You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@calcite.apache.org by jh...@apache.org on 2016/03/07 21:23:23 UTC
svn commit: r1733977 [8/12] - in /calcite/site/avatica: ./ community/ css/
develop/ docs/ docs/api/ docs/testapi/ downloads/ fonts/ img/ js/ news/
news/2016/ news/2016/03/ news/2016/03/03/ news/2016/03/03/separate-project/
news/2016/03/03/tbd-release/ ...
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: dev@calcite.apache.org
+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: dev@calcite.apache.org
+
+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/">announce@apache.org</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>