blob: a32cbac0cc9a4c56515ca3eb03ad67641d0867f3 [file] [log] [blame]
<!DOCTYPE HTML>
<html lang="en-US">
<head>
<meta charset="UTF-8">
<title>Custom Client Artifacts</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>Custom Client Artifacts</h1>
<!--
-->
<p>As of Apache Calcite Avatica 1.9.0, there are two artifacts (jars) provided that enable client-access
to an Avatica server over JDBC.</p>
<figure class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="nt">&lt;dependencies&gt;</span>
<span class="c">&lt;!-- Shaded artifact --&gt;</span>
<span class="nt">&lt;dependency&gt;</span>
<span class="nt">&lt;groupId&gt;</span>org.apache.calcite.avatica<span class="nt">&lt;/groupId&gt;</span>
<span class="nt">&lt;artifactId&gt;</span>avatica<span class="nt">&lt;/artifactId&gt;</span>
<span class="nt">&lt;/dependency&gt;</span>
<span class="c">&lt;!-- Non-shaded artifact --&gt;</span>
<span class="nt">&lt;dependency&gt;</span>
<span class="nt">&lt;groupId&gt;</span>org.apache.calcite.avatica<span class="nt">&lt;/groupId&gt;</span>
<span class="nt">&lt;artifactId&gt;</span>avatica-core<span class="nt">&lt;/artifactId&gt;</span>
<span class="nt">&lt;/dependency&gt;</span>
<span class="nt">&lt;/dependencies&gt;</span></code></pre></figure>
<p>In keeping with the convention of previous releases, <code class="highlighter-rouge">org.apache.calcite.avatica:avatica</code> is a JAR
which contains all of the necessary dependencies of the Avatica client code base. Those classes which
can be safely relocated are done so to reduce the potential for classpath issues.</p>
<p>Avatica 1.9.0 will introduce a new artifact <code class="highlighter-rouge">org.apache.calcite.avatica:avatica-core</code> which is only
the Avatica client classes without any bundled dependencies. This artifact enables users to build a
classpath with different versions of JARs than what Avatica presently depends upon. This is a “your-mileage-may-vary”
or “void-your-warranty” type of decision (as you are using Avatica with dependecies which we have not tested);
however, some downstream projects do provide reasonable assurances of compatibilities across releases.</p>
<h2 id="building-your-own-avatica-client-artifact">Building your own Avatica client artifact</h2>
<p>In some cases, it may be beneficial to provide specific versions of Avatica dependencies. Here is
a brief <code class="highlighter-rouge">pom.xml</code> which outlines how this can be done.</p>
<figure class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="cp">&lt;?xml version="1.0" encoding="UTF-8"?&gt;</span>
<span class="nt">&lt;project</span> <span class="na">xmlns=</span><span class="s">"http://maven.apache.org/POM/4.0.0"</span> <span class="na">xmlns:xsi=</span><span class="s">"http://www.w3.org/2001/XMLSchema-instance"</span> <span class="na">xsi:schemaLocation=</span><span class="s">"http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"</span><span class="nt">&gt;</span>
<span class="nt">&lt;modelVersion&gt;</span>4.0.0<span class="nt">&lt;/modelVersion&gt;</span>
<span class="nt">&lt;groupId&gt;</span>myorg.custom.client<span class="nt">&lt;/groupId&gt;</span>
<span class="nt">&lt;artifactId&gt;</span>my-special-app-client<span class="nt">&lt;/artifactId&gt;</span>
<span class="nt">&lt;packaging&gt;</span>jar<span class="nt">&lt;/packaging&gt;</span>
<span class="nt">&lt;name&gt;</span>Special Application Client Artifact<span class="nt">&lt;/name&gt;</span>
<span class="nt">&lt;description&gt;</span>A custom artifact which uses Apache Calcite Avatica for my Org's Special Application<span class="nt">&lt;/description&gt;</span>
<span class="nt">&lt;properties&gt;</span>
<span class="nt">&lt;myorg.prefix&gt;</span>myorg.custom.client<span class="nt">&lt;/myorg.prefix&gt;</span>
<span class="nt">&lt;/properties&gt;</span>
<span class="nt">&lt;dependencies&gt;</span>
<span class="nt">&lt;dependency&gt;</span>
<span class="nt">&lt;groupId&gt;</span>org.apache.calcite.avatica<span class="nt">&lt;/groupId&gt;</span>
<span class="nt">&lt;artifactId&gt;</span>avatica-core<span class="nt">&lt;/artifactId&gt;</span>
<span class="nt">&lt;version&gt;</span>1.9.0<span class="nt">&lt;/version&gt;</span>
<span class="nt">&lt;/dependency&gt;</span>
<span class="nt">&lt;dependency&gt;</span>
<span class="nt">&lt;groupId&gt;</span>org.apache.httpcomponents<span class="nt">&lt;/groupId&gt;</span>
<span class="nt">&lt;artifactId&gt;</span>httpclient<span class="nt">&lt;/artifactId&gt;</span>
<span class="c">&lt;!-- Override the version from avatica-core (4.5.2) to address a hypothetical bug in httpclient --&gt;</span>
<span class="nt">&lt;version&gt;</span>4.5.3<span class="nt">&lt;/version&gt;</span>
<span class="nt">&lt;/dependency&gt;</span>
<span class="c">&lt;!-- Include Guava for the "Special Application" --&gt;</span>
<span class="nt">&lt;dependency&gt;</span>
<span class="nt">&lt;groupId&gt;</span>com.google.guava<span class="nt">&lt;/groupId&gt;</span>
<span class="nt">&lt;artifactId&gt;</span>guava<span class="nt">&lt;/artifactId&gt;</span>
<span class="nt">&lt;version&gt;</span>17.0<span class="nt">&lt;/version&gt;</span>
<span class="nt">&lt;/dependency&gt;</span>
<span class="nt">&lt;/dependencies&gt;</span>
<span class="nt">&lt;build&gt;</span>
<span class="nt">&lt;plugins&gt;</span>
<span class="nt">&lt;plugin&gt;</span>
<span class="nt">&lt;groupId&gt;</span>org.apache.maven.plugins<span class="nt">&lt;/groupId&gt;</span>
<span class="nt">&lt;artifactId&gt;</span>maven-shade-plugin<span class="nt">&lt;/artifactId&gt;</span>
<span class="nt">&lt;executions&gt;</span>
<span class="nt">&lt;execution&gt;</span>
<span class="nt">&lt;phase&gt;</span>package<span class="nt">&lt;/phase&gt;</span>
<span class="nt">&lt;goals&gt;</span>
<span class="nt">&lt;goal&gt;</span>shade<span class="nt">&lt;/goal&gt;</span>
<span class="nt">&lt;/goals&gt;</span>
<span class="nt">&lt;configuration&gt;</span>
<span class="c">&lt;!-- Relocate Jackson, Protobuf, Apache Commons HttpClient and HttpComponents, but not Guava.
The hypothetical "Special App" would be expecting Guava in the standard location --&gt;</span>
<span class="nt">&lt;relocations&gt;</span>
<span class="nt">&lt;relocation&gt;</span>
<span class="nt">&lt;pattern&gt;</span>com.fasterxml.jackson<span class="nt">&lt;/pattern&gt;</span>
<span class="nt">&lt;shadedPattern&gt;</span>${myorg.prefix}.com.fasterxml.jackson<span class="nt">&lt;/shadedPattern&gt;</span>
<span class="nt">&lt;/relocation&gt;</span>
<span class="nt">&lt;relocation&gt;</span>
<span class="nt">&lt;pattern&gt;</span>com.google.protobuf<span class="nt">&lt;/pattern&gt;</span>
<span class="nt">&lt;shadedPattern&gt;</span>${myorg.prefix}.com.google.protobuf<span class="nt">&lt;/shadedPattern&gt;</span>
<span class="nt">&lt;/relocation&gt;</span>
<span class="nt">&lt;relocation&gt;</span>
<span class="nt">&lt;pattern&gt;</span>org.apache.http<span class="nt">&lt;/pattern&gt;</span>
<span class="nt">&lt;shadedPattern&gt;</span>${myorg.prefix}.org.apache.http<span class="nt">&lt;/shadedPattern&gt;</span>
<span class="nt">&lt;/relocation&gt;</span>
<span class="nt">&lt;relocation&gt;</span>
<span class="nt">&lt;pattern&gt;</span>org.apache.commons<span class="nt">&lt;/pattern&gt;</span>
<span class="nt">&lt;shadedPattern&gt;</span>${myorg.prefix}.org.apache.commons<span class="nt">&lt;/shadedPattern&gt;</span>
<span class="nt">&lt;/relocation&gt;</span>
<span class="nt">&lt;/relocations&gt;</span>
<span class="nt">&lt;createDependencyReducedPom&gt;</span>false<span class="nt">&lt;/createDependencyReducedPom&gt;</span>
<span class="nt">&lt;/configuration&gt;</span>
<span class="nt">&lt;/execution&gt;</span>
<span class="nt">&lt;/executions&gt;</span>
<span class="nt">&lt;/plugin&gt;</span>
<span class="nt">&lt;/plugins&gt;</span>
<span class="nt">&lt;/build&gt;</span>
<span class="nt">&lt;/project&gt;</span></code></pre></figure>
<div class="section-nav">
<div class="left align-right">
<a href="/avatica/docs/compatibility.html" class="prev">Previous</a>
</div>
<div class="right align-left">
<a href="/avatica/docs/docker.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=""><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="current"><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>
<li class=""><a href="/avatica/docs/go_howto.html">HOWTO</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 &copy;&nbsp;2019
<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&nbsp;License&nbsp;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>