Added: calcite/site/avatica/target/docs/howto.html URL: http://svn.apache.org/viewvc/calcite/site/avatica/target/docs/howto.html?rev=1733977&view=auto ============================================================================== --- calcite/site/avatica/target/docs/howto.html (added) +++ calcite/site/avatica/target/docs/howto.html Mon Mar 7 20:23:21 2016 @@ -0,0 +1,1421 @@ +<!DOCTYPE HTML> +<html lang="en-US"> +<head> + <meta charset="UTF-8"> + <title>HOWTO</title> + <meta name="viewport" content="width=device-width,initial-scale=1"> + <meta name="generator" content="Jekyll v3.0.3"> + <link rel="stylesheet" href="//fonts.googleapis.com/css?family=Lato:300,300italic,400,400italic,700,700italic,900"> + <link rel="stylesheet" href="/avatica/css/screen.css"> + <link rel="icon" type="image/x-icon" href="/avatica/favicon.ico"> + <!--[if lt IE 9]> + <script src="/js/html5shiv.min.js"></script> + <script src="/js/respond.min.js"></script> + <![endif]--> +</head> + + +<body class="wrap"> + <header role="banner"> + <nav class="mobile-nav show-on-mobiles"> + <ul> + <li class=""> + <a href="/avatica/">Home</a> + </li> + <li class=""> + <a href="/avatica/downloads/">Download</a> + </li> + <li class=""> + <a href="/avatica/community/">Community</a> + </li> + <li class=""> + <a href="/avatica/develop/">Develop</a> + </li> + <li class=""> + <a href="/avatica/news/">News</a> + </li> + <li class="current"> + <a href="/avatica/docs/">Docs</a> + </li> +</ul> + + </nav> + <div class="grid"> + <div class="unit one-third center-on-mobiles"> + <h1> + <a href="/avatica/.."> + <span class="sr-only">Apache Calcite Avatica</span> + <img src="/avatica/img/logo.png" width="226" height="140" alt="Calcite Logo"> + </a> + </h1> + </div> + <nav class="main-nav unit two-thirds hide-on-mobiles"> + <ul> + <li class=""> + <a href="/avatica/">Home</a> + </li> + <li class=""> + <a href="/avatica/downloads/">Download</a> + </li> + <li class=""> + <a href="/avatica/community/">Community</a> + </li> + <li class=""> + <a href="/avatica/develop/">Develop</a> + </li> + <li class=""> + <a href="/avatica/news/">News</a> + </li> + <li class="current"> + <a href="/avatica/docs/">Docs</a> + </li> +</ul> + + </nav> + </div> +</header> + + + <section class="docs"> + <div class="grid"> + + <div class="docs-nav-mobile unit whole show-on-mobiles"> + <select onchange="if (this.value) window.location.href=this.value"> + <option value="">Navigate the docsâ¦</option> + + <optgroup label="Overview"> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + </optgroup> + + <optgroup label="Reference"> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + </optgroup> + + <optgroup label="Meta"> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + </optgroup> + + </select> +</div> + + + <div class="unit four-fifths"> + <article> + <h1>HOWTO</h1> + <!-- + +--> + +<p>Hereâs some miscellaneous documentation about using Calcite and its various +adapters.</p> + +<ul id="markdown-toc"> + <li><a href="#building-from-a-source-distribution" id="markdown-toc-building-from-a-source-distribution">Building from a source distribution</a></li> + <li><a href="#building-from-git" id="markdown-toc-building-from-git">Building from git</a></li> + <li><a href="#running-tests" id="markdown-toc-running-tests">Running tests</a></li> + <li><a href="#running-integration-tests" id="markdown-toc-running-integration-tests">Running integration tests</a> <ul> + <li><a href="#vm-preparation" id="markdown-toc-vm-preparation">VM preparation</a></li> + <li><a href="#vm-management" id="markdown-toc-vm-management">VM management</a></li> + <li><a href="#suggested-test-flow" id="markdown-toc-suggested-test-flow">Suggested test flow</a></li> + <li><a href="#integration-tests-technical-details" id="markdown-toc-integration-tests-technical-details">Integration tests technical details</a></li> + </ul> + </li> + <li><a href="#contributing" id="markdown-toc-contributing">Contributing</a></li> + <li><a href="#getting-started" id="markdown-toc-getting-started">Getting started</a></li> + <li><a href="#tracing" id="markdown-toc-tracing">Tracing</a></li> + <li><a href="#csv-adapter" id="markdown-toc-csv-adapter">CSV adapter</a></li> + <li><a href="#mongodb-adapter" id="markdown-toc-mongodb-adapter">MongoDB adapter</a></li> + <li><a href="#splunk-adapter" id="markdown-toc-splunk-adapter">Splunk adapter</a></li> + <li><a href="#implementing-an-adapter" id="markdown-toc-implementing-an-adapter">Implementing an adapter</a> <ul> + <li><a href="#testing-adapter-in-java" id="markdown-toc-testing-adapter-in-java">Testing adapter in Java</a></li> + </ul> + </li> + <li><a href="#advanced-topics-for-developers" id="markdown-toc-advanced-topics-for-developers">Advanced topics for developers</a> <ul> + <li><a href="#javatypefactory" id="markdown-toc-javatypefactory">JavaTypeFactory</a></li> + <li><a href="#rebuilding-generated-protocol-buffer-code" id="markdown-toc-rebuilding-generated-protocol-buffer-code">Rebuilding generated Protocol Buffer code</a></li> + </ul> + </li> + <li><a href="#advanced-topics-for-committers" id="markdown-toc-advanced-topics-for-committers">Advanced topics for committers</a> <ul> + <li><a href="#set-up-pgp-signing-keys-for-calcite-committers" id="markdown-toc-set-up-pgp-signing-keys-for-calcite-committers">Set up PGP signing keys (for Calcite committers)</a></li> + <li><a href="#making-a-snapshot-for-calcite-committers" id="markdown-toc-making-a-snapshot-for-calcite-committers">Making a snapshot (for Calcite committers)</a></li> + <li><a href="#making-a-release-for-calcite-committers" id="markdown-toc-making-a-release-for-calcite-committers">Making a release (for Calcite committers)</a></li> + <li><a href="#cleaning-up-after-a-failed-release-attempt-for-calcite-committers" id="markdown-toc-cleaning-up-after-a-failed-release-attempt-for-calcite-committers">Cleaning up after a failed release attempt (for Calcite committers)</a></li> + <li><a href="#validate-a-release" id="markdown-toc-validate-a-release">Validate a release</a></li> + <li><a href="#get-approval-for-a-release-via-apache-voting-process-for-calcite-committers" id="markdown-toc-get-approval-for-a-release-via-apache-voting-process-for-calcite-committers">Get approval for a release via Apache voting process (for Calcite committers)</a></li> + <li><a href="#publishing-a-release-for-calcite-committers" id="markdown-toc-publishing-a-release-for-calcite-committers">Publishing a release (for Calcite committers)</a></li> + <li><a href="#publish-the-web-site" id="markdown-toc-publish-the-web-site">Publishing the web site (for Calcite committers)</a></li> + </ul> + </li> +</ul> + +<h2 id="building-from-a-source-distribution">Building from a source distribution</h2> + +<p>Prerequisites are maven (3.2.1 or later) +and Java (JDK 1.7 or later, 1.8 preferred) on your path.</p> + +<p>Unpack the source distribution <code class="highlighter-rouge">.tar.gz</code> or <code class="highlighter-rouge">.zip</code> file, +<code class="highlighter-rouge">cd</code> to the root directory of the unpacked source, +then build using maven:</p> + +<figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="gp">$ </span>tar xvfz calcite-1.6.0-source.tar.gz +<span class="gp">$ </span><span class="nb">cd </span>calcite-1.6.0 +<span class="gp">$ </span>mvn install</code></pre></figure> + +<p><a href="#running-tests">Running tests</a> describes how to run more or fewer +tests.</p> + +<h2 id="building-from-git">Building from git</h2> + +<p>Prerequisites are git, maven (3.2.1 or later) +and Java (JDK 1.7 or later, 1.8 preferred) on your path.</p> + +<p>Create a local copy of the github repository, +<code class="highlighter-rouge">cd</code> to its root directory, +then build using maven:</p> + +<figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="gp">$ </span>git clone git://github.com/apache/calcite.git +<span class="gp">$ </span><span class="nb">cd </span>calcite +<span class="gp">$ </span>mvn install</code></pre></figure> + +<p>Calcite includes a number of machine-generated codes. By default, these are +regenerated on every build, but this has the negative side-effect of causing +a re-compilation of the entire project when the non-machine-generated code +has not changed. To make sure incremental compilation still works as intended, +provide the <code class="highlighter-rouge">skipGenerate</code> command line option with your maven command. +If you invoke the <code class="highlighter-rouge">clean</code> lifecycle phase, you must not specify the +<code class="highlighter-rouge">skipGenerate</code> option as it will not recompile the necessary code for the build +to succeed.</p> + +<figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="gp">$ </span>mvn clean +<span class="gp">$ </span>mvn package +... hacks ... +<span class="gp">$ </span>mvn package -DskipGenerate</code></pre></figure> + +<p><a href="#running-tests">Running tests</a> describes how to run more or fewer +tests.</p> + +<h2 id="running-tests">Running tests</h2> + +<p>The test suite will run by default when you build, unless you specify +<code class="highlighter-rouge">-DskipTests</code>:</p> + +<figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="gp">$ </span>mvn -DskipTests clean install +<span class="gp">$ </span>mvn <span class="nb">test</span></code></pre></figure> + +<p>There are other options that control which tests are run, and in what +environment, as follows.</p> + +<ul> + <li><code class="highlighter-rouge">-Dcalcite.test.db=DB</code> (where db is <code class="highlighter-rouge">h2</code>, <code class="highlighter-rouge">hsqldb</code>, <code class="highlighter-rouge">mysql</code>, or <code class="highlighter-rouge">postgresql</code>) allows you +to change the JDBC data source for the test suite. Calciteâs test +suite requires a JDBC data source populated with the foodmart data +set. + <ul> + <li><code class="highlighter-rouge">hsqldb</code>, the default, uses an in-memory hsqldb database.</li> + <li>All others access a test virtual machine +(see <a href="#running-integration-tests">integration tests</a> below). +<code class="highlighter-rouge">mysql</code> and <code class="highlighter-rouge">postgresql</code> might be somewhat faster than hsqldb, but you need +to populate it (i.e. provision a VM).</li> + </ul> + </li> + <li><code class="highlighter-rouge">-Dcalcite.debug</code> prints extra debugging information to stdout.</li> + <li><code class="highlighter-rouge">-Dcalcite.test.slow</code> enables tests that take longer to execute. For +example, there are tests that create virtual TPC-H and TPC-DS schemas +in-memory and run tests from those benchmarks.</li> + <li><code class="highlighter-rouge">-Dcalcite.test.splunk</code> enables tests that run against Splunk. +Splunk must be installed and running.</li> +</ul> + +<h2 id="running-integration-tests">Running integration tests</h2> + +<p>For testing Calciteâs external adapters, a test virtual machine should be used. +The VM includes H2, HSQLDB, MySQL, MongoDB, and PostgreSQL.</p> + +<p>Test VM requires 5GiB of disk space and it takes 30 minutes to build.</p> + +<p>Note: you can use <a href="https://github.com/vlsi/calcite-test-dataset";>calcite-test-dataset</a> + to populate your own database, however it is recommended to use test VM so the test environment can be reproduced.</p> + +<h3 id="vm-preparation">VM preparation</h3> + +<p>0) Install dependencies: <a href="https://www.vagrantup.com/";>Vagrant</a> and <a href="https://www.virtualbox.org/";>VirtualBox</a></p> + +<p>1) Clone https://github.com/vlsi/calcite-test-dataset.git at the same level as calcite repository. +For instance:</p> + +<figure class="highlight"><pre><code class="language-bash" data-lang="bash">code + +-- calcite + +-- calcite-test-dataset</code></pre></figure> + +<p>Note: integration tests search for ../calcite-test-dataset or ../../calcite-test-dataset. + You can specify full path via calcite.test.dataset system property.</p> + +<p>2) Build and start the VM:</p> + +<figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="nb">cd </span>calcite-test-dataset <span class="o">&&</span> mvn install</code></pre></figure> + +<h3 id="vm-management">VM management</h3> + +<p>Test VM is provisioned by Vagrant, so regular Vagrant <code class="highlighter-rouge">vagrant up</code> and <code class="highlighter-rouge">vagrant halt</code> should be used to start and stop the VM. +The connection strings for different databases are listed in <a href="https://github.com/vlsi/calcite-test-dataset";>calcite-test-dataset</a> readme.</p> + +<h3 id="suggested-test-flow">Suggested test flow</h3> + +<p>Note: test VM should be started before you launch integration tests. Calcite itself does not start/stop the VM.</p> + +<p>Command line:</p> + +<ul> + <li>Executing regular unit tests (does not require external data): no change. <code class="highlighter-rouge">mvn test</code> or <code class="highlighter-rouge">mvn install</code>.</li> + <li>Executing all tests, for all the DBs: <code class="highlighter-rouge">mvn verify -Pit</code>. <code class="highlighter-rouge">it</code> stands for âintegration-testâ. <code class="highlighter-rouge">mvn install -Pit</code> works as well.</li> + <li>Executing just tests for external DBs, excluding unit tests: <code class="highlighter-rouge">mvn -Dtest=foo -DfailIfNoTests=false -Pit verify</code></li> + <li>Executing just MongoDB tests: <code class="highlighter-rouge">cd mongo; mvn verify -Pit</code></li> +</ul> + +<p>From within IDE:</p> + +<ul> + <li>Executing regular unit tests: no change.</li> + <li>Executing MongoDB tests: run <code class="highlighter-rouge">MongoAdapterIT.java</code> as usual (no additional properties are required)</li> + <li>Executing MySQL tests: run <code class="highlighter-rouge">JdbcTest</code> and <code class="highlighter-rouge">JdbcAdapterTest</code> with setting <code class="highlighter-rouge">-Dcalcite.test.db=mysql</code></li> + <li>Executing PostgreSQL tests: run <code class="highlighter-rouge">JdbcTest</code> and <code class="highlighter-rouge">JdbcAdapterTest</code> with setting <code class="highlighter-rouge">-Dcalcite.test.db=postgresql</code></li> +</ul> + +<h3 id="integration-tests-technical-details">Integration tests technical details</h3> + +<p>Tests with external data are executed at mavenâs integration-test phase. +We do not currently use pre-integration-test/post-integration-test, however we could use that in future. +The verification of build pass/failure is performed at verify phase. +Integration tests should be named <code class="highlighter-rouge">...IT.java</code>, so they are not picked up on unit test execution.</p> + +<h2 id="contributing">Contributing</h2> + +<p>See the <a href="/avatica/develop/#contributing">developers guide</a>.</p> + +<h2 id="getting-started">Getting started</h2> + +<p>See the <a href="/avatica/develop/#getting-started">developers guide</a>.</p> + +<h2 id="tracing">Tracing</h2> + +<p>To enable tracing, add the following flags to the java command line:</p> + +<p><code class="highlighter-rouge">-Dcalcite.debug=true</code></p> + +<p>The first flag causes Calcite to print the Java code it generates +(to execute queries) to stdout. It is especially useful if you are debugging +mysterious problems like this:</p> + +<p><code class="highlighter-rouge">Exception in thread "main" java.lang.ClassCastException: Integer cannot be cast to Long + at Baz$1$1.current(Unknown Source)</code></p> + +<p>By default, Calcite uses the Log4j bindings for SLF4J. There is a provided configuration +file which outputs logging at the INFO level to the console in <code class="highlighter-rouge">core/src/test/resources/log4j.properties</code>. +You can modify the level for the rootLogger to increase verbosity or change the level +for a specific class if you so choose.</p> + +<figure class="highlight"><pre><code class="language-properties" data-lang="properties"><span class="c"># Change rootLogger level to WARN +</span><span class="py">log4j.rootLogger</span><span class="p">=</span><span class="s">WARN, A1</span> +<span class="c"># Increase level to DEBUG for RelOptPlanner +</span><span class="py">log4j.logger.org.apache.calcite.plan.RelOptPlanner</span><span class="p">=</span><span class="s">DEBUG</span> +<span class="c"># Increase level to TRACE for HepPlanner +</span><span class="py">log4j.logger.org.apache.calcite.plan.hep.HepPlanner</span><span class="p">=</span><span class="s">TRACE</span></code></pre></figure> + +<h2 id="csv-adapter">CSV adapter</h2> + +<p>See the <a href="/docs/tutorial.html">tutorial</a>.</p> + +<h2 id="mongodb-adapter">MongoDB adapter</h2> + +<p>First, download and install Calcite, +and <a href="http://www.mongodb.org/downloads";>install MongoDB</a>.</p> + +<p>Note: you can use MongoDB from integration test virtual machine above.</p> + +<p>Import MongoDBâs zipcode data set into MongoDB:</p> + +<figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="gp">$ </span>curl -o /tmp/zips.json http://media.mongodb.org/zips.json +<span class="gp">$ </span>mongoimport --db <span class="nb">test</span> --collection zips --file /tmp/zips.json +Tue Jun 4 16:24:14.190 check 9 29470 +Tue Jun 4 16:24:14.469 imported 29470 objects</code></pre></figure> + +<p>Log into MongoDB to check itâs there:</p> + +<figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="gp">$ </span>mongo +MongoDB shell version: 2.4.3 +connecting to: <span class="nb">test</span> +<span class="gp">> </span>db.zips.find<span class="o">()</span>.limit<span class="o">(</span>3<span class="o">)</span> +<span class="o">{</span> <span class="s2">"city"</span> : <span class="s2">"ACMAR"</span>, <span class="s2">"loc"</span> : <span class="o">[</span> -86.51557, 33.584132 <span class="o">]</span>, <span class="s2">"pop"</span> : 6055, <span class="s2">"state"</span> : <span class="s2">"AL"</span>, <span class="s2">"_id"</span> : <span class="s2">"35004"</span> <span class="o">}</span> +<span class="o">{</span> <span class="s2">"city"</span> : <span class="s2">"ADAMSVILLE"</span>, <span class="s2">"loc"</span> : <span class="o">[</span> -86.959727, 33.588437 <span class="o">]</span>, <span class="s2">"pop"</span> : 10616, <span class="s2">"state"</span> : <span class="s2">"AL"</span>, <span class="s2">"_id"</span> : <span class="s2">"35005"</span> <span class="o">}</span> +<span class="o">{</span> <span class="s2">"city"</span> : <span class="s2">"ADGER"</span>, <span class="s2">"loc"</span> : <span class="o">[</span> -87.167455, 33.434277 <span class="o">]</span>, <span class="s2">"pop"</span> : 3205, <span class="s2">"state"</span> : <span class="s2">"AL"</span>, <span class="s2">"_id"</span> : <span class="s2">"35006"</span> <span class="o">}</span> +<span class="gp">> </span><span class="nb">exit +</span>bye</code></pre></figure> + +<p>Connect using the +<a href="https://github.com/apache/calcite/tree/master/avatica/mongodb/src/test/resources/mongo-zips-model.json";>mongo-zips-model.json</a> +Calcite model:</p> + +<figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="gp">$ </span>./sqlline +<span class="gp">sqlline> </span>!connect jdbc:calcite:model<span class="o">=</span>mongodb/target/test-classes/mongo-zips-model.json admin admin +Connecting to jdbc:calcite:model<span class="o">=</span>mongodb/target/test-classes/mongo-zips-model.json +Connected to: Calcite <span class="o">(</span>version 1.x.x<span class="o">)</span> +Driver: Calcite JDBC Driver <span class="o">(</span>version 1.x.x<span class="o">)</span> +Autocommit status: <span class="nb">true +</span>Transaction isolation: TRANSACTION_REPEATABLE_READ +<span class="gp">sqlline> </span>!tables ++------------+--------------+-----------------+---------------+ +| TABLE_CAT | TABLE_SCHEM | TABLE_NAME | TABLE_TYPE | ++------------+--------------+-----------------+---------------+ +| null | mongo_raw | zips | TABLE | +| null | mongo_raw | system.indexes | TABLE | +| null | mongo | ZIPS | VIEW | +| null | metadata | COLUMNS | SYSTEM_TABLE | +| null | metadata | TABLES | SYSTEM_TABLE | ++------------+--------------+-----------------+---------------+ +<span class="gp">sqlline> </span><span class="k">select </span>count<span class="o">(</span><span class="k">*</span><span class="o">)</span> from zips; ++---------+ +| EXPR<span class="nv">$0</span> | ++---------+ +| 29467 | ++---------+ +1 row selected <span class="o">(</span>0.746 seconds<span class="o">)</span> +<span class="gp">sqlline> </span>!quit +Closing: org.apache.calcite.jdbc.FactoryJdbc41<span class="nv">$CalciteConnectionJdbc41</span> +<span class="err">$</span></code></pre></figure> + +<h2 id="splunk-adapter">Splunk adapter</h2> + +<p>To run the test suite and sample queries against Splunk, +load Splunkâs <code class="highlighter-rouge">tutorialdata.zip</code> data set as described in +<a href="http://docs.splunk.com/Documentation/Splunk/6.0.2/PivotTutorial/GetthetutorialdataintoSplunk";>the Splunk tutorial</a>.</p> + +<p>(This step is optional, but it provides some interesting data for the sample +queries. It is also necessary if you intend to run the test suite, using +<code class="highlighter-rouge">-Dcalcite.test.splunk=true</code>.)</p> + +<h2 id="implementing-an-adapter">Implementing an adapter</h2> + +<p>New adapters can be created by implementing <code class="highlighter-rouge">CalcitePrepare.Context</code>:</p> + +<figure class="highlight"><pre><code class="language-java" data-lang="java"><span class="kn">import</span> <span class="nn">org.apache.calcite.adapter.java.JavaTypeFactory</span><span class="o">;</span> +<span class="kn">import</span> <span class="nn">org.apache.calcite.jdbc.CalcitePrepare</span><span class="o">;</span> +<span class="kn">import</span> <span class="nn">org.apache.calcite.jdbc.CalciteSchema</span><span class="o">;</span> + +<span class="kd">public</span> <span class="kd">class</span> <span class="nc">AdapterContext</span> <span class="kd">implements</span> <span class="n">CalcitePrepare</span><span class="o">.</span><span class="na">Context</span> <span class="o">{</span> + <span class="nd">@Override</span> + <span class="kd">public</span> <span class="n">JavaTypeFactory</span> <span class="n">getTypeFactory</span><span class="o">()</span> <span class="o">{</span> + <span class="c1">// adapter implementation</span> + <span class="k">return</span> <span class="n">typeFactory</span><span class="o">;</span> + <span class="o">}</span> + + <span class="nd">@Override</span> + <span class="kd">public</span> <span class="n">CalciteSchema</span> <span class="n">getRootSchema</span><span class="o">()</span> <span class="o">{</span> + <span class="c1">// adapter implementation</span> + <span class="k">return</span> <span class="n">rootSchema</span><span class="o">;</span> + <span class="o">}</span> +<span class="o">}</span></code></pre></figure> + +<h3 id="testing-adapter-in-java">Testing adapter in Java</h3> + +<p>The example below shows how SQL query can be submitted to +<code class="highlighter-rouge">CalcitePrepare</code> with a custom context (<code class="highlighter-rouge">AdapterContext</code> in this +case). Calcite prepares and implements the query execution, using the +resources provided by the <code class="highlighter-rouge">Context</code>. <code class="highlighter-rouge">CalcitePrepare.PrepareResult</code> +provides access to the underlying enumerable and methods for +enumeration. The enumerable itself can naturally be some adapter +specific implementation.</p> + +<figure class="highlight"><pre><code class="language-java" data-lang="java"><span class="kn">import</span> <span class="nn">org.apache.calcite.jdbc.CalcitePrepare</span><span class="o">;</span> +<span class="kn">import</span> <span class="nn">org.apache.calcite.prepare.CalcitePrepareImpl</span><span class="o">;</span> +<span class="kn">import</span> <span class="nn">org.junit.Test</span><span class="o">;</span> + +<span class="kd">public</span> <span class="kd">class</span> <span class="nc">AdapterContextTest</span> <span class="o">{</span> + <span class="nd">@Test</span> + <span class="kd">public</span> <span class="kt">void</span> <span class="n">testSelectAllFromTable</span><span class="o">()</span> <span class="o">{</span> + <span class="n">AdapterContext</span> <span class="n">ctx</span> <span class="o">=</span> <span class="k">new</span> <span class="n">AdapterContext</span><span class="o">();</span> + <span class="n">String</span> <span class="n">sql</span> <span class="o">=</span> <span class="s">"SELECT * FROM TABLENAME"</span><span class="o">;</span> + <span class="n">Class</span> <span class="n">elementType</span> <span class="o">=</span> <span class="n">Object</span><span class="o">[].</span><span class="na">class</span><span class="o">;</span> + <span class="n">CalcitePrepare</span><span class="o">.</span><span class="na">PrepareResult</span><span class="o"><</span><span class="n">Object</span><span class="o">></span> <span class="n">prepared</span> <span class="o">=</span> + <span class="k">new</span> <span class="n">CalcitePrepareImpl</span><span class="o">().</span><span class="na">prepareSql</span><span class="o">(</span><span class="n">ctx</span><span class="o">,</span> <span class="n">sql</span><span class="o">,</span> <span class="kc">null</span><span class="o">,</span> <span class="n">elementType</span><span class="o">,</span> <span class="o">-</span><span class="mi">1</span><span class="o">);</span> + <span class="n">Object</span> <span class="n">enumerable</span> <span class="o">=</span> <span class="n">prepared</span><span class="o">.</span><span class="na">getExecutable</span><span class="o">();</span> + <span class="c1">// etc.</span> + <span class="o">}</span> +<span class="o">}</span></code></pre></figure> + +<h1 id="advanced-topics-for-developers">Advanced topics for developers</h1> + +<p>The following sections might be of interest if you are adding features +to particular parts of the code base. You donât need to understand +these topics if you are just building from source and running tests.</p> + +<h2 id="javatypefactory">JavaTypeFactory</h2> + +<p>When Calcite compares types (instances of <code class="highlighter-rouge">RelDataType</code>), it requires them to be the same +object. If there are two distinct type instances that refer to the +same Java type, Calcite may fail to recognize that they match. It is +recommended to:</p> + +<ul> + <li>Use a single instance of <code class="highlighter-rouge">JavaTypeFactory</code> within the calcite context;</li> + <li>Store the types so that the same object is always returned for the same type.</li> +</ul> + +<h2 id="rebuilding-generated-protocol-buffer-code">Rebuilding generated Protocol Buffer code</h2> + +<p>Calciteâs Avatica Server component supports RPC serialization +using <a href="https://developers.google.com/protocol-buffers/";>Protocol Buffers</a>. +In the context of Avatica, Protocol Buffers can +generate a collection of messages defined by a schema. The library +itself can parse old serialized messages using a +new schema. This is highly desirable in an environment where the +client and server are not guaranteed to have the same version of +objects.</p> + +<p>Typically, the code generated by the Protocol Buffers library doesnât +need to be re-generated only every build, only when the schema changes.</p> + +<p>First, install Protobuf 3.0:</p> + +<figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="gp">$ </span>wget https://github.com/google/protobuf/releases/download/v3.0.0-beta-1/protobuf-java-3.0.0-beta-1.tar.gz +<span class="gp">$ </span>tar xf protobuf-java-3.0.0-beta-1.tar.gz <span class="o">&&</span> <span class="nb">cd </span>protobuf-3.0.0-beta-1 +<span class="gp">$ </span>./configure +<span class="gp">$ </span>make +<span class="gp">$ </span>sudo make install</code></pre></figure> + +<p>Then, re-generate the compiled code:</p> + +<figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="gp">$ </span><span class="nb">cd </span>avatica +<span class="gp">$ </span>./src/main/scripts/generate-protobuf.sh</code></pre></figure> + +<h1 id="advanced-topics-for-committers">Advanced topics for committers</h1> + +<p>The following sections are of interest to Calcite committers and in +particular release managers.</p> + +<h2 id="set-up-pgp-signing-keys-for-calcite-committers">Set up PGP signing keys (for Calcite committers)</h2> + +<p>Follow instructions <a href="http://www.apache.org/dev/release-signing";>here</a> to +create a key pair. (On Mac OS X, I did <code class="highlighter-rouge">brew install gpg</code> and +<code class="highlighter-rouge">gpg --gen-key</code>.)</p> + +<p>Add your public key to the <code class="highlighter-rouge">KEYS</code> file by following instructions in +the <code class="highlighter-rouge">KEYS</code> file.</p> + +<h2 id="making-a-snapshot-for-calcite-committers">Making a snapshot (for Calcite committers)</h2> + +<p>Before you start:</p> + +<ul> + <li>Set up signing keys as described above.</li> + <li>Make sure you are using JDK 1.7 (not 1.8).</li> + <li>Make sure build and tests succeed with <code class="highlighter-rouge">-Dcalcite.test.db=hsqldb</code> (the default)</li> +</ul> + +<figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="c"># Set passphrase variable without putting it into shell history</span> +<span class="nb">read</span> -s GPG_PASSPHRASE + +<span class="c"># Make sure that there are no junk files in the sandbox</span> +git clean -xn +mvn clean + +mvn -Papache-release -Dgpg.passphrase<span class="o">=</span><span class="k">${</span><span class="nv">GPG_PASSPHRASE</span><span class="k">}</span> install</code></pre></figure> + +<p>When the dry-run has succeeded, change <code class="highlighter-rouge">install</code> to <code class="highlighter-rouge">deploy</code>.</p> + +<h2 id="making-a-release-for-calcite-committers">Making a release (for Calcite committers)</h2> + +<p>Before you start:</p> + +<ul> + <li>Set up signing keys as described above.</li> + <li>Make sure you are using JDK 1.7 (not 1.8).</li> + <li>Check that <code class="highlighter-rouge">README</code> and <code class="highlighter-rouge">site/_docs/howto.md</code> have the correct version number.</li> + <li>Set <code class="highlighter-rouge">version.major</code> and <code class="highlighter-rouge">version.minor</code> in <code class="highlighter-rouge">pom.xml</code>.</li> + <li>Make sure build and tests succeed, including with +-Dcalcite.test.db={mysql,hsqldb}, -Dcalcite.test.slow, +-Dcalcite.test.mongodb, -Dcalcite.test.splunk.</li> + <li>Trigger a +<a href="https://scan.coverity.com/projects/2966";>Coverity scan</a> +by merging the latest code into the <code class="highlighter-rouge">julianhyde/coverity_scan</code> branch, +and when it completes, make sure that there are no important issues.</li> + <li>Make sure that +<a href="https://issues.apache.org/jira/issues/?jql=project%20%3D%20CALCITE%20AND%20status%20%3D%20Resolved%20and%20fixVersion%20is%20null";> +every âresolvedâ JIRA case</a> (including duplicates) has +a fix version assigned (most likely the version we are +just about to release)</li> +</ul> + +<p>Create a release branch named after the release, e.g. <code class="highlighter-rouge">branch-1.1</code>, and push it to Apache.</p> + +<figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="gp">$ </span>git checkout -b branch-X.Y +<span class="gp">$ </span>git push -u origin branch-X.Y</code></pre></figure> + +<p>We will use the branch for the entire the release process. Meanwhile, +we do not allow commits to the master branch. After the release is +final, we can use <code class="highlighter-rouge">git merge --ff-only</code> to append the changes on the +release branch onto the master branch. (Apache does not allow reverts +to the master branch, which makes it difficult to clean up the kind of +messy commits that inevitably happen while you are trying to finalize +a release.)</p> + +<p>Now, set up your environment and do a dry run. The dry run will not +commit any changes back to git and gives you the opportunity to verify +that the release process will complete as expected.</p> + +<p>If any of the steps fail, clean up (see below), fix the problem, and +start again from the top.</p> + +<figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="c"># Set passphrase variable without putting it into shell history</span> +<span class="nb">read</span> -s GPG_PASSPHRASE + +<span class="c"># Make sure that there are no junk files in the sandbox</span> +git clean -xn +mvn clean + +<span class="c"># Do a dry run of the release:prepare step, which sets version numbers.</span> +mvn -DdryRun<span class="o">=</span><span class="nb">true</span> -DskipTests -DreleaseVersion<span class="o">=</span>X.Y.Z -DdevelopmentVersion<span class="o">=</span>X.Y.Z+1-SNAPSHOT -Papache-release -Darguments<span class="o">=</span><span class="s2">"-Dgpg.passphrase=</span><span class="k">${</span><span class="nv">GPG_PASSPHRASE</span><span class="k">}</span><span class="s2">"</span> release:prepare 2>&1 | tee /tmp/prepare-dry.log</code></pre></figure> + +<p>Check the artifacts:</p> + +<ul> + <li>In the <code class="highlighter-rouge">target</code> directory should be these 8 files, among others: + <ul> + <li>apache-calcite-X.Y.Z-src.tar.gz</li> + <li>apache-calcite-X.Y.Z-src.tar.gz.asc</li> + <li>apache-calcite-X.Y.Z-src.tar.gz.md5</li> + <li>apache-calcite-X.Y.Z-src.tar.gz.sha1</li> + <li>apache-calcite-X.Y.Z-src.zip</li> + <li>apache-calcite-X.Y.Z-src.zip.asc</li> + <li>apache-calcite-X.Y.Z-src.zip.md5</li> + <li>apache-calcite-X.Y.Z-src.zip.sha1</li> + </ul> + </li> + <li>Note that the file names start <code class="highlighter-rouge">apache-calcite-</code>.</li> + <li>In the two source distros <code class="highlighter-rouge">.tar.gz</code> and <code class="highlighter-rouge">.zip</code> (currently there is +no binary distro), check that all files belong to a directory called +<code class="highlighter-rouge">apache-calcite-X.Y.Z-src</code>.</li> + <li>That directory must contain files <code class="highlighter-rouge">NOTICE</code>, <code class="highlighter-rouge">LICENSE</code>, +<code class="highlighter-rouge">README</code>, <code class="highlighter-rouge">README.md</code> + <ul> + <li>Check that the version in <code class="highlighter-rouge">README</code> is correct</li> + </ul> + </li> + <li>In each .jar (for example +<code class="highlighter-rouge">core/target/calcite-core-X.Y.Z.jar</code> and +<code class="highlighter-rouge">mongodb/target/calcite-mongodb-X.Y.Z-sources.jar</code>), check +that the <code class="highlighter-rouge">META-INF</code> directory contains <code class="highlighter-rouge">DEPENDENCIES</code>, <code class="highlighter-rouge">LICENSE</code>, +<code class="highlighter-rouge">NOTICE</code> and <code class="highlighter-rouge">git.properties</code></li> + <li>In each .jar, check that <code class="highlighter-rouge">org-apache-calcite-jdbc.properties</code> is +present and does not contain un-substituted <code class="highlighter-rouge">${...}</code> variables</li> + <li>Check PGP, per <a href="https://httpd.apache.org/dev/verification.html";>this</a></li> +</ul> + +<p>Now, remove the <code class="highlighter-rouge">-DdryRun</code> flag and run the release for real.</p> + +<figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="c"># Prepare sets the version numbers, creates a tag, and pushes it to git.</span> +mvn -DdryRun<span class="o">=</span><span class="nb">false</span> -DskipTests -DreleaseVersion<span class="o">=</span>X.Y.Z -DdevelopmentVersion<span class="o">=</span>X.Y.Z+1-SNAPSHOT -Papache-release -Darguments<span class="o">=</span><span class="s2">"-Dgpg.passphrase=</span><span class="k">${</span><span class="nv">GPG_PASSPHRASE</span><span class="k">}</span><span class="s2">"</span> release:prepare 2>&1 | tee /tmp/prepare.log + +<span class="c"># Perform checks out the tagged version, builds, and deploys to the staging repository</span> +mvn -DskipTests -Papache-release -Darguments<span class="o">=</span><span class="s2">"-Dgpg.passphrase=</span><span class="k">${</span><span class="nv">GPG_PASSPHRASE</span><span class="k">}</span><span class="s2">"</span> release:perform 2>&1 | tee /tmp/perform.log</code></pre></figure> + +<p>Verify the staged artifacts in the Nexus repository:</p> + +<ul> + <li>Go to <a href="https://repository.apache.org/";>https://repository.apache.org/</a> and login</li> + <li>Under <code class="highlighter-rouge">Build Promotion</code>, click <code class="highlighter-rouge">Staging Repositories</code></li> + <li>In the <code class="highlighter-rouge">Staging Repositories</code> tab there should be a line with profile <code class="highlighter-rouge">org.apache.calcite</code></li> + <li>Navigate through the artifact tree and make sure the .jar, .pom, .asc files are present</li> + <li>Check the box on in the first column of the row, +and press the âCloseâ button to publish the repository at +https://repository.apache.org/content/repositories/orgapachecalcite-1000 +(or a similar URL)</li> +</ul> + +<p>Upload the artifacts via subversion to a staging area, +https://dist.apache.org/repos/dist/dev/calcite/apache-calcite-X.Y.Z-rcN:</p> + +<figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="c"># Create a subversion workspace, if you haven't already</span> +mkdir -p ~/dist/dev +<span class="nb">pushd</span> ~/dist/dev +svn co https://dist.apache.org/repos/dist/dev/calcite +<span class="nb">popd</span> + +<span class="c"># Move the files into a directory</span> +<span class="nb">cd </span>target +mkdir ~/dist/dev/calcite/apache-calcite-X.Y.Z-rcN +mv apache-calcite-<span class="k">*</span> ~/dist/dev/calcite/apache-calcite-X.Y.Z-rcN + +<span class="c"># Check in</span> +<span class="nb">cd</span> ~/dist/dev/calcite +svn add apache-calcite-X.Y.Z-rcN +svn ci</code></pre></figure> + +<h2 id="cleaning-up-after-a-failed-release-attempt-for-calcite-committers">Cleaning up after a failed release attempt (for Calcite committers)</h2> + +<figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="c"># Make sure that the tag you are about to generate does not already</span> +<span class="c"># exist (due to a failed release attempt)</span> +git tag + +<span class="c"># If the tag exists, delete it locally and remotely</span> +git tag -d apache-calcite-X.Y.Z +git push origin :refs/tags/apache-calcite-X.Y.Z + +<span class="c"># Remove modified files</span> +mvn release:clean + +<span class="c"># Check whether there are modified files and if so, go back to the</span> +<span class="c"># original git commit</span> +git status +git reset --hard HEAD</code></pre></figure> + +<h2 id="validate-a-release">Validate a release</h2> + +<figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="c"># Check that the signing key (e.g. 2AD3FAE3) is pushed</span> +gpg --recv-keys key + +<span class="c"># Check keys</span> +curl -O https://dist.apache.org/repos/dist/release/calcite/KEYS + +<span class="c"># Sign/check md5 and sha1 hashes</span> +<span class="c"># (Assumes your O/S has 'md5' and 'sha1' commands.)</span> +<span class="k">function </span>checkHash<span class="o">()</span> <span class="o">{</span> + <span class="nb">cd</span> <span class="s2">"</span><span class="nv">$1</span><span class="s2">"</span> + <span class="k">for </span>i <span class="k">in</span> <span class="k">*</span>.<span class="o">{</span>zip,pom,gz<span class="o">}</span>; <span class="k">do + if</span> <span class="o">[</span> ! -f <span class="nv">$i</span> <span class="o">]</span>; <span class="k">then + continue + fi + if</span> <span class="o">[</span> -f <span class="nv">$i</span>.md5 <span class="o">]</span>; <span class="k">then + if</span> <span class="o">[</span> <span class="s2">"</span><span class="k">$(</span>cat <span class="nv">$i</span>.md5<span class="k">)</span><span class="s2">"</span> <span class="o">=</span> <span class="s2">"</span><span class="k">$(</span>md5 -q <span class="nv">$i</span><span class="k">)</span><span class="s2">"</span> <span class="o">]</span>; <span class="k">then + </span><span class="nb">echo</span> <span class="nv">$i</span>.md5 present and correct + <span class="k">else + </span><span class="nb">echo</span> <span class="nv">$i</span>.md5 does not match + <span class="k">fi + else + </span>md5 -q <span class="nv">$i</span> > <span class="nv">$i</span>.md5 + <span class="nb">echo</span> <span class="nv">$i</span>.md5 created + <span class="k">fi + if</span> <span class="o">[</span> -f <span class="nv">$i</span>.sha1 <span class="o">]</span>; <span class="k">then + if</span> <span class="o">[</span> <span class="s2">"</span><span class="k">$(</span>cat <span class="nv">$i</span>.sha1<span class="k">)</span><span class="s2">"</span> <span class="o">=</span> <span class="s2">"</span><span class="k">$(</span>sha1 -q <span class="nv">$i</span><span class="k">)</span><span class="s2">"</span> <span class="o">]</span>; <span class="k">then + </span><span class="nb">echo</span> <span class="nv">$i</span>.sha1 present and correct + <span class="k">else + </span><span class="nb">echo</span> <span class="nv">$i</span>.sha1 does not match + <span class="k">fi + else + </span>sha1 -q <span class="nv">$i</span> > <span class="nv">$i</span>.sha1 + <span class="nb">echo</span> <span class="nv">$i</span>.sha1 created + <span class="k">fi + done</span> +<span class="o">}</span> +checkHash apache-calcite-X.Y.Z-rcN</code></pre></figure> + +<h2 id="get-approval-for-a-release-via-apache-voting-process-for-calcite-committers">Get approval for a release via Apache voting process (for Calcite committers)</h2> + +<p>Release vote on dev list</p> + +<figure class="highlight"><pre><code class="language-text" data-lang="text">To: [email protected] +Subject: [VOTE] Release apache-calcite-X.Y.Z (release candidate N) + +Hi all, + +I have created a build for Apache Calcite X.Y.Z, release candidate N. + +Thanks to everyone who has contributed to this release. +<Further details about release.> You can read the release notes here: +https://github.com/apache/calcite/blob/XXXX/site/_docs/history.md + +The commit to be voted upon: +http://git-wip-us.apache.org/repos/asf/calcite/commit/NNNNNN + +Its hash is XXXX. + +The artifacts to be voted on are located here: +https://dist.apache.org/repos/dist/dev/calcite/apache-calcite-X.Y.Z-rcN/ + +The hashes of the artifacts are as follows: +src.tar.gz.md5 XXXX +src.tar.gz.sha1 XXXX +src.zip.md5 XXXX +src.zip.sha1 XXXX + +A staged Maven repository is available for review at: +https://repository.apache.org/content/repositories/orgapachecalcite-NNNN + +Release artifacts are signed with the following key: +https://people.apache.org/keys/committer/jhyde.asc + +Please vote on releasing this package as Apache Calcite X.Y.Z. + +The vote is open for the next 72 hours and passes if a majority of +at least three +1 PMC votes are cast. + +[ ] +1 Release this package as Apache Calcite X.Y.Z +[ ] 0 I don't feel strongly about it, but I'm okay with the release +[ ] -1 Do not release this package because... + + +Here is my vote: + ++1 (binding) + +Julian</code></pre></figure> + +<p>After vote finishes, send out the result:</p> + +<figure class="highlight"><pre><code class="language-text" data-lang="text">Subject: [RESULT] [VOTE] Release apache-calcite-X.Y.Z (release candidate N) +To: [email protected] + +Thanks to everyone who has tested the release candidate and given +their comments and votes. + +The tally is as follows. + +N binding +1s: +<names> + +N non-binding +1s: +<names> + +No 0s or -1s. + +Therefore I am delighted to announce that the proposal to release +Apache Calcite X.Y.Z has passed. + +Thanks everyone. Weâll now roll the release out to the mirrors. + +There was some feedback during voting. I shall open a separate +thread to discuss. + + +Julian</code></pre></figure> + +<p>Use the <a href="http://s.apache.org";>Apache URL shortener</a> to generate +shortened URLs for the vote proposal and result emails. Examples: +<a href="http://s.apache.org/calcite-1.2-vote";>s.apache.org/calcite-1.2-vote</a> and +<a href="http://s.apache.org/calcite-1.2-result";>s.apache.org/calcite-1.2-result</a>.</p> + +<h2 id="publishing-a-release-for-calcite-committers">Publishing a release (for Calcite committers)</h2> + +<p>After a successful release vote, we need to push the release +out to mirrors, and other tasks.</p> + +<p>Choose a release date. +This is based on the time when you expect to announce the release. +This is usually a day after the vote closes. +Remember that UTC date changes at 4pm Pacific time.</p> + +<p>In JIRA, search for +<a href="https://issues.apache.org/jira/issues/?jql=project%20%3D%20CALCITE%20and%20fixVersion%20%3D%201.5.0%20and%20status%20%3D%20Resolved%20and%20resolution%20%3D%20Fixed";>all issues resolved in this release</a>, +and do a bulk update changing their status to âClosedâ, +with a change comment +âResolved in release X.Y.Z (YYYY-MM-DD)â +(fill in release number and date appropriately). +Uncheck âSend mail for this updateâ.</p> + +<p>Promote the staged nexus artifacts.</p> + +<ul> + <li>Go to <a href="https://repository.apache.org/";>https://repository.apache.org/</a> and login</li> + <li>Under âBuild Promotionâ click âStaging Repositoriesâ</li> + <li>In the line with âorgapachecalcite-xxxxâ, check the box</li> + <li>Press âReleaseâ button</li> +</ul> + +<p>Check the artifacts into svn.</p> + +<figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="c"># Get the release candidate.</span> +mkdir -p ~/dist/dev +<span class="nb">cd</span> ~/dist/dev +svn co https://dist.apache.org/repos/dist/dev/calcite + +<span class="c"># Copy the artifacts. Note that the copy does not have '-rcN' suffix.</span> +mkdir -p ~/dist/release +<span class="nb">cd</span> ~/dist/release +svn co https://dist.apache.org/repos/dist/release/calcite +<span class="nb">cd </span>calcite +cp -rp ../../dev/calcite/apache-calcite-X.Y.Z-rcN apache-calcite-X.Y.Z +svn add apache-calcite-X.Y.Z + +<span class="c"># Check in.</span> +svn ci</code></pre></figure> + +<p>Svnpubsub will publish to the +<a href="https://dist.apache.org/repos/dist/release/calcite";>release repo</a> and propagate to the +<a href="http://www.apache.org/dyn/closer.cgi/calcite";>mirrors</a> within 24 hours.</p> + +<p>If there are now more than 2 releases, clear out the oldest ones:</p> + +<figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="nb">cd</span> ~/dist/release/calcite +svn rm apache-calcite-X.Y.Z +svn ci</code></pre></figure> + +<p>The old releases will remain available in the +<a href="http://archive.apache.org/dist/calcite/";>release archive</a>.</p> + +<p>Add a release note by copying +<a href="https://github.com/apache/calcite/tree/master/avatica/site/_posts/2015-11-10-release-1.5.0.md";>site/_posts/2015-11-10-release-1.5.0.md</a>, +generate the javadoc and copy to <code class="highlighter-rouge">site/target/apidocs</code> and <code class="highlighter-rouge">site/target/testapidocs</code>, +<a href="#publish-the-web-site">publish the site</a>, +and check that it appears in the contents in <a href="http://localhost:4000/news/";>news</a>.</p> + +<p>After 24 hours, announce the release by sending an email to +<a href="https://mail-archives.apache.org/mod_mbox/www-announce/";>[email protected]</a>. +You can use +<a href="https://mail-archives.apache.org/mod_mbox/www-announce/201601.mbox/%3C8DB4C1E5-B322-4A33-8E8F-9858FA6A1119%40apache.org%3E";>the 1.6.0 announcement</a> +as a template. Be sure to include a brief description of the project.</p> + +<h2 id="publish-the-web-site">Publishing the web site (for Calcite committers)</h2> + +<p>See instructions in +<a href="https://github.com/apache/calcite/tree/master/avatica/site/README.md";>site/README.md</a>.</p> + + + + + + + + + + + + + + + + + + + + + + <div class="section-nav"> + <div class="left align-right"> + + + + <a href="/avatica/docs/protobuf_reference.html" class="prev">Previous</a> + + </div> + <div class="right align-left"> + + + + <a href="/avatica/docs/history.html" class="next">Next</a> + + </div> + </div> + <div class="clear"></div> + + + </article> + </div> + + <div class="unit one-fifth hide-on-mobiles"> + <aside> + + <h4>Overview</h4> + + +<ul> + + + + + + + + + + + + + + + + + + + + + + + + <li class=""><a href="/avatica/docs/index.html">Background</a></li> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + <li class=""><a href="/avatica/docs/roadmap.html">Roadmap</a></li> + + + +</ul> + + + <h4>Reference</h4> + + +<ul> + + + + + + + + + + + + + + + + + + + + + + + + + + + + <li class=""><a href="/avatica/docs/json_reference.html">JSON Reference</a></li> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + <li class=""><a href="/avatica/docs/protobuf_reference.html">Protobuf Reference</a></li> + + + + + + + + + + + + + + + + + + + + + + <li class="current"><a href="/avatica/docs/howto.html">HOWTO</a></li> + + + +</ul> + + + <h4>Meta</h4> + + +<ul> + + + + + + + + + + + + + + + + <li class=""><a href="/avatica/docs/history.html">History</a></li> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +</ul> + + + </aside> +</div> + + + <div class="clear"></div> + + </div> + </section> + + + <footer role="contentinfo"> + <div id="poweredby"> + <a href="http://www.apache.org/";> + <span class="sr-only">Apache</span> + <img src="/avatica/img/feather.png" width="190" height="77" alt="Apache Logo"></a> + </div> + <div id="copyright"> + <p>The contents of this website are © 2016 + <a href="https://www.apache.org/";>Apache Software Foundation</a> + under the terms of + the <a href="https://www.apache.org/licenses/LICENSE-2.0.html";> + Apache License v2</a>. Apache Calcite and its logo are + trademarks of the Apache Software Foundation.</p> + </div> +</footer> + + <script> + var anchorForId = function (id) { + var anchor = document.createElement("a"); + anchor.className = "header-link"; + anchor.href = "#" + id; + anchor.innerHTML = "<span class=\"sr-only\">Permalink</span><i class=\"fa fa-link\"></i>"; + anchor.title = "Permalink"; + return anchor; + }; + + var linkifyAnchors = function (level, containingElement) { + var headers = containingElement.getElementsByTagName("h" + level); + for (var h = 0; h < headers.length; h++) { + var header = headers[h]; + + if (typeof header.id !== "undefined" && header.id !== "") { + header.appendChild(anchorForId(header.id)); + } + } + }; + + document.onreadystatechange = function () { + if (this.readyState === "complete") { + var contentBlock = document.getElementsByClassName("docs")[0] || document.getElementsByClassName("news")[0]; + if (!contentBlock) { + return; + } + for (var level = 1; level <= 6; level++) { + linkifyAnchors(level, contentBlock); + } + } + }; +</script> + + +</body> +</html>
Added: calcite/site/avatica/target/docs/index.html URL: http://svn.apache.org/viewvc/calcite/site/avatica/target/docs/index.html?rev=1733977&view=auto ============================================================================== --- calcite/site/avatica/target/docs/index.html (added) +++ calcite/site/avatica/target/docs/index.html Mon Mar 7 20:23:21 2016 @@ -0,0 +1,765 @@ +<!DOCTYPE HTML> +<html lang="en-US"> +<head> + <meta charset="UTF-8"> + <title>Background</title> + <meta name="viewport" content="width=device-width,initial-scale=1"> + <meta name="generator" content="Jekyll v3.0.3"> + <link rel="stylesheet" href="//fonts.googleapis.com/css?family=Lato:300,300italic,400,400italic,700,700italic,900"> + <link rel="stylesheet" href="/avatica/css/screen.css"> + <link rel="icon" type="image/x-icon" href="/avatica/favicon.ico"> + <!--[if lt IE 9]> + <script src="/js/html5shiv.min.js"></script> + <script src="/js/respond.min.js"></script> + <![endif]--> +</head> + + +<body class="wrap"> + <header role="banner"> + <nav class="mobile-nav show-on-mobiles"> + <ul> + <li class=""> + <a href="/avatica/">Home</a> + </li> + <li class=""> + <a href="/avatica/downloads/">Download</a> + </li> + <li class=""> + <a href="/avatica/community/">Community</a> + </li> + <li class=""> + <a href="/avatica/develop/">Develop</a> + </li> + <li class=""> + <a href="/avatica/news/">News</a> + </li> + <li class="current"> + <a href="/avatica/docs/">Docs</a> + </li> +</ul> + + </nav> + <div class="grid"> + <div class="unit one-third center-on-mobiles"> + <h1> + <a href="/avatica/.."> + <span class="sr-only">Apache Calcite Avatica</span> + <img src="/avatica/img/logo.png" width="226" height="140" alt="Calcite Logo"> + </a> + </h1> + </div> + <nav class="main-nav unit two-thirds hide-on-mobiles"> + <ul> + <li class=""> + <a href="/avatica/">Home</a> + </li> + <li class=""> + <a href="/avatica/downloads/">Download</a> + </li> + <li class=""> + <a href="/avatica/community/">Community</a> + </li> + <li class=""> + <a href="/avatica/develop/">Develop</a> + </li> + <li class=""> + <a href="/avatica/news/">News</a> + </li> + <li class="current"> + <a href="/avatica/docs/">Docs</a> + </li> +</ul> + + </nav> + </div> +</header> + + + <section class="docs"> + <div class="grid"> + + <div class="docs-nav-mobile unit whole show-on-mobiles"> + <select onchange="if (this.value) window.location.href=this.value"> + <option value="">Navigate the docsâ¦</option> + + <optgroup label="Overview"> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + </optgroup> + + <optgroup label="Reference"> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + </optgroup> + + <optgroup label="Meta"> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + </optgroup> + + </select> +</div> + + + <div class="unit four-fifths"> + <article> + <h1>Background</h1> + <!-- + +--> + +<p>Avatica is a framework for building JDBC and ODBC drivers for databases, +and an RPC wire protocol.</p> + +<p><img src="https://raw.githubusercontent.com/julianhyde/share/master/slides/avatica-architecture.png"; alt="Avatica Architecture" /></p> + +<p>Avaticaâs Java binding has very few dependencies. +Even though it is part of Apache Calcite it does not depend on other parts of +Calcite. It depends only on JDK 1.7+ and Jackson.</p> + +<p>Avaticaâs wire protocol is JSON over HTTP. +The Java implementation uses Jackson to convert request/response command +objects to/from JSON.</p> + +<p>Avatica-Server is a Java implementation of Avatica RPC.</p> + +<p>Core concepts:</p> + +<ul> + <li>Meta is a local API sufficient to implement any Avatica provider</li> + <li>Factory creates implementations of the JDBC classes (Driver, Connection, +Statement, ResultSet) on top of a Meta</li> + <li>Service is an interface that implements the functions of Meta in terms +of request and response command objects</li> +</ul> + +<h2 id="jdbc">JDBC</h2> + +<p>Avatica implements JDBC by means of Factory. +Factory creates implementations of the JDBC classes (Driver, Connection, +Statement, PreparedStatement, ResultSet) on top of a Meta.</p> + +<h2 id="odbc">ODBC</h2> + +<p>Work has not started on Avatica ODBC.</p> + +<p>Avatica ODBC would use the same wire protocol and could use the same server +implementation in Java. The ODBC client would be written in C or C++.</p> + +<p>Since the Avatica protocol abstracts many of the differences between providers, +the same ODBC client could be used for different databases.</p> + +<h2 id="http-server">HTTP Server</h2> + +<p>Avatica-server embeds the Jetty HTTP server, providing a class +<a href="/apidocs/org/apache/calcite/avatica/server/HttpServer.html">HttpServer</a> +that implements the Avatica RPC protocol +and can be run as a standalone Java application.</p> + +<p>Connectors in HTTP server can be configured if needed by extending +<code class="highlighter-rouge">HttpServer</code> class and overriding its <code class="highlighter-rouge">configureConnector()</code> method. +For example, user can set <code class="highlighter-rouge">requestHeaderSize</code> to 64K bytes as follows:</p> + +<figure class="highlight"><pre><code class="language-java" data-lang="java"><span class="n">HttpServer</span> <span class="n">server</span> <span class="o">=</span> <span class="k">new</span> <span class="n">HttpServer</span><span class="o">(</span><span class="n">handler</span><span class="o">)</span> <span class="o">{</span> + <span class="nd">@Override</span> + <span class="kd">protected</span> <span class="n">ServerConnector</span> <span class="n">configureConnector</span><span class="o">(</span> + <span class="n">ServerConnector</span> <span class="n">connector</span><span class="o">,</span> <span class="kt">int</span> <span class="n">port</span><span class="o">)</span> <span class="o">{</span> + <span class="n">HttpConnectionFactory</span> <span class="n">factory</span> <span class="o">=</span> <span class="o">(</span><span class="n">HttpConnectionFactory</span><span class="o">)</span> + <span class="n">connector</span><span class="o">.</span><span class="na">getDefaultConnectionFactory</span><span class="o">();</span> + <span class="n">factory</span><span class="o">.</span><span class="na">getHttpConfiguration</span><span class="o">().</span><span class="na">setRequestHeaderSize</span><span class="o">(</span><span class="mi">64</span> <span class="o"><<</span> <span class="mi">10</span><span class="o">);</span> + <span class="k">return</span> <span class="kd">super</span><span class="o">.</span><span class="na">configureConnector</span><span class="o">(</span><span class="n">connector</span><span class="o">,</span> <span class="n">port</span><span class="o">);</span> + <span class="o">}</span> +<span class="o">};</span> +<span class="n">server</span><span class="o">.</span><span class="na">start</span><span class="o">();</span></code></pre></figure> + +<h2 id="project-structure">Project structure</h2> + +<p>We know that it is important that client libraries have minimal dependencies.</p> + +<p>Avatica is currently part of Apache Calcite. +It does not depend upon any other part of Calcite. +At some point Avatica could become a separate project.</p> + +<p>Packages:</p> + +<ul> + <li><a href="/apidocs/org/apache/calcite/avatica/package-summary.html">org.apache.calcite.avatica</a> Core framework</li> + <li><a href="/apidocs/org/apache/calcite/avatica/remote/package-summary.html">org.apache.calcite.avatica.remote</a> JDBC driver that uses remote procedure calls</li> + <li><a href="/apidocs/org/apache/calcite/avatica/server/package-summary.html">org.apache.calcite.avatica.server</a> HTTP server</li> + <li><a href="/apidocs/org/apache/calcite/avatica/util/package-summary.html">org.apache.calcite.avatica.util</a> Utilities</li> +</ul> + +<h2 id="status">Status</h2> + +<h3 id="implemented">Implemented</h3> + +<ul> + <li>Create connection, create statement, metadata, prepare, bind, execute, fetch</li> + <li>RPC using JSON over HTTP</li> + <li>Local implementation</li> + <li>Implementation over an existing JDBC driver</li> + <li>Composite RPCs (combining several requests into one round trip) + <ul> + <li>Execute-Fetch</li> + <li>Metadata-Fetch (metadata calls such as getTables return all rows)</li> + </ul> + </li> +</ul> + +<h3 id="not-implemented">Not implemented</h3> + +<ul> + <li>ODBC</li> + <li>RPCs + <ul> + <li>CloseStatement</li> + <li>CloseConnection</li> + </ul> + </li> + <li>Composite RPCs + <ul> + <li>CreateStatement-Prepare</li> + <li>CloseStatement-CloseConnection</li> + <li>Prepare-Execute-Fetch (Statement.executeQuery should fetch first N rows)</li> + </ul> + </li> + <li>Remove statements from statement table</li> + <li>DML (INSERT, UPDATE, DELETE)</li> + <li>Statement.execute applied to SELECT statement</li> +</ul> + + + + + + + + + + <div class="section-nav"> + <div class="left align-right"> + + <span class="prev disabled">Previous</span> + + </div> + <div class="right align-left"> + + + + <a href="/avatica/docs/roadmap.html" class="next">Next</a> + + </div> + </div> + <div class="clear"></div> + + + </article> + </div> + + <div class="unit one-fifth hide-on-mobiles"> + <aside> + + <h4>Overview</h4> + + +<ul> + + + + + + + + + + + + + + + + + + + + + + + + <li class="current"><a href="/avatica/docs/index.html">Background</a></li> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + <li class=""><a href="/avatica/docs/roadmap.html">Roadmap</a></li> + + + +</ul> + + + <h4>Reference</h4> + + +<ul> + + + + + + + + + + + + + + + + + + + + + + + + + + + + <li class=""><a href="/avatica/docs/json_reference.html">JSON Reference</a></li> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + <li class=""><a href="/avatica/docs/protobuf_reference.html">Protobuf Reference</a></li> + + + + + + + + + + + + + + + + + + + + + + <li class=""><a href="/avatica/docs/howto.html">HOWTO</a></li> + + + +</ul> + + + <h4>Meta</h4> + + +<ul> + + + + + + + + + + + + + + + + <li class=""><a href="/avatica/docs/history.html">History</a></li> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +</ul> + + + </aside> +</div> + + + <div class="clear"></div> + + </div> + </section> + + + <footer role="contentinfo"> + <div id="poweredby"> + <a href="http://www.apache.org/";> + <span class="sr-only">Apache</span> + <img src="/avatica/img/feather.png" width="190" height="77" alt="Apache Logo"></a> + </div> + <div id="copyright"> + <p>The contents of this website are © 2016 + <a href="https://www.apache.org/";>Apache Software Foundation</a> + under the terms of + the <a href="https://www.apache.org/licenses/LICENSE-2.0.html";> + Apache License v2</a>. Apache Calcite and its logo are + trademarks of the Apache Software Foundation.</p> + </div> +</footer> + + <script> + var anchorForId = function (id) { + var anchor = document.createElement("a"); + anchor.className = "header-link"; + anchor.href = "#" + id; + anchor.innerHTML = "<span class=\"sr-only\">Permalink</span><i class=\"fa fa-link\"></i>"; + anchor.title = "Permalink"; + return anchor; + }; + + var linkifyAnchors = function (level, containingElement) { + var headers = containingElement.getElementsByTagName("h" + level); + for (var h = 0; h < headers.length; h++) { + var header = headers[h]; + + if (typeof header.id !== "undefined" && header.id !== "") { + header.appendChild(anchorForId(header.id)); + } + } + }; + + document.onreadystatechange = function () { + if (this.readyState === "complete") { + var contentBlock = document.getElementsByClassName("docs")[0] || document.getElementsByClassName("news")[0]; + if (!contentBlock) { + return; + } + for (var level = 1; level <= 6; level++) { + linkifyAnchors(level, contentBlock); + } + } + }; +</script> + + +</body> +</html>
![https://raw.githubusercontent.com/julianhyde/share/master/slides/avatica-architecture.png"](https://raw.githubusercontent.com/julianhyde/share/master/slides/avatica-architecture.png"){kind=link}