Added: calcite/site/avatica/docs/howto.html
URL:
http://svn.apache.org/viewvc/calcite/site/avatica/docs/howto.html?rev=1848180&view=auto
==============================================================================
--- calcite/site/avatica/docs/howto.html (added)
+++ calcite/site/avatica/docs/howto.html Tue Dec 4 22:13:30 2018
@@ -0,0 +1,1579 @@
+<!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.7.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="Avatica Reference">
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ </optgroup>
+
+ <optgroup label="Avatica Go Client Reference">
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ </optgroup>
+
+ <optgroup label="Avatica Meta">
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ </optgroup>
+
+ <optgroup label="Avatica Go Client Meta">
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ </optgroup>
+
+ </select>
+</div>
+
+
+ <div class="unit four-fifths">
+ <article>
+ <h1>HOWTO</h1>
+ <!--
+
+-->
+
+<p>Hereâs some miscellaneous documentation about using Avatica.</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> <ul>
+ <li><a href="#running-tests-in-your-environment"
id="markdown-toc-running-tests-in-your-environment">Running tests in your
environment</a></li>
+ <li><a href="#to-run-tests-in-docker"
id="markdown-toc-to-run-tests-in-docker">To run tests in docker:</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="#advanced-topics-for-developers"
id="markdown-toc-advanced-topics-for-developers">Advanced topics for
developers</a></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="#run-a-gpg-agent" id="markdown-toc-run-a-gpg-agent">Run a
GPG agent</a></li>
+ <li><a
href="#set-up-maven-repository-credentials-for-calcite-committers"
id="markdown-toc-set-up-maven-repository-credentials-for-calcite-committers">Set
up Maven repository credentials (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> <ul>
+ <li><a href="#to-perform-the-dry-run-directly-in-your-environment"
id="markdown-toc-to-perform-the-dry-run-directly-in-your-environment">To
perform the dry-run directly in your environment:</a></li>
+ <li><a href="#to-perform-the-dry-run-in-docker"
id="markdown-toc-to-perform-the-dry-run-in-docker">To perform the dry-run in
docker:</a></li>
+ <li><a href="#if-you-are-building-directly-in-your-environment"
id="markdown-toc-if-you-are-building-directly-in-your-environment">If you are
building directly in your environment:</a></li>
+ <li><a href="#if-you-are-building-using-docker"
id="markdown-toc-if-you-are-building-using-docker">If you are building using
docker:</a></li>
+ <li><a href="#to-build-directly-in-your-environment"
id="markdown-toc-to-build-directly-in-your-environment">To build directly in
your environment:</a></li>
+ <li><a href="#to-build-using-docker"
id="markdown-toc-to-build-using-docker">To build using docker:</a></li>
+ </ul>
+ </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 8 or later) on your path.</p>
+
+<p>Unpack the source distribution <code
class="highlighter-rouge">.tar.gz</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="nv">$ </span><span class="nb">tar </span>xvfz
apache-calcite-avatica-1.13.0-src.tar.gz
+<span class="nv">$ </span><span class="nb">cd
</span>apache-calcite-avatica-1.13.0-src
+<span class="nv">$ </span>./mvnw 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 8 or later) 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="nv">$ </span>git clone
git://github.com/apache/calcite-avatica.git avatica
+<span class="nv">$ </span><span class="nb">cd </span>avatica
+<span class="nv">$ </span>./mvnw install</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>
+
+<h3 id="running-tests-in-your-environment">Running tests in your
environment</h3>
+
+<figure class="highlight"><pre><code class="language-bash"
data-lang="bash"><span class="nv">$ </span>./mvnw clean verify <span
class="nt">-Dcheckstyle</span>.skip</code></pre></figure>
+
+<p>By default, invoking the <code class="highlighter-rouge">verify</code>
Maven lifecycle phase will also cause checkstyle
+rules to be run. It is expected that contributions pass the checkstyle rules;
however,
+it is common to ignore these while working on a feature/bug and fix them at
the end.</p>
+
+<h3 id="to-run-tests-in-docker">To run tests in docker:</h3>
+
+<ul>
+ <li>You will need to have <a
href="https://docs.docker.com/install/";>docker</a> and <a
href="https://docs.docker.com/compose/install/";>Docker Compose</a>
installed.</li>
+</ul>
+
+<figure class="highlight"><pre><code class="language-bash"
data-lang="bash">docker-compose run <span
class="nb">test</span></code></pre></figure>
+
+<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>
+
+<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>
+
+<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
+<a href="https://dist.apache.org/repos/dist/release/calcite/KEYS";><code
class="highlighter-rouge">KEYS</code></a>
+file by following instructions in the <code
class="highlighter-rouge">KEYS</code> file.
+(The <code class="highlighter-rouge">KEYS</code> file is not present in the
git repo or in a release tar
+ball because that would be
+<a
href="https://issues.apache.org/jira/browse/CALCITE-1746";>redundant</a>.)</p>
+
+<h2 id="run-a-gpg-agent">Run a GPG agent</h2>
+
+<p>By default, Maven plugins which require you to unlock a GPG secret key
+will prompt you in the terminal. To prevent you from having to enter
+this password numerous times, it is highly recommended to install and
+run <code class="highlighter-rouge">gpg-agent</code>.</p>
+
+<p>This can be started automatically via an <code
class="highlighter-rouge">~/.xsession</code> on Linux or some
+scripting in your shellâs configuration script of choice (e.g. <code
class="highlighter-rouge">~/.bashrc</code> or <code
class="highlighter-rouge">~/.zshrc</code>)</p>
+
+<figure class="highlight"><pre><code class="language-bash"
data-lang="bash"><span class="nv">GPG_AGENT</span><span class="o">=</span><span
class="k">$(</span>which gpg-agent<span class="k">)</span>
+<span class="nv">GPG_TTY</span><span class="o">=</span><span
class="sb">`</span>tty<span class="sb">`</span>
+<span class="nb">export </span>GPG_TTY
+<span class="k">if</span> <span class="o">[[</span> <span class="nt">-f</span>
<span class="s2">"</span><span class="nv">$GPG_AGENT</span><span
class="s2">"</span> <span class="o">]]</span><span class="p">;</span> <span
class="k">then
+ </span><span class="nv">envfile</span><span class="o">=</span><span
class="s2">"</span><span class="k">${</span><span class="nv">HOME</span><span
class="k">}</span><span class="s2">/.gnupg/gpg-agent.env"</span>
+
+ <span class="k">if </span><span class="nb">test</span> <span
class="nt">-f</span> <span class="s2">"</span><span
class="nv">$envfile</span><span class="s2">"</span> <span
class="o">&&</span> <span class="nb">kill</span> <span
class="nt">-0</span> <span class="k">$(</span><span class="nb">grep
</span>GPG_AGENT_INFO <span class="s2">"</span><span
class="nv">$envfile</span><span class="s2">"</span> | cut <span
class="nt">-d</span>: <span class="nt">-f</span> 2<span class="k">)</span>
2>/dev/null<span class="p">;</span> <span class="k">then
+ </span><span class="nb">source</span> <span class="s2">"</span><span
class="nv">$envfile</span><span class="s2">"</span>
+ <span class="k">else
+ </span><span class="nb">eval</span> <span class="s2">"</span><span
class="k">$(</span>gpg-agent <span class="nt">--daemon</span> <span
class="nt">--log-file</span><span class="o">=</span>~/.gpg/gpg.log <span
class="nt">--write-env-file</span> <span class="s2">"</span><span
class="nv">$envfile</span><span class="s2">"</span><span
class="k">)</span><span class="s2">"</span>
+ <span class="k">fi
+ </span><span class="nb">export </span>GPG_AGENT_INFO <span class="c"># the
env file does not contain the export statement</span>
+<span class="k">fi</span></code></pre></figure>
+
+<p>Also, ensure that <code class="highlighter-rouge">default-cache-ttl
6000</code> is set in <code
class="highlighter-rouge">~/.gnupg/gpg-agent.conf</code>
+to guarantee that your credentials will be cached for the duration of the
build.</p>
+
+<h2 id="set-up-maven-repository-credentials-for-calcite-committers">Set up
Maven repository credentials (for Calcite committers)</h2>
+
+<p>Follow the instructions <a
href="http://www.apache.org/dev/publishing-maven-artifacts.html#dev-env";>here</a>
to add your credentials to your maven configuration.</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 8 (not 9 or 10).</li>
+</ul>
+
+<figure class="highlight"><pre><code class="language-bash"
data-lang="bash"><span class="c"># Make sure that there are no junk files in
the sandbox</span>
+git clean <span class="nt">-xn</span>
+
+./mvnw <span class="nt">-Papache-release</span> clean
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 8 (not 9 or 10).</li>
+ <li>Check that <code class="highlighter-rouge">README</code>, <code
class="highlighter-rouge">site/_docs/howto.md</code>, <code
class="highlighter-rouge">site/_docs/docker_images.md</code> have the correct
version number.</li>
+ <li>Check that <code class="highlighter-rouge">NOTICE</code> has the current
copyright year.</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>Add release notes to <code
class="highlighter-rouge">site/_docs/history.md</code>. Include the commit
history,
+and say which versions of Java, Guava and operating systems the release is
+tested against.</li>
+ <li>Generate a report of vulnerabilities that occur among dependencies,
+using <code class="highlighter-rouge">./mvnw verify -Ppedantic</code>.</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-avatica-1.9</code>, and push it to
Apache.</p>
+
+<figure class="highlight"><pre><code class="language-bash"
data-lang="bash"><span class="nv">$ </span>git checkout <span
class="nt">-b</span> branch-avatica-X.Y
+<span class="nv">$ </span>git push <span class="nt">-u</span> origin
branch-avatica-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>
+
+<p>To perform the dry-run, you can either use your environment or the release
script and docker.</p>
+
+<h3 id="to-perform-the-dry-run-directly-in-your-environment">To perform the
dry-run directly in your environment:</h3>
+
+<figure class="highlight"><pre><code class="language-bash"
data-lang="bash"><span class="c"># Make sure that there are no junk files in
the sandbox</span>
+git clean <span class="nt">-xn</span>
+
+<span class="c"># Do a dry run of the release:prepare step, which sets version
numbers.</span>
+<span class="c"># Typically we increment minor version: If X.Y.Z is 1.13.0,
X2.Y2.Z2 is 1.14.0.</span>
+<span class="c"># Note X.Y.Z is the current version we're trying to release,
and X2.Y2.Z2 is the next development version.</span>
+
+<span class="c"># For example, if I am currently building a release for
1.11.0, X.Y.Z would be 1.11.0 and X2.Y2.Z2 would be 1.12.0.</span>
+./mvnw <span class="nt">-DdryRun</span><span class="o">=</span><span
class="nb">true</span> <span class="nt">-DreleaseVersion</span><span
class="o">=</span>X.Y.Z <span class="nt">-DdevelopmentVersion</span><span
class="o">=</span>X2.Y2.Z2-SNAPSHOT <span class="nt">-Dtag</span><span
class="o">=</span>avatica-X.Y.Z-rcN <span class="nt">-Papache-release</span>
<span class="nt">-Duser</span>.name<span class="o">=</span><span
class="k">${</span><span class="nv">asf</span><span
class="p">.username</span><span class="k">}</span> release:prepare
+
+<span class="c"># If you have multiple GPG keys, you can select the key used
to sign the release by appending `-Dgpg.keyname=${your.key.id}` to
`-Darguments`:</span>
+./mvnw <span class="nt">-DdryRun</span><span class="o">=</span><span
class="nb">true</span> <span class="nt">-DreleaseVersion</span><span
class="o">=</span>X.Y.Z <span class="nt">-DdevelopmentVersion</span><span
class="o">=</span>X2.Y2.Z2-SNAPSHOT <span class="nt">-Dtag</span><span
class="o">=</span>avatica-X.Y.Z-rcN <span class="nt">-Papache-release</span>
<span class="nt">-Duser</span>.name<span class="o">=</span><span
class="k">${</span><span class="nv">asf</span><span
class="p">.username</span><span class="k">}</span> release:prepare <span
class="nt">-Darguments</span><span class="o">=</span><span
class="nt">-Dgpg</span>.keyname<span class="o">=</span><span
class="k">${</span><span class="nv">your</span><span
class="p">.key.id</span><span class="k">}</span></code></pre></figure>
+
+<h3 id="to-perform-the-dry-run-in-docker">To perform the dry-run in
docker:</h3>
+
+<ul>
+ <li>
+ <p>You will need to have <a
href="https://docs.docker.com/install/";>docker</a> and <a
href="https://docs.docker.com/compose/install/";>Docker Compose</a>
installed.</p>
+ </li>
+ <li>
+ <p>The script expects you to mount your <code
class="highlighter-rouge">~/.gnupg</code> directory into the <code
class="highlighter-rouge">/.gnupg</code> directory in the container. Once
mounted into the container,
+the script will make a copy of the contents and move it to a different
location, so that it will not modify the contents of your original
+<code class="highlighter-rouge">~/.gnupg</code> directory during the build.</p>
+ </li>
+</ul>
+
+<figure class="highlight"><pre><code class="language-bash"
data-lang="bash"><span class="c"># On Linux:</span>
+docker-compose run <span class="nt">-v</span> ~/.gnupg:/.gnupg dry-run
+
+<span class="c"># On Windows</span>
+docker-compose run <span class="nt">-v</span>
/c/Users/username/AppData/Roaming/gnupg:/.gnupg dry-run</code></pre></figure>
+
+<p>Check the artifacts:</p>
+
+<ul>
+ <li>In the <code class="highlighter-rouge">target</code> directory should be
these 6 files, among others:
+ <ul>
+ <li>apache-calcite-avatica-X.Y.Z-src.tar.gz</li>
+ <li>apache-calcite-avatica-X.Y.Z-src.tar.gz.asc</li>
+ <li>apache-calcite-avatica-X.Y.Z-src.tar.gz.sha256</li>
+ </ul>
+ </li>
+ <li>Note that the file names start <code
class="highlighter-rouge">apache-calcite-avatica-</code>.</li>
+ <li>In the source distro <code class="highlighter-rouge">.tar.gz</code>
(currently there is
+no binary distro), check that all files belong to a directory called
+<code class="highlighter-rouge">apache-calcite-avatica-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>Make sure that there is no <code class="highlighter-rouge">KEYS</code>
file in the source distros</li>
+ <li>For each .jar (for example <code
class="highlighter-rouge">core/target/avatica-core-X.Y.Z.jar</code>
+and <code
class="highlighter-rouge">server/target/avatica-server-X.Y.Z-sources.jar</code>),
+verify that the <code class="highlighter-rouge">META-INF</code> directory
contains the correct
+contents for <code class="highlighter-rouge">DEPENDENCIES</code>, <code
class="highlighter-rouge">LICENSE</code> and <code
class="highlighter-rouge">NOTICE</code> per the
+source/classes contained. Refer to the ASF licensing documentation on
+what is required.</li>
+ <li>Check PGP, per <a
href="https://httpd.apache.org/dev/verification.html";>this</a></li>
+</ul>
+
+<p>If something is not correct, you can invoke the <code
class="highlighter-rouge">release:clean</code> mojo to remove the
+generated files from your workspace:</p>
+
+<h3 id="if-you-are-building-directly-in-your-environment">If you are building
directly in your environment:</h3>
+
+<figure class="highlight"><pre><code class="language-bash"
data-lang="bash">./mvnw release:clean</code></pre></figure>
+
+<h3 id="if-you-are-building-using-docker">If you are building using
docker:</h3>
+
+<figure class="highlight"><pre><code class="language-bash"
data-lang="bash">docker-compose run clean</code></pre></figure>
+
+<p>If successful, remove the <code class="highlighter-rouge">-DdryRun</code>
flag and run the release for real.</p>
+
+<h3 id="to-build-directly-in-your-environment">To build directly in your
environment:</h3>
+
+<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>
+<span class="c"># Typically we increment minor version: If X.Y.Z is 1.13.0,
X2.Y2.Z2 is 1.14.0.</span>
+<span class="c"># Note X.Y.Z is the current version we're trying to release,
and X2.Y2.Z2 is the next development version.</span>
+<span class="c"># For example, if I am currently building a release for
1.13.0, X.Y.Z would be 1.13.0 and X2.Y2.Z2 would be 1.14.0.</span>
+./mvnw <span class="nt">-DreleaseVersion</span><span class="o">=</span>X.Y.Z
<span class="nt">-DdevelopmentVersion</span><span
class="o">=</span>X2.Y2.Z2-SNAPSHOT <span class="nt">-Dtag</span><span
class="o">=</span>avatica-X.Y.Z-rcN <span class="nt">-Papache-release</span>
<span class="nt">-Duser</span>.name<span class="o">=</span><span
class="k">${</span><span class="nv">asf</span><span
class="p">.username</span><span class="k">}</span> release:prepare
+
+<span class="c"># If you have multiple GPG keys, you can select the key used
to sign the release by appending
`-Darguments=-Dgpg.keyname=${your.key.id}`:</span>
+./mvnw <span class="nt">-DreleaseVersion</span><span class="o">=</span>X.Y.Z
<span class="nt">-DdevelopmentVersion</span><span
class="o">=</span>X2.Y2.Z2-SNAPSHOT <span class="nt">-Dtag</span><span
class="o">=</span>avatica-X.Y.Z-rcN <span class="nt">-Papache-release</span>
<span class="nt">-Duser</span>.name<span class="o">=</span><span
class="k">${</span><span class="nv">asf</span><span
class="p">.username</span><span class="k">}</span> release:prepare <span
class="nt">-Darguments</span><span class="o">=</span><span
class="nt">-Dgpg</span>.keyname<span class="o">=</span><span
class="k">${</span><span class="nv">your</span><span
class="p">.key.id</span><span class="k">}</span>
+
+<span class="c"># Perform checks out the tagged version, builds, and deploys
to the staging repository</span>
+./mvnw <span class="nt">-Papache-release</span> <span
class="nt">-Duser</span>.name<span class="o">=</span><span
class="k">${</span><span class="nv">asf</span><span
class="p">.username</span><span class="k">}</span> release:perform <span
class="nt">-Darguments</span><span class="o">=</span><span
class="s2">"-DskipTests"</span></code></pre></figure>
+
+<h3 id="to-build-using-docker">To build using docker:</h3>
+
+<figure class="highlight"><pre><code class="language-bash"
data-lang="bash"><span class="c"># On Linux:</span>
+docker-compose run <span class="nt">-v</span> ~/.gnupg:/.gnupg release
+
+<span class="c"># On Windows</span>
+docker-compose run <span class="nt">-v</span>
/c/Users/username/AppData/Roaming/gnupg:/.gnupg release</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-avatica-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 <span class="nt">-p</span> ~/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-avatica-X.Y.Z-rcN
+mv apache-calcite-avatica-<span class="k">*</span>
~/dist/dev/calcite/apache-calcite-avatica-X.Y.Z-rcN
+
+<span class="c"># Check in</span>
+<span class="nb">cd</span> ~/dist/dev/calcite
+svn add apache-calcite-avatica-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 <span class="nt">-d</span> avatica-X.Y.Z
+git push origin :refs/tags/avatica-X.Y.Z
+
+<span class="c"># Remove modified files</span>
+./mvnw 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 <span class="nt">--hard</span> 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 <span class="nt">--recv-keys</span> key
+
+<span class="c"># Check keys</span>
+curl <span class="nt">-O</span>
https://dist.apache.org/repos/dist/release/calcite/KEYS
+
+<span class="c"># Sign/check sha256 hashes</span>
+<span class="c"># (Assumes your O/S has a 'shasum' command.)</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>pom,gz<span class="o">}</span><span
class="p">;</span> <span class="k">do
+ if</span> <span class="o">[</span> <span class="o">!</span> <span
class="nt">-f</span> <span class="nv">$i</span> <span class="o">]</span><span
class="p">;</span> <span class="k">then
+ continue
+ fi
+ if</span> <span class="o">[</span> <span class="nt">-f</span> <span
class="nv">$i</span>.sha256 <span class="o">]</span><span class="p">;</span>
<span class="k">then
+ if</span> <span class="o">[</span> <span class="s2">"</span><span
class="k">$(</span><span class="nb">cat</span> <span
class="nv">$i</span>.sha256<span class="k">)</span><span class="s2">"</span>
<span class="o">=</span> <span class="s2">"</span><span
class="k">$(</span>shasum <span class="nt">-a</span> 256 <span
class="nv">$i</span><span class="k">)</span><span class="s2">"</span> <span
class="o">]</span><span class="p">;</span> <span class="k">then
+ </span><span class="nb">echo</span> <span class="nv">$i</span>.sha256
present and correct
+ <span class="k">else
+ </span><span class="nb">echo</span> <span class="nv">$i</span>.sha256
does not match
+ <span class="k">fi
+ else
+ </span>shasum <span class="nt">-a</span> 256 <span class="nv">$i</span>
<span class="o">></span> <span class="nv">$i</span>.sha256
+ <span class="nb">echo</span> <span class="nv">$i</span>.sha256 created
+ <span class="k">fi
+ done</span>
+<span class="o">}</span>
+checkHash apache-calcite-avatica-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-avatica-X.Y.Z (release candidate N)
+
+Hi all,
+
+I have created a build for Apache Calcite Avatica 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-avatica/blob/XXXX/site/_docs/history.md
+
+The commit to be voted upon:
+http://git-wip-us.apache.org/repos/asf/calcite-avatica/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-avatica-X.Y.Z-rcN/
+
+The hashes of the artifacts are as follows:
+src.tar.gz.sha256 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 Avatica 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-avatica-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 Avatica 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>Tip: Push the git tag only after the staged nexus artifacts are promoted in
the repository. This is because pushing the
+tag triggers Docker Hub to start building the docker images immediately and
the build will pull in the promoted artifacts.
+If the artifacts are not yet available, the build on Docker Hub will fail.</p>
+
+<p>Copy the Git tag:</p>
+
+<figure class="highlight"><pre><code class="language-bash"
data-lang="bash">git tag rel/avatica-X.Y.X avatica-X.Y.Z-rcN
+git push origin rel/avatica-X.Y.Z</code></pre></figure>
+
+<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 <span class="nt">-p</span> ~/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 <span class="nt">-p</span> ~/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 <span class="nt">-rp</span>
../../dev/calcite/apache-calcite-avatica-X.Y.Z-rcN apache-calcite-avatica-X.Y.Z
+svn add apache-calcite-avatica-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-avatica-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-avatica/tree/master/site/_posts/2016-11-01-release-1.9.0.md";>site/_posts/2016-11-01-release-1.9.0.md</a>,
+generate the javadoc and copy to <code
class="highlighter-rouge">site/target/avatica/apidocs</code>
+and <code class="highlighter-rouge">site/target/avatica/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/201606.mbox/%[email protected]%3E";>the
1.8.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-avatica/tree/master/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/security.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>Avatica Reference</h4>
+
+
+<ul>
+
+
+
+
+
+
+
+
+ <li class=""><a href="/avatica/docs/client_reference.html">Client
Reference</a></li>
+
+
+
+
+
+
+
+
+
+ <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>
+
+
+
+
+
+
+
+
+
+ <li class=""><a href="/avatica/docs/security.html">Security</a></li>
+
+
+
+
+
+
+
+
+
+ <li class=""><a
href="/avatica/docs/compatibility.html">Compatibility</a></li>
+
+
+
+
+
+
+
+
+
+ <li class=""><a href="/avatica/docs/custom_client_artifacts.html">Custom
Client Artifacts</a></li>
+
+
+
+
+
+
+
+
+
+ <li class=""><a href="/avatica/docs/docker.html">Docker Images</a></li>
+
+
+
+
+
+
+
+
+
+ <li class=""><a href="/avatica/docs/protocol_testing.html">Protocol
Testing</a></li>
+
+
+</ul>
+
+
+ <h4>Avatica Go Client Reference</h4>
+
+
+<ul>
+
+
+
+
+
+
+
+
+ <li class=""><a href="/avatica/docs/go_client_reference.html">Go Client
Reference</a></li>
+
+
+</ul>
+
+
+ <h4>Avatica Meta</h4>
+
+
+<ul>
+
+
+
+
+
+
+
+
+ <li class=""><a href="/avatica/docs/history.html">History</a></li>
+
+
+
+
+
+
+
+
+
+ <li class=""><a href="/avatica/docs/api/">API</a></li>
+
+
+
+
+
+
+
+
+
+ <li class=""><a href="/avatica/docs/testapi/">Test API</a></li>
+
+
+</ul>
+
+
+ <h4>Avatica Go Client Meta</h4>
+
+
+<ul>
+
+
+
+
+
+
+
+
+ <li class=""><a href="/avatica/docs/go_history.html">Go Client
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 © 2018
+ <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>
Propchange: calcite/site/avatica/docs/howto.html
------------------------------------------------------------------------------
svn:executable = *
Added: calcite/site/avatica/docs/index.html
URL:
http://svn.apache.org/viewvc/calcite/site/avatica/docs/index.html?rev=1848180&view=auto
==============================================================================
--- calcite/site/avatica/docs/index.html (added)
+++ calcite/site/avatica/docs/index.html Tue Dec 4 22:13:30 2018
@@ -0,0 +1,1179 @@
+<!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.7.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="Avatica Reference">
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ </optgroup>
+
+ <optgroup label="Avatica Go Client Reference">
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ </optgroup>
+
+ <optgroup label="Avatica Meta">
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ </optgroup>
+
+ <optgroup label="Avatica Go Client 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 8+ and Jackson.</p>
+
+<p>Avaticaâs wire protocols are JSON or Protocol Buffers over HTTP. The
+Java implementation of the JSON protocol uses
+<a href="https://github.com/FasterXML/jackson";>Jackson</a> 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><a href="/avatica/apidocs/org/apache/calcite/avatica/Meta.html">Meta</a>
+is a local API sufficient to implement any Avatica provider</li>
+ <li><a
href="/avatica/apidocs/org/apache/calcite/avatica/AvaticaFactory.html">AvaticaFactory</a>
+creates implementations of the JDBC classes on top of a <code
class="highlighter-rouge">Meta</code></li>
+ <li><a
href="/avatica/apidocs/org/apache/calcite/avatica/remote/Service.html">Service</a>
+is an interface that implements the functions of <code
class="highlighter-rouge">Meta</code> in terms
+of request and response command objects</li>
+</ul>
+
+<h2 id="jdbc">JDBC</h2>
+
+<p>Avatica implements JDBC by means of
+<a
href="/avatica/apidocs/org/apache/calcite/avatica/AvaticaFactory.html">AvaticaFactory</a>.
+An implementation of <code class="highlighter-rouge">AvaticaFactory</code>
creates implementations of the
+JDBC classes (<a
href="https://docs.oracle.com/javase/8/docs/api//java/sql/Driver.html";>Driver</a>,
+<a
href="https://docs.oracle.com/javase/8/docs/api//java/sql/Connection.html";>Connection</a>,
+<a
href="https://docs.oracle.com/javase/8/docs/api//java/sql/Statement.html";>Statement</a>,
+<a
href="https://docs.oracle.com/javase/8/docs/api//java/sql/ResultSet.html";>ResultSet</a>)
+on top of a <code class="highlighter-rouge">Meta</code>.</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>
+
+<p>Although the Avatica project does not include an ODBC driver, there
+are ODBC drivers written on top of the Avatica protocol, for example
+<a href="http://hortonworks.com/hadoop-tutorial/bi-apache-phoenix-odbc/";>an
ODBC driver for Apache Phoenix</a>.</p>
+
+<h2 id="http-server">HTTP Server</h2>
+
+<p>Avatica-server embeds the Jetty HTTP server, providing a class
+<a
href="/avatica/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="nf">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 a sub-project of <a href="https://calcite.apache.org";>Apache
Calcite</a>,
+maintained in a separate repository.
+It does not depend upon any other part of Calcite.</p>
+
+<p>Packages:</p>
+
+<ul>
+ <li><a
href="/avatica/apidocs/org/apache/calcite/avatica/package-summary.html">org.apache.calcite.avatica</a>
Core framework</li>
+ <li><a
href="/avatica/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="/avatica/apidocs/org/apache/calcite/avatica/server/package-summary.html">org.apache.calcite.avatica.server</a>
HTTP server</li>
+ <li><a
href="/avatica/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>
+
+<h2 id="clients">Clients</h2>
+
+<p>The following is a list of available Avatica clients. Several describe
+themselves as adapters for
+<a href="http://phoenix.apache.org";>Apache Phoenix</a> but also work with other
+Avatica back-ends. Contributions for clients in other languages are
+highly welcomed!</p>
+
+<h3 id="microsoft-net-driver-for-apache-phoenix-query-server">Microsoft .NET
driver for Apache Phoenix Query Server</h3>
+<ul>
+ <li><a href="https://github.com/Azure/hdinsight-phoenix-sharp";>Home
page</a></li>
+ <li>Language: C#</li>
+ <li><em>License</em>: <a
href="https://www.apache.org/licenses/LICENSE-2.0";>Apache 2.0</a></li>
+ <li>Avatica version 1.2.0 onwards</li>
+ <li><em>Maintainer</em>: Microsoft Azure</li>
+</ul>
+
+<h3 id="apache-phoenixavatica-sql-driver">Apache Phoenix/Avatica SQL
Driver</h3>
+<ul>
+ <li><a href="https://github.com/apache/calcite-avatica-go";>Home page</a></li>
+ <li><em>Language</em>: Go</li>
+ <li><em>License</em>: <a
href="https://www.apache.org/licenses/LICENSE-2.0";>Apache 2.0</a></li>
+ <li>Avatica version 1.8.0 onwards</li>
+ <li><em>Maintainer</em>: Boostport and the Apache Calcite community</li>
+</ul>
+
+<h3 id="avatica-thin-client">Avatica thin client</h3>
+<ul>
+ <li><a href="https://calcite.apache.org/avatica";>Home page</a></li>
+ <li><em>Language</em>: Java</li>
+ <li><em>License</em>: <a
href="https://www.apache.org/licenses/LICENSE-2.0";>Apache 2.0</a></li>
+ <li>Any Avatica version</li>
+ <li><em>Maintainer</em>: Apache Calcite community</li>
+</ul>
+
+<h3 id="apache-phoenix-database-adapter-for-python">Apache Phoenix database
adapter for Python</h3>
+<ul>
+ <li><a href="https://bitbucket.org/lalinsky/python-phoenixdb";>Home
page</a></li>
+ <li>Language: Python</li>
+ <li><em>License</em>: <a
href="https://www.apache.org/licenses/LICENSE-2.0";>Apache 2.0</a></li>
+ <li>Avatica version 1.2.0 to 1.6.0</li>
+ <li><em>Maintainer</em>: Lukáš Lalinský</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>Avatica Reference</h4>
+
+
+<ul>
+
+
+
+
+
+
+
+
+ <li class=""><a href="/avatica/docs/client_reference.html">Client
Reference</a></li>
+
+
+
+
+
+
+
+
+
+ <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>
+
+
+
+
+
+
+
+
+
+ <li class=""><a href="/avatica/docs/security.html">Security</a></li>
+
+
+
+
+
+
+
+
+
+ <li class=""><a
href="/avatica/docs/compatibility.html">Compatibility</a></li>
+
+
+
+
+
+
+
+
+
+ <li class=""><a href="/avatica/docs/custom_client_artifacts.html">Custom
Client Artifacts</a></li>
+
+
+
+
+
+
+
+
+
+ <li class=""><a href="/avatica/docs/docker.html">Docker Images</a></li>
+
+
+
+
+
+
+
+
+
+ <li class=""><a href="/avatica/docs/protocol_testing.html">Protocol
Testing</a></li>
+
+
+</ul>
+
+
+ <h4>Avatica Go Client Reference</h4>
+
+
+<ul>
+
+
+
+
+
+
+
+
+ <li class=""><a href="/avatica/docs/go_client_reference.html">Go Client
Reference</a></li>
+
+
+</ul>
+
+
+ <h4>Avatica Meta</h4>
+
+
+<ul>
+
+
+
+
+
+
+
+
+ <li class=""><a href="/avatica/docs/history.html">History</a></li>
+
+
+
+
+
+
+
+
+
+ <li class=""><a href="/avatica/docs/api/">API</a></li>
+
+
+
+
+
+
+
+
+
+ <li class=""><a href="/avatica/docs/testapi/">Test API</a></li>
+
+
+</ul>
+
+
+ <h4>Avatica Go Client Meta</h4>
+
+
+<ul>
+
+
+
+
+
+
+
+
+ <li class=""><a href="/avatica/docs/go_history.html">Go Client
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 © 2018
+ <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>
Propchange: calcite/site/avatica/docs/index.html
------------------------------------------------------------------------------
svn:executable = *
![https://raw.githubusercontent.com/julianhyde/share/master/slides/avatica-architecture.png"](https://raw.githubusercontent.com/julianhyde/share/master/slides/avatica-architecture.png"){kind=link}