http://git-wip-us.apache.org/repos/asf/calcite-avatica/blob/fc7b26c8/avatica/site/_docs/custom_client_artifacts.md ---------------------------------------------------------------------- diff --git a/avatica/site/_docs/custom_client_artifacts.md b/avatica/site/_docs/custom_client_artifacts.md deleted file mode 100644 index f128a4f..0000000 --- a/avatica/site/_docs/custom_client_artifacts.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -layout: docs -title: Custom Client Artifacts -permalink: /docs/custom_client_artifacts.html ---- - -<!-- -{% comment %} -Licensed to the Apache Software Foundation (ASF) under one or more -contributor license agreements. See the NOTICE file distributed with -this work for additional information regarding copyright ownership. -The ASF licenses this file to you under the Apache License, Version 2.0 -(the "License"); you may not use this file except in compliance with -the License. You may obtain a copy of the License at - -http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. -{% endcomment %} ---> - -As of Apache Calcite Avatica 1.9.0, there are two artifacts (jars) provided that enable client-access -to an Avatica server over JDBC. - -{% highlight xml %} -<dependencies> - <!-- Shaded artifact --> - <dependency> - <groupId>org.apache.calcite.avatica</groupId> - <artifactId>avatica</artifactId> - </dependency> - <!-- Non-shaded artifact --> - <dependency> - <groupId>org.apache.calcite.avatica</groupId> - <artifactId>avatica-core</artifactId> - </dependency> -</dependencies> -{% endhighlight %} - -In keeping with the convention of previous releases, `org.apache.calcite.avatica:avatica` 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. - -Avatica 1.9.0 will introduce a new artifact `org.apache.calcite.avatica:avatica-core` 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. - -## Building your own Avatica client artifact - -In some cases, it may be beneficial to provide specific versions of Avatica dependencies. Here is -a brief `pom.xml` which outlines how this can be done. - -{% highlight xml %} -<?xml version="1.0" encoding="UTF-8"?> -<project xmlns="http://maven.apache.org/POM/4.0.0"; xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd";> - <modelVersion>4.0.0</modelVersion> - <groupId>myorg.custom.client</groupId> - <artifactId>my-special-app-client</artifactId> - <packaging>jar</packaging> - <name>Special Application Client Artifact</name> - <description>A custom artifact which uses Apache Calcite Avatica for my Org's Special Application</description> - - <properties> - <myorg.prefix>myorg.custom.client</myorg.prefix> - </properties> - - <dependencies> - <dependency> - <groupId>org.apache.calcite.avatica</groupId> - <artifactId>avatica-core</artifactId> - <version>1.9.0</version> - </dependency> - <dependency> - <groupId>org.apache.httpcomponents</groupId> - <artifactId>httpclient</artifactId> - <!-- Override the version from avatica-core (4.5.2) to address a hypothetical bug in httpclient --> - <version>4.5.3</version> - </dependency> - <!-- Include Guava for the "Special Application" --> - <dependency> - <groupId>com.google.guava</groupId> - <artifactId>guava</artifactId> - <version>17.0</version> - </dependency> - </dependencies> - - <build> - <plugins> - <plugin> - <groupId>org.apache.maven.plugins</groupId> - <artifactId>maven-shade-plugin</artifactId> - <executions> - <execution> - <phase>package</phase> - <goals> - <goal>shade</goal> - </goals> - <configuration> - <!-- Relocate Jackson, Protobuf, Apache Commons HttpClient and HttpComponents, but not Guava. - The hypothetical "Special App" would be expecting Guava in the standard location --> - <relocations> - <relocation> - <pattern>com.fasterxml.jackson</pattern> - <shadedPattern>${myorg.prefix}.com.fasterxml.jackson</shadedPattern> - </relocation> - <relocation> - <pattern>com.google.protobuf</pattern> - <shadedPattern>${myorg.prefix}.com.google.protobuf</shadedPattern> - </relocation> - <relocation> - <pattern>org.apache.http</pattern> - <shadedPattern>${myorg.prefix}.org.apache.http</shadedPattern> - </relocation> - <relocation> - <pattern>org.apache.commons</pattern> - <shadedPattern>${myorg.prefix}.org.apache.commons</shadedPattern> - </relocation> - </relocations> - <createDependencyReducedPom>false</createDependencyReducedPom> - </configuration> - </execution> - </executions> - </plugin> - </plugins> - </build> -</project> -{% endhighlight %}
http://git-wip-us.apache.org/repos/asf/calcite-avatica/blob/fc7b26c8/avatica/site/_docs/history.md ---------------------------------------------------------------------- diff --git a/avatica/site/_docs/history.md b/avatica/site/_docs/history.md deleted file mode 100644 index 6e5184f..0000000 --- a/avatica/site/_docs/history.md +++ /dev/null @@ -1,314 +0,0 @@ ---- -layout: docs -title: History -permalink: "/docs/history.html" ---- - -<!-- -{% comment %} -Licensed to the Apache Software Foundation (ASF) under one or more -contributor license agreements. See the NOTICE file distributed with -this work for additional information regarding copyright ownership. -The ASF licenses this file to you under the Apache License, Version 2.0 -(the "License"); you may not use this file except in compliance with -the License. You may obtain a copy of the License at - -http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. -{% endcomment %} ---> - -For a full list of releases, see -<a href="https://github.com/apache/calcite/releases";>github</a>. -Downloads are available on the -[downloads page]({{ site.baseurl }}/downloads/). - -## <a href="https://github.com/apache/calcite/releases/tag/calcite-avatica-1.9.0";>1.9.0</a> / 2016-11-01 -{: #v1-9-0} - -Apache Calcite Avatica 1.9.0 includes various improvements to make it -more robust and secure, while maintaining API and protocol -compatibility with previous versions. We now include non-shaded and -shaded artifacts, to make it easier to embed Avatica in your -application. There is improved support for the JDBC API, including -better type conversions and support for canceling statements. The -transport is upgraded to use protobuf-3.1.0 (previously 3.0 beta). - -Compatibility: This release is tested -on Linux, macOS, Microsoft Windows; -using Oracle JDK 1.7, 1.8; -Guava versions 14.0 to 19.0; -other software versions as specified in `pom.xml`. - -Features and bug fixes - -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1471";>CALCITE-1471</a>] - `HttpServerSpnegoWithJaasTest.testAuthenticatedClientsAllowed` fails on Windows - (Aaron Mihalik) -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1464";>CALCITE-1464</a>] - Upgrade Jetty version to 9.2.19v20160908 -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1463";>CALCITE-1463</a>] - In `standalone-server` jar, relocate dependencies rather than excluding them -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1355";>CALCITE-1355</a>] - Upgrade to protobuf-java 3.1.0 -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1462";>CALCITE-1462</a>] - Remove Avatica pom cruft -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1458";>CALCITE-1458</a>] - Add column values to the deprecated protobuf attribute -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1433";>CALCITE-1433</a>] - Add missing dependencies to `avatica-server` -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1433";>CALCITE-1433</a>] - Fix missing avatica `test-jar` dependency -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1423";>CALCITE-1423</a>] - Add method `ByteString.indexOf(ByteString, int)` -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1408";>CALCITE-1408</a>] - `ResultSet.getXxx` methods should throw `SQLDataException` if cannot convert to - the requested type (Laurent Goujon) -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1410";>CALCITE-1410</a>] - Fix JDBC metadata classes (Laurent Goujon) -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1224";>CALCITE-1224</a>] - Publish non-shaded and shaded versions of Avatica client artifacts -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1407";>CALCITE-1407</a>] - `MetaImpl.fieldMetaData` wrongly uses 1-based column ordinals -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1361";>CALCITE-1361</a>] - Remove entry from `AvaticaConnection.flagMap` when session closed -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1399";>CALCITE-1399</a>] - Make the jcommander `SerializationConverter` public -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1394";>CALCITE-1394</a>] - Javadoc warnings due to `CoreMatchers.containsString` and `mockito-all` -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1390";>CALCITE-1390</a>] - Avatica JDBC driver wrongly modifies `Properties` object -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1371";>CALCITE-1371</a>] - `PreparedStatement` does not process Date type correctly (Billy (Yiming) Liu) -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1301";>CALCITE-1301</a>] - Add `cancel` flag to `AvaticaStatement` -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1315";>CALCITE-1315</a>] - Retry the request on `NoHttpResponseException` -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1300";>CALCITE-1300</a>] - Retry on HTTP-503 in hc-based `AvaticaHttpClient` -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1263";>CALCITE-1263</a>] - Case-insensitive match and null default value for `enum` properties -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1282";>CALCITE-1282</a>] - Adds an API method to set extra allowed Kerberos realms - -Tests - -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1226";>CALCITE-1226</a>] - Disable `AvaticaSpnegoTest` due to intermittent failures - -Web site and documentation - -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1369";>CALCITE-1369</a>] - Add list of Avatica clients to the web site -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1229";>CALCITE-1229</a>] - Restore API and Test API links to site -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1287";>CALCITE-1287</a>] - TCK test for binary columns -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1285";>CALCITE-1285</a>] - Fix client URL template in example config file - -## <a href="https://github.com/apache/calcite/releases/tag/calcite-avatica-1.8.0";>1.8.0</a> / 2016-06-04 -{: #v1-8-0} - -Apache Calcite Avatica 1.8.0 continues the focus on compatibility with previous -versions while also adding support for authentication between Avatica client and server. -Performance, notably on the write-path, is also major area of improvement -in this release, increasing as much as two to three times over previous versions -with the addition of new API support. The documentation for both users and developers -continues to receive improvements. - -A number of protocol issues are resolved relating to the proper serialization of -decimals, the wire-API semantics of signed integers that were marked as unsigned -integers, and the unintentional Base64-encoding of binary data using the Protocol -Buffers serialization in Avatica. These issues were fixed in such a way to be -backwards compatible, but older clients/servers may still compute incorrect data. - -Users of Avatica 1.7.x should not notice any issues in upgrading existing applications -and are encouraged to upgrade as soon as possible. - -Features and bug fixes - -* [<a href='https://issues.apache.org/jira/browse/CALCITE-1159'>CALCITE-1159</a>] - Support Kerberos-authenticated clients using SPNEGO -* [<a href='https://issues.apache.org/jira/browse/CALCITE-1173'>CALCITE-1173</a>] - Basic and Digest authentication -* [<a href='https://issues.apache.org/jira/browse/CALCITE-1249'>CALCITE-1249</a>] - L&N incorrect for source and non-shaded jars for avatica-standalone-server module -* [<a href='https://issues.apache.org/jira/browse/CALCITE-1103'>CALCITE-1103</a>] - Decimal data serialized as Double in Protocol Buffer API -* [<a href='https://issues.apache.org/jira/browse/CALCITE-1205'>CALCITE-1205</a>] - Inconsistency in protobuf TypedValue field names -* [<a href='https://issues.apache.org/jira/browse/CALCITE-1207'>CALCITE-1207</a>] - Allow numeric connection properties, and K, M, G suffixes -* [<a href='https://issues.apache.org/jira/browse/CALCITE-1209'>CALCITE-1209</a>] - Byte strings not being correctly decoded when sent to avatica using protocol buffers -* [<a href='https://issues.apache.org/jira/browse/CALCITE-1213'>CALCITE-1213</a>] - Changing AvaticaDatabaseMetaData from class to interface breaks compatibility -* [<a href='https://issues.apache.org/jira/browse/CALCITE-1218'>CALCITE-1218</a>] - Mishandling of uncaught exceptions results in no ErrorResponse sent to client -* [<a href='https://issues.apache.org/jira/browse/CALCITE-1230'>CALCITE-1230</a>] - Add SQLSTATE reference data as enum SqlState -* [<a href='https://issues.apache.org/jira/browse/CALCITE-1243'>CALCITE-1243</a>] - max_row_count in protobuf Requests should be signed int -* [<a href='https://issues.apache.org/jira/browse/CALCITE-1247'>CALCITE-1247</a>] - JdbcMeta#prepare doesn't set maxRowCount on the Statement -* [<a href='https://issues.apache.org/jira/browse/CALCITE-1254'>CALCITE-1254</a>] - Support PreparedStatement.executeLargeBatch -* [<a href='https://issues.apache.org/jira/browse/CALCITE-643'>CALCITE-643</a>] - User authentication for avatica clients -* [<a href='https://issues.apache.org/jira/browse/CALCITE-1128'>CALCITE-1128</a>] - Support addBatch()/executeBatch() in remote driver -* [<a href='https://issues.apache.org/jira/browse/CALCITE-1179'>CALCITE-1179</a>] - Extend list of time units and time unit ranges -* [<a href='https://issues.apache.org/jira/browse/CALCITE-1180'>CALCITE-1180</a>] - Support clearBatch() in remote driver -* [<a href='https://issues.apache.org/jira/browse/CALCITE-1185'>CALCITE-1185</a>] - Send back ErrorResponse on failure to parse requests -* [<a href='https://issues.apache.org/jira/browse/CALCITE-1192'>CALCITE-1192</a>] - Document protobuf and json REP types with examples -* [<a href='https://issues.apache.org/jira/browse/CALCITE-1214'>CALCITE-1214</a>] - Support url-based kerberos login -* [<a href='https://issues.apache.org/jira/browse/CALCITE-1236'>CALCITE-1236</a>] - Log exceptions sent back to client in server log -* [<a href='https://issues.apache.org/jira/browse/CALCITE-836'>CALCITE-836</a>] - Provide a way for the Avatica client to query the server versions -* [<a href='https://issues.apache.org/jira/browse/CALCITE-1156'>CALCITE-1156</a>] - Bump jetty version -* [<a href='https://issues.apache.org/jira/browse/CALCITE-1184'>CALCITE-1184</a>] - Update Kerby dependency to 1.0.0-RC2 - -Tests - -* [<a href='https://issues.apache.org/jira/browse/CALCITE-1190'>CALCITE-1190</a>] - Cross-Version Compatibility Test Harness -* [<a href='https://issues.apache.org/jira/browse/CALCITE-1113'>CALCITE-1113</a>] - Parameter precision and scale are not returned from Avatica REST API -* [<a href='https://issues.apache.org/jira/browse/CALCITE-1186'>CALCITE-1186</a>] - Parameter 'signed' metadata is always returned as false -* [<a href='https://issues.apache.org/jira/browse/CALCITE-1189'>CALCITE-1189</a>] - Unit test failure when JVM default charset is not UTF-8 -* [<a href='https://issues.apache.org/jira/browse/CALCITE-1061'>CALCITE-1061</a>] - RemoteMetaTest#testRemoteStatementInsert's use of hsqldb isn't guarded -* [<a href='https://issues.apache.org/jira/browse/CALCITE-1194'>CALCITE-1194</a>] - Avatica metrics has non-test dependency on JUnit -* [<a href='https://issues.apache.org/jira/browse/CALCITE-835'>CALCITE-835</a>] - Unicode character seems to be handled incorrectly in Avatica - -Web site and documentation - -* [<a href='https://issues.apache.org/jira/browse/CALCITE-1251'>CALCITE-1251</a>] - Write release notes -* [<a href='https://issues.apache.org/jira/browse/CALCITE-1201'>CALCITE-1201</a>] - Bad character in JSON docs -* [<a href='https://issues.apache.org/jira/browse/CALCITE-1267'>CALCITE-1267</a>] - Point to release notes on website in README -* [<a href='https://issues.apache.org/jira/browse/CALCITE-1163'>CALCITE-1163</a>] - Avatica sub-site logo leads to Calcite site instead of Avatica's -* [<a href='https://issues.apache.org/jira/browse/CALCITE-1202'>CALCITE-1202</a>] - Lock version of Jekyll used by website - -## <a href="https://github.com/apache/calcite/releases/tag/calcite-avatica-1.7.1";>1.7.1</a> / 2016-03-18 -{: #v1-7-1} - -This is the first release of Avatica as an independent project. (It -is still governed by Apache Calcite's PMC, and stored in the same git -repository as Calcite, but releases are no longer synchronized, and -Avatica does not depend on any Calcite modules.) - -One notable technical change is that we have replaced JUL (`java.util.logging`) -with [SLF4J](http://slf4j.org/). SLF4J provides an API that Avatica can use -independent of the logging implementation. This is more -flexible for users: they can configure Avatica's logging within their -own chosen logging framework. This work was done in -[[CALCITE-669](https://issues.apache.org/jira/browse/CALCITE-669)]. - -If you have configured JUL in Calcite/Avatica previously, you'll -notice some differences, because JUL's `FINE`, `FINER` and `FINEST` -logging levels do not exist in SLF4J. To deal with this, we mapped -`FINE` to SLF4J's `DEBUG` level, and mapped `FINER` and `FINEST` to -SLF4J's `TRACE`. - -The performance of Avatica was an important focus for this release as well. -Numerous improvements aimed at reducing the overall latency of Avatica RPCs -was reduced. Some general testing showed an overall reduction of latency -by approximately 15% over the previous release. - -Compatibility: This release is tested on Linux, Mac OS X, Microsoft -Windows; using Oracle JDK 1.7, 1.8; Guava versions 12.0.1 to 19.0; -other software versions as specified in `pom.xml`. - -Features and bug fixes - -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1156";>CALCITE-1156</a>] - Upgrade Jetty from 9.2.7.v20150116 to 9.2.15.v20160210 -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1141";>CALCITE-1141</a>] - Bump `version.minor` for Avatica -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1132";>CALCITE-1132</a>] - Update `artifactId`, `groupId` and `name` for Avatica -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1064";>CALCITE-1064</a>] - Address problematic `maven-remote-resources-plugin` -* In `TimeUnit` add `WEEK`, `QUARTER`, `MICROSECOND` values, and change type of - `multiplier` -* Update `groupId` when Calcite POMs reference Avatica modules -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1078";>CALCITE-1078</a>] - Detach avatica from the core calcite Maven project -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1117";>CALCITE-1117</a>] - Default to a `commons-httpclient` implementation -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1118";>CALCITE-1118</a>] - Add a noop-JDBC driver for testing Avatica server -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1119";>CALCITE-1119</a>] - Additional metrics instrumentation for request processing -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1094";>CALCITE-1094</a>] - Replace `ByteArrayOutputStream` to avoid synchronized writes -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1092";>CALCITE-1092</a>] - Use singleton descriptor instances for protobuf field presence checks -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1093";>CALCITE-1093</a>] - Reduce impact of `ArrayList` performance -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1086";>CALCITE-1086</a>] - Avoid sending `Signature` on `Execute` for updates -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1031";>CALCITE-1031</a>] - In prepared statement, `CsvScannableTable.scan` is called twice -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1085";>CALCITE-1085</a>] - Use a `NoopContext` singleton in `NoopTimer` -* [<a href="https://issues.apache.org/jira/browse/CALCITE-642";>CALCITE-642</a>] - Add an avatica-metrics API -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1071";>CALCITE-1071</a>] - Improve hash functions -* [<a href="https://issues.apache.org/jira/browse/CALCITE-669";>CALCITE-669</a>] - Mass removal of Java Logging for SLF4J -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1067";>CALCITE-1067</a>] - Test failures due to clashing temporary table names -* [<a href="https://issues.apache.org/jira/browse/CALCITE-999";>CALCITE-999</a>] - Clean up maven POM files - -Web site and documentation - -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1142";>CALCITE-1142</a>] - Create a `README` for Avatica -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1144";>CALCITE-1144</a>] - Fix `LICENSE` for Avatica -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1143";>CALCITE-1143</a>] - Remove unnecessary `NOTICE` for Avatica -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1139";>CALCITE-1139</a>] - Update Calcite's `KEYS` and add a copy for Avatica -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1140";>CALCITE-1140</a>] - Release notes and website updates for Avatica 1.7 -* Instructions for Avatica site -* New logo and color scheme for Avatica site -* [<a href="https://issues.apache.org/jira/browse/CALCITE-1079";>CALCITE-1079</a>] - Split out an Avatica website, made to slot into the Calcite site at `/avatica` - -## Past releases - -Prior to release 1.7.1, Avatica was released as part of Calcite. Maven -modules had groupId 'org.apache.calcite' and module names -'calcite-avatica', 'calcite-avatica-server' etc. - -Please refer to the -[Calcite release page](https://calcite.apache.org/docs/history.html) -for information about previous Avatica releases. http://git-wip-us.apache.org/repos/asf/calcite-avatica/blob/fc7b26c8/avatica/site/_docs/howto.md ---------------------------------------------------------------------- diff --git a/avatica/site/_docs/howto.md b/avatica/site/_docs/howto.md deleted file mode 100644 index 24689b5..0000000 --- a/avatica/site/_docs/howto.md +++ /dev/null @@ -1,535 +0,0 @@ ---- -layout: docs -title: HOWTO -permalink: /docs/howto.html ---- - -<!-- -{% comment %} -Licensed to the Apache Software Foundation (ASF) under one or more -contributor license agreements. See the NOTICE file distributed with -this work for additional information regarding copyright ownership. -The ASF licenses this file to you under the Apache License, Version 2.0 -(the "License"); you may not use this file except in compliance with -the License. You may obtain a copy of the License at - -http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. -{% endcomment %} ---> - -Here's some miscellaneous documentation about using Calcite and its various -adapters. - -* TOC -{:toc} - -## Building from a source distribution - -Prerequisites are maven (3.2.1 or later) -and Java (JDK 1.7 or later, 1.8 preferred) on your path. - -Unpack the source distribution `.tar.gz` or `.zip` file, -`cd` to the root directory of the unpacked source, -then build using maven: - -{% highlight bash %} -$ tar xvfz apache-calcite-avatica-1.9.0-src.tar.gz -$ cd apache-calcite-avatica-1.9.0-src -$ mvn install -{% endhighlight %} - -[Running tests](#running-tests) describes how to run more or fewer -tests. - -## Building from git - -Prerequisites are git, maven (3.2.1 or later) -and Java (JDK 1.7 or later, 1.8 preferred) on your path. - -Create a local copy of the github repository, -`cd` to its root directory, -then build using maven: - -{% highlight bash %} -$ git clone git://github.com/apache/calcite.git -$ cd calcite/avatica -$ mvn install -{% endhighlight %} - -[Running tests](#running-tests) describes how to run more or fewer -tests. - -## Running tests - -The test suite will run by default when you build, unless you specify -`-DskipTests`: - -{% highlight bash %} -$ mvn clean verify -Dcheckstyle.skip -{% endhighlight %} - -By default, invoking the `verify` 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. - -## Contributing - -See the [developers guide]({{ site.baseurl }}/develop/#contributing). - -## Getting started - -See the [developers guide]({{ site.baseurl }}/develop/#getting-started). - -# Advanced topics for developers - -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. - -## Rebuilding generated Protocol Buffer code - -Calcite's Avatica Server component supports RPC serialization -using [Protocol Buffers](https://developers.google.com/protocol-buffers/). -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. - -Typically, the code generated by the Protocol Buffers library doesn't -need to be re-generated only every build, only when the schema changes. - -First, install Protobuf 3.1: - -{% highlight bash %} -$ wget https://github.com/google/protobuf/releases/download/v3.1.0/protobuf-java-3.1.0.tar.gz -$ tar xf protobuf-java-3.1.0.tar.gz && cd protobuf-3.1.0 -$ ./configure -$ make -$ sudo make install -{% endhighlight %} - -Then, re-generate the compiled code: - -{% highlight bash %} -$ cd avatica/core -$ ./src/main/scripts/generate-protobuf.sh -{% endhighlight %} - -# Advanced topics for committers - -The following sections are of interest to Calcite committers and in -particular release managers. - -## Set up PGP signing keys (for Calcite committers) - -Follow instructions [here](http://www.apache.org/dev/release-signing) to -create a key pair. (On Mac OS X, I did `brew install gpg` and -`gpg --gen-key`.) - -Add your public key to the `KEYS` file by following instructions in -the `KEYS` file. - -## Run a GPG agent - -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 `gpg-agent`. - -This can be started automatically via an `~/.xsession` on Linux or some -scripting in your shell's configuration script of choice (e.g. `~/.bashrc` or `~/.zshrc`) - -{% highlight bash %} -GPG_AGENT=$(which gpg-agent) -GPG_TTY=`tty` -export GPG_TTY -if [[ -f "$GPG_AGENT" ]]; then - envfile="${HOME}/.gnupg/gpg-agent.env" - - if test -f "$envfile" && kill -0 $(grep GPG_AGENT_INFO "$envfile" | cut -d: -f 2) 2>/dev/null; then - source "$envfile" - else - eval "$(gpg-agent --daemon --log-file=~/.gpg/gpg.log --write-env-file "$envfile")" - fi - export GPG_AGENT_INFO # the env file does not contain the export statement -fi -{% endhighlight %} - -Also, ensure that `default-cache-ttl 6000` is set in `~/.gnupg/gpg-agent.conf` -to guarantee that your credentials will be cached for the duration of the build. - -## Making a snapshot (for Calcite committers) - -Before you start: - -* Set up signing keys as described above. -* Make sure you are using JDK 1.7 (not 1.8). - -{% highlight bash %} -# Make sure that there are no junk files in the sandbox -git clean -xn - -mvn -Papache-release clean install -{% endhighlight %} - -When the dry-run has succeeded, change `install` to `deploy`. - -## Making a release (for Calcite committers) - -Before you start: - -* Set up signing keys as described above. -* Make sure you are using JDK 1.7 (not 1.8). -* Check that `README` and `site/_docs/howto.md` have the correct version number. -* Set `version.major` and `version.minor` in `pom.xml`. -* Trigger a - <a href="https://scan.coverity.com/projects/2966";>Coverity scan</a> - by merging the latest code into the `julianhyde/coverity_scan` branch, - and when it completes, make sure that there are no important issues. -* 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) - -Create a release branch named after the release, e.g. -`branch-avatica-1.9`, and push it to Apache. - -{% highlight bash %} -$ git checkout -b branch-avatica-X.Y -$ git push -u origin branch-avatica-X.Y -{% endhighlight %} - -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 `git merge --ff-only` 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.) - -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. - -If any of the steps fail, clean up (see below), fix the problem, and -start again from the top. - -{% highlight bash %} -# Make sure that there are no junk files in the sandbox -git clean -xn - -# Do a dry run of the release:prepare step, which sets version numbers. -mvn -DdryRun=true -DreleaseVersion=X.Y.Z -DdevelopmentVersion=X.Y.Z+1-SNAPSHOT -Dtag=calcite-avatica-X.Y.Z-rcN -Papache-release -Duser.name=${asf.username} release:prepare -{% endhighlight %} - -Check the artifacts: - -* In the `target` directory should be these 8 files, among others: - * apache-calcite-avatica-X.Y.Z-src.tar.gz - * apache-calcite-avatica-X.Y.Z-src.tar.gz.asc - * apache-calcite-avatica-X.Y.Z-src.tar.gz.md5 - * apache-calcite-avatica-X.Y.Z-src.tar.gz.sha1 - * apache-calcite-avatica-X.Y.Z-src.zip - * apache-calcite-avatica-X.Y.Z-src.zip.asc - * apache-calcite-avatica-X.Y.Z-src.zip.md5 - * apache-calcite-avatica-X.Y.Z-src.zip.sha1 -* Note that the file names start `apache-calcite-avatica-`. -* In the two source distros `.tar.gz` and `.zip` (currently there is - no binary distro), check that all files belong to a directory called - `apache-calcite-avatica-X.Y.Z-src`. -* That directory must contain files `NOTICE`, `LICENSE`, - `README`, `README.md` - * Check that the version in `README` is correct -* For each .jar, verify that the `META-INF` directory contains the correct - contents for `DEPENDENCIES`, `LICENSE` and `NOTICE` per the - source/classes contained. Refer to the ASF licensing documentation on - what is required. -* Check PGP, per [this](https://httpd.apache.org/dev/verification.html) - -If something is not correct, you can invoke the `release:clean` mojo to remove the -generated files from your workspace: - -{% highlight bash %} -mvn release:clean -{% endhighlight %} - -If successful, remove the `-DdryRun` flag and run the release for real. - -{% highlight bash %} -# Prepare sets the version numbers, creates a tag, and pushes it to git. -mvn -DreleaseVersion=X.Y.Z -DdevelopmentVersion=X.Y.Z+1-SNAPSHOT -Dtag=calcite-avatica-X.Y.Z-rc0 -Papache-release -Duser.name=${asf.username} release:prepare - -# Perform checks out the tagged version, builds, and deploys to the staging repository -mvn -Papache-release -Duser.name=${asf.username} release:perform -Darguments="-DskipTests" -{% endhighlight %} - -Verify the staged artifacts in the Nexus repository: - -* Go to [https://repository.apache.org/](https://repository.apache.org/) and login -* Under `Build Promotion`, click `Staging Repositories` -* In the `Staging Repositories` tab there should be a line with profile `org.apache.calcite` -* Navigate through the artifact tree and make sure the .jar, .pom, .asc files are present -* 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) - -Upload the artifacts via subversion to a staging area, -https://dist.apache.org/repos/dist/dev/calcite/apache-calcite-X.Y.Z-rcN: - -{% highlight bash %} -# Create a subversion workspace, if you haven't already -mkdir -p ~/dist/dev -pushd ~/dist/dev -svn co https://dist.apache.org/repos/dist/dev/calcite -popd - -# Move the files into a directory -cd target -mkdir ~/dist/dev/calcite/apache-calcite-avatica-X.Y.Z-rcN -mv apache-calcite-avatica-* ~/dist/dev/calcite/apache-calcite-avatica-X.Y.Z-rcN - -# Check in -cd ~/dist/dev/calcite -svn add apache-calcite-avatica-X.Y.Z-rcN -svn ci -{% endhighlight %} - -## Cleaning up after a failed release attempt (for Calcite committers) - -{% highlight bash %} -# Make sure that the tag you are about to generate does not already -# exist (due to a failed release attempt) -git tag - -# If the tag exists, delete it locally and remotely -git tag -d apache-calcite-X.Y.Z -git push origin :refs/tags/apache-calcite-avatica-X.Y.Z - -# Remove modified files -mvn release:clean - -# Check whether there are modified files and if so, go back to the -# original git commit -git status -git reset --hard HEAD -{% endhighlight %} - -## Validate a release - -{% highlight bash %} -# Check that the signing key (e.g. 2AD3FAE3) is pushed -gpg --recv-keys key - -# Check keys -curl -O https://dist.apache.org/repos/dist/release/calcite/KEYS - -# Sign/check md5 and sha1 hashes -# (Assumes your O/S has 'md5' and 'sha1' commands.) -function checkHash() { - cd "$1" - for i in *.{zip,pom,gz}; do - if [ ! -f $i ]; then - continue - fi - if [ -f $i.md5 ]; then - if [ "$(cat $i.md5)" = "$(md5 -q $i)" ]; then - echo $i.md5 present and correct - else - echo $i.md5 does not match - fi - else - md5 -q $i > $i.md5 - echo $i.md5 created - fi - if [ -f $i.sha1 ]; then - if [ "$(cat $i.sha1)" = "$(sha1 -q $i)" ]; then - echo $i.sha1 present and correct - else - echo $i.sha1 does not match - fi - else - sha1 -q $i > $i.sha1 - echo $i.sha1 created - fi - done -} -checkHash apache-calcite-X.Y.Z-rcN -{% endhighlight %} - -## Get approval for a release via Apache voting process (for Calcite committers) - -Release vote on dev list - -{% highlight 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/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-avatica-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 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 -{% endhighlight %} - -After vote finishes, send out the result: - -{% highlight 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 -{% endhighlight %} - -Use the [Apache URL shortener](http://s.apache.org) to generate -shortened URLs for the vote proposal and result emails. Examples: -[s.apache.org/calcite-1.2-vote](http://s.apache.org/calcite-1.2-vote) and -[s.apache.org/calcite-1.2-result](http://s.apache.org/calcite-1.2-result). - - -## Publishing a release (for Calcite committers) - -After a successful release vote, we need to push the release -out to mirrors, and other tasks. - -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. - -In JIRA, search for -[all issues resolved in this release](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), -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". - -Promote the staged nexus artifacts. - -* Go to [https://repository.apache.org/](https://repository.apache.org/) and login -* Under "Build Promotion" click "Staging Repositories" -* In the line with "orgapachecalcite-xxxx", check the box -* Press "Release" button - -Check the artifacts into svn. - -{% highlight bash %} -# Get the release candidate. -mkdir -p ~/dist/dev -cd ~/dist/dev -svn co https://dist.apache.org/repos/dist/dev/calcite - -# Copy the artifacts. Note that the copy does not have '-rcN' suffix. -mkdir -p ~/dist/release -cd ~/dist/release -svn co https://dist.apache.org/repos/dist/release/calcite -cd calcite -cp -rp ../../dev/calcite/apache-calcite-avatica-X.Y.Z-rcN apache-calcite-avatica-X.Y.Z -svn add apache-calcite-X.Y.Z - -# Check in. -svn ci -{% endhighlight %} - -Svnpubsub will publish to the -[release repo](https://dist.apache.org/repos/dist/release/calcite) and propagate to the -[mirrors](http://www.apache.org/dyn/closer.cgi/calcite) within 24 hours. - -If there are now more than 2 releases, clear out the oldest ones: - -{% highlight bash %} -cd ~/dist/release/calcite -svn rm apache-calcite-avatica-X.Y.Z -svn ci -{% endhighlight %} - -The old releases will remain available in the -[release archive](http://archive.apache.org/dist/calcite/). - -Add a release note by copying -[site/_posts/2015-11-10-release-1.5.0.md]({{ site.sourceRoot }}/site/_posts/2015-11-10-release-1.5.0.md), -generate the javadoc and copy to `site/target/apidocs` and `site/target/testapidocs`, -[publish the site](#publish-the-web-site), -and check that it appears in the contents in [news](http://localhost:4000/news/). - -After 24 hours, announce the release by sending an email to -[[email protected]](https://mail-archives.apache.org/mod_mbox/www-announce/). -You can use -[the 1.6.0 announcement](https://mail-archives.apache.org/mod_mbox/www-announce/201601.mbox/%3C8DB4C1E5-B322-4A33-8E8F-9858FA6A1119%40apache.org%3E) -as a template. Be sure to include a brief description of the project. - -## Publishing the web site (for Calcite committers) -{: #publish-the-web-site} - -See instructions in -[site/README.md]({{ site.sourceRoot }}/site/README.md). http://git-wip-us.apache.org/repos/asf/calcite-avatica/blob/fc7b26c8/avatica/site/_docs/index.md ---------------------------------------------------------------------- diff --git a/avatica/site/_docs/index.md b/avatica/site/_docs/index.md deleted file mode 100644 index 4b04e33..0000000 --- a/avatica/site/_docs/index.md +++ /dev/null @@ -1,176 +0,0 @@ ---- -layout: docs -title: Background -permalink: /docs/index.html ---- -<!-- -{% comment %} -Licensed to the Apache Software Foundation (ASF) under one or more -contributor license agreements. See the NOTICE file distributed with -this work for additional information regarding copyright ownership. -The ASF licenses this file to you under the Apache License, Version 2.0 -(the "License"); you may not use this file except in compliance with -the License. You may obtain a copy of the License at - -http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. -{% endcomment %} ---> - -Avatica is a framework for building JDBC and ODBC drivers for databases, -and an RPC wire protocol. - - - -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. - -Avatica's wire protocols are JSON or Protocol Buffers over HTTP. The -Java implementation of the JSON protocol uses -[Jackson](https://github.com/FasterXML/jackson) to convert -request/response command objects to/from JSON. - -Avatica-Server is a Java implementation of Avatica RPC. - -Core concepts: - -* [Meta]({{ site.apiRoot }}/org/apache/calcite/avatica/Meta.html) - is a local API sufficient to implement any Avatica provider -* [AvaticaFactory]({{ site.apiRoot }}/org/apache/calcite/avatica/AvaticaFactory.html) - creates implementations of the JDBC classes on top of a `Meta` -* [Service]({{ site.apiRoot }}/org/apache/calcite/avatica/remote/Service.html) - is an interface that implements the functions of `Meta` in terms - of request and response command objects - -## JDBC - -Avatica implements JDBC by means of -[AvaticaFactory]({{ site.apiRoot }}/org/apache/calcite/avatica/AvaticaFactory.html). -An implementation of `AvaticaFactory` creates implementations of the -JDBC classes ([Driver]({{ site.jdkApiRoot }}/java/sql/Driver.html), -[Connection]({{ site.jdkApiRoot }}/java/sql/Connection.html), -[Statement]({{ site.jdkApiRoot }}/java/sql/Statement.html), -[ResultSet]({{ site.jdkApiRoot }}/java/sql/ResultSet.html)) -on top of a `Meta`. - -## ODBC - -Work has not started on Avatica ODBC. - -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++. - -Since the Avatica protocol abstracts many of the differences between providers, -the same ODBC client could be used for different databases. - -Although the Avatica project does not include an ODBC driver, there -are ODBC drivers written on top of the Avatica protocol, for example -[an ODBC driver for Apache Phoenix](http://hortonworks.com/hadoop-tutorial/bi-apache-phoenix-odbc/). - -## HTTP Server - -Avatica-server embeds the Jetty HTTP server, providing a class -[HttpServer]({{ site.apiRoot }}/org/apache/calcite/avatica/server/HttpServer.html) -that implements the Avatica RPC protocol -and can be run as a standalone Java application. - -Connectors in HTTP server can be configured if needed by extending -`HttpServer` class and overriding its `configureConnector()` method. -For example, user can set `requestHeaderSize` to 64K bytes as follows: - -{% highlight java %} -HttpServer server = new HttpServer(handler) { - @Override - protected ServerConnector configureConnector( - ServerConnector connector, int port) { - HttpConnectionFactory factory = (HttpConnectionFactory) - connector.getDefaultConnectionFactory(); - factory.getHttpConfiguration().setRequestHeaderSize(64 << 10); - return super.configureConnector(connector, port); - } -}; -server.start(); -{% endhighlight %} - -## Project structure - -We know that it is important that client libraries have minimal dependencies. - -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. - -Packages: - -* [org.apache.calcite.avatica]({{ site.apiRoot }}/org/apache/calcite/avatica/package-summary.html) Core framework -* [org.apache.calcite.avatica.remote]({{ site.apiRoot }}/org/apache/calcite/avatica/remote/package-summary.html) JDBC driver that uses remote procedure calls -* [org.apache.calcite.avatica.server]({{ site.apiRoot }}/org/apache/calcite/avatica/server/package-summary.html) HTTP server -* [org.apache.calcite.avatica.util]({{ site.apiRoot }}/org/apache/calcite/avatica/util/package-summary.html) Utilities - -## Status - -### Implemented - -* Create connection, create statement, metadata, prepare, bind, execute, fetch -* RPC using JSON over HTTP -* Local implementation -* Implementation over an existing JDBC driver -* Composite RPCs (combining several requests into one round trip) - * Execute-Fetch - * Metadata-Fetch (metadata calls such as getTables return all rows) - -### Not implemented - -* ODBC -* RPCs - * CloseStatement - * CloseConnection -* Composite RPCs - * CreateStatement-Prepare - * CloseStatement-CloseConnection - * Prepare-Execute-Fetch (Statement.executeQuery should fetch first N rows) -* Remove statements from statement table -* DML (INSERT, UPDATE, DELETE) -* Statement.execute applied to SELECT statement - -## Clients - -The following is a list of available Avatica clients. Several describe -themselves as adapters for -[Apache Phoenix](http://phoenix.apache.org) but also work with other -Avatica back-ends. Contributions for clients in other languages are -highly welcomed! - -### Microsoft .NET driver for Apache Phoenix Query Server -* [Home page](https://github.com/Azure/hdinsight-phoenix-sharp) -* Language: C# -* *License*: [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) -* Avatica version 1.2.0 onwards -* *Maintainer*: Microsoft Azure - -### Boostport -* [Home page](https://github.com/Boostport/avatica) -* *Language*: Go -* *License*: [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) -* Avatica version 1.8.0 onwards -* *Maintainer*: Boostport - -### Avatica thin client -* [Home page](https://calcite.apache.org/avatica) -* *Language*: Java -* *License*: [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) -* Any Avatica version -* *Maintainer*: Apache Calcite community - -### Apache Phoenix database adapter for Python -* [Home page](https://bitbucket.org/lalinsky/python-phoenixdb) -* Language: Python -* *License*: [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) -* Avatica version 1.2.0 to 1.6.0 -* *Maintainer*: Lukáš Lalinský http://git-wip-us.apache.org/repos/asf/calcite-avatica/blob/fc7b26c8/avatica/site/_docs/json_reference.md ---------------------------------------------------------------------- diff --git a/avatica/site/_docs/json_reference.md b/avatica/site/_docs/json_reference.md deleted file mode 100644 index 6340c59..0000000 --- a/avatica/site/_docs/json_reference.md +++ /dev/null @@ -1,1191 +0,0 @@ ---- -layout: docs -title: JSON Reference -sidebar_title: JSON Reference -permalink: /docs/json_reference.html -requests: - - { name: "CatalogsRequest" } - - { name: "CloseConnectionRequest" } - - { name: "CloseStatementRequest" } - - { name: "ColumnsRequest" } - - { name: "CommitRequest" } - - { name: "ConnectionSyncRequest" } - - { name: "CreateStatementRequest" } - - { name: "DatabasePropertyRequest" } - - { name: "ExecuteRequest" } - - { name: "ExecuteBatchRequest" } - - { name: "FetchRequest" } - - { name: "OpenConnectionRequest" } - - { name: "PrepareAndExecuteBatchRequest" } - - { name: "PrepareAndExecuteRequest" } - - { name: "PrepareRequest" } - - { name: "RollbackRequest" } - - { name: "SchemasRequest" } - - { name: "SyncResultsRequest" } - - { name: "TableTypesRequest" } - - { name: "TablesRequest" } - - { name: "TypeInfoRequest" } -miscellaneous: - - { name: "AvaticaParameter" } - - { name: "AvaticaSeverity" } - - { name: "AvaticaType" } - - { name: "ColumnMetaData" } - - { name: "ConnectionProperties" } - - { name: "CursorFactory" } - - { name: "DatabaseProperty" } - - { name: "Frame" } - - { name: "QueryState" } - - { name: "Rep" } - - { name: "RpcMetadata" } - - { name: "Signature" } - - { name: "StateType" } - - { name: "StatementHandle" } - - { name: "StatementType" } - - { name: "Style" } - - { name: "TypedValue" } -responses: - - { name: "CloseConnectionResponse" } - - { name: "CloseStatementResponse" } - - { name: "CommitResponse" } - - { name: "ConnectionSyncResponse" } - - { name: "CreateStatementResponse" } - - { name: "DatabasePropertyResponse" } - - { name: "ErrorResponse" } - - { name: "ExecuteBatchResponse" } - - { name: "ExecuteResponse" } - - { name: "FetchResponse" } - - { name: "OpenConnectionResponse" } - - { name: "PrepareResponse" } - - { name: "ResultSetResponse" } - - { name: "RollbackResponse" } - - { name: "SyncResultsResponse" } ---- - -<!-- -{% comment %} -Licensed to the Apache Software Foundation (ASF) under one or more -contributor license agreements. See the NOTICE file distributed with -this work for additional information regarding copyright ownership. -The ASF licenses this file to you under the Apache License, Version 2.0 -(the "License"); you may not use this file except in compliance with -the License. You may obtain a copy of the License at - -http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. -{% endcomment %} ---> - -As Avatica uses JSON to serialize messages sent over an HTTP transport, -the RPC layer is agnostic of the language used by a client. While the Avatica -server is written in Java, this enables clients to interact with the server -using any language instead of being limited to Java. - -A specification of the JSON request and response objects are documented -below. Programmatic bindings for these JSON objects are only available -in Java. For support outside of Java, see the Protocol Buffer -[bindings]({{ site.baseurl }}/docs/avatica_protobuf_reference.html) - -## Index - -### Requests -<ul> - {% for item in page.requests %}<li><a href="#{{ item.name | downcase }}">{{ item.name }}</a></li>{% endfor %} -</ul> - -### Responses -<ul> - {% for item in page.responses %}<li><a href="#{{ item.name | downcase }}">{{ item.name }}</a></li>{% endfor %} -</ul> - -### Miscellaneous -<ul> - {% for item in page.miscellaneous %}<li><a href="#{{ item.name | downcase }}">{{ item.name }}</a></li>{% endfor %} -</ul> - - -## Requests - -The collection of all JSON objects accepted as requests to Avatica. All Requests include a `request` attribute -which uniquely identifies the concrete Request from all other Requests. - -### CatalogsRequest - -This request is used to fetch the available catalog names in the database. - -{% highlight json %} -{ - "request": "getCatalogs", - "connectionId": "000000-0000-0000-00000000" -} -{% endhighlight %} - -`connectionId` (required string) The identifier of the connection to use. - -### CloseConnectionRequest - -This request is used to close the Connection object in the Avatica server identified by the given IDs. - -{% highlight json %} -{ - "request": "closeConnection", - "connectionId": "000000-0000-0000-00000000" -} -{% endhighlight %} - -`connectionId` (required string) The identifier of the connection to close. - -### CloseStatementRequest - -This request is used to close the Statement object in the Avatica server identified by the given IDs. - -{% highlight json %} -{ - "request": "closeStatement", - "connectionId": "000000-0000-0000-00000000", - "statementId": 12345 -} -{% endhighlight %} - -`connectionId` (required string) The identifier of the connection to which the statement belongs. - -`statementId` (required integer) The identifier of the statement to close. - -### ColumnsRequest - -This request is used to fetch columns in the database given some optional filtering criteria. - -{% highlight json %} -{ - "request": "getColumns", - "connectionId": "000000-0000-0000-00000000", - "catalog": "catalog", - "schemaPattern": "schema_pattern.*", - "tableNamePattern": "table_pattern.*", - "columnNamePattern": "column_pattern.*" -} -{% endhighlight %} - -`connectionId` (required string) The identifier of the connection on which to fetch the columns. - -`catalog` (optional string) The name of a catalog to limit returned columns. - -`schemaPattern` (optional string) A Java Pattern against schemas to limit returned columns. - -`tableNamePattern` (optional string) A Java Pattern against table names to limit returned columns. - -`columnNamePattern` (optional string) A Java Pattern against column names to limit returned columns. - -### CommitRequest - -This request is used to issue a `commit` on the Connection in the Avatica server identified by the given ID. - -{% highlight json %} -{ - "request": "commit", - "connectionId": "000000-0000-0000-00000000" -} -{% endhighlight %} - -`connectionId` (required string) The identifier of the connection on which to invoke commit. - -### ConnectionSyncRequest - -This request is used to ensure that the client and server have a consistent view of the database properties. - -{% highlight json %} -{ - "request": "connectionSync", - "connectionId": "000000-0000-0000-00000000", - "connProps": ConnectionProperties -} -{% endhighlight %} - -`connectionId` (required string) The identifier of the connection to synchronize. - -`connProps` (optional nested object) A <a href="#connectionproperties">ConnectionProperties</a> object to synchronize between the client and server. - -### CreateStatementRequest - -This request is used to create a new Statement in the Avatica server. - -{% highlight json %} -{ - "request": "createStatement", - "connectionId": "000000-0000-0000-00000000" -} -{% endhighlight %} - -`connectionId` (required string) The identifier of the connection to use in creating a statement. - -### DatabasePropertyRequest - -This request is used to fetch all <a href="#databaseproperty">database properties</a>. - -{% highlight json %} -{ - "request": "databaseProperties", -} -{% endhighlight %} - -`connectionId` (required string) The identifier of the connection to use when fetching the database properties. - -### ExecuteBatchRequest - -This request is used to execute a batch of updates on a PreparedStatement. - -{% highlight json %} -{ - "request": "executeBatch", - "connectionId": "000000-0000-0000-00000000", - "statementId": 12345, - "parameterValues": [ [ TypedValue, TypedValue, ... ], [ TypedValue, TypedValue, ...], ... ] -} -{% endhighlight %} - -`connectionId` (required string) The identifier of the connection to use when fetching the database properties. - -`statementId` (required integer) The identifier of the statement created using the above connection. - -`parameterValues` (required array of array) An array of arrays of <a href="#typedvalue">TypedValue</a>'s. Each element - in the array is an update to a row, while the outer array represents the entire "batch" of updates. - -### ExecuteRequest - -This request is used to execute a PreparedStatement, optionally with values to bind to the parameters in the Statement. - -{% highlight json %} -{ - "request": "execute", - "statementHandle": StatementHandle, - "parameterValues": [TypedValue, TypedValue, ... ], - "maxRowCount": 100 -} -{% endhighlight %} - -`statementHandle` (required object) A <a href="#statementhandle">StatementHandle</a> object. - -`parameterValues` (optional array of nested objects) The <a href="#typedvalue">TypedValue</a> for each parameter on the prepared statement. - -`maxRowCount` (required long) The maximum number of rows returned in the response. - -### FetchRequest - -This request is used to fetch a batch of rows from a Statement previously created. - -{% highlight json %} -{ - "request": "fetch", - "connectionId": "000000-0000-0000-00000000", - "statementId": 12345, - "offset": 0, - "fetchMaxRowCount": 100 -} -{% endhighlight %} - -`connectionId` (required string) The identifier of the connection to use. - -`statementId` (required integer) The identifier of the statement created using the above connection. - -`offset` (required integer) The positional offset into a result set to fetch. - -`fetchMatchRowCount` (required integer) The maximum number of rows to return in the response to this request. - -### OpenConnectionRequest - -This request is used to open a new Connection in the Avatica server. - -{% highlight json %} -{ - "request": "openConnection", - "connectionId": "000000-0000-0000-00000000", - "info": {"key":"value", ...} -} -{% endhighlight %} - -`connectionId` (required string) The identifier of the connection to open in the server. - -`info` (optional string-to-string map) A Map containing properties to include when creating the Connection. - -### PrepareAndExecuteBatchRequest - -This request is used as short-hand to create a Statement and execute an batch of SQL commands in that Statement. - -{% highlight json %} -{ - "request": "prepareAndExecuteBatch", - "connectionId": "000000-0000-0000-00000000", - "statementId": 12345, - "sqlCommands": [ "SQL Command", "SQL Command", ... ] -} -{% endhighlight %} - -`connectionId` (required string) The identifier for the connection to use. - -`statementId` (required integer) The identifier for the statement created by the above connection to use. - -`sqlCommands` (required array of strings) An array of SQL commands - -### PrepareAndExecuteRequest - -This request is used as a short-hand for create a Statement and fetching the first batch of results in a single call without any parameter substitution. - -{% highlight json %} -{ - "request": "prepareAndExecute", - "connectionId": "000000-0000-0000-00000000", - "statementId": 12345, - "sql": "SELECT * FROM table", - "maxRowCount": 100, -} -{% endhighlight %} - -`connectionId` (required string) The identifier for the connection to use. - -`statementId` (required integer) The identifier for the statement created by the above connection to use. - -`sql` (required string) A SQL statement - -`maxRowCount` (required long) The maximum number of rows returned in the response. - -### PrepareRequest - -This request is used to create create a new Statement with the given query in the Avatica server. - -{% highlight json %} -{ - "request": "prepare", - "connectionId": "000000-0000-0000-00000000", - "sql": "SELECT * FROM table", - "maxRowCount": 100, -} -{% endhighlight %} - -`connectionId` (required string) The identifier for the connection to use. - -`sql` (required string) A SQL statement - -`maxRowCount` (required long) The maximum number of rows returned in the response. - -### SyncResultsRequest - -This request is used to reset a ResultSet's iterator to a specific offset in the Avatica server. - -{% highlight json %} -{ - "request": "syncResults", - "connectionId": "000000-0000-0000-00000000", - "statementId": 12345, - "state": QueryState, - "offset": 200 -} -{% endhighlight %} - -`connectionId` (required string) The identifier for the connection to use. - -`statementId` (required integer) The identifier for the statement to use. - -`state` (required object) The <a href="#querystate">QueryState</a> object. - -`offset` (required long) The offset into the ResultSet to seek to. - -### RollbackRequest - -This request is used to issue a `rollback` on the Connection in the Avatica server identified by the given ID. - -{% highlight json %} -{ - "request": "rollback", - "connectionId": "000000-0000-0000-00000000" -} -{% endhighlight %} - -`connectionId` (required string) The identifier for the connection on which to invoke rollback. - -### SchemasRequest - -This request is used to fetch the schemas matching the provided criteria in the database. - -{% highlight json %} -{ - "request": "getSchemas", - "connectionId": "000000-0000-0000-00000000", - "catalog": "name", - "schemaPattern": "pattern.*" -} -{% endhighlight %} - -`connection_id` The identifier for the connection to fetch schemas from. - -`catalog` (required string) The name of the catalog to fetch the schema from. - -`schemaPattern` (required string) A Java pattern of schemas to fetch. - -### TableTypesRequest - -This request is used to fetch the table types available in this database. - -{% highlight json %} -{ - "request": "getTableTypes", - "connectionId": "000000-0000-0000-00000000" -} -{% endhighlight %} - -`connectionId` The identifier of the connection to fetch the table types from. - -### TablesRequest - -This request is used to fetch the tables available in this database filtered by the provided criteria. - -{% highlight json %} -{ - "request": "getTables", - "connectionId": "000000-0000-0000-00000000", - "catalog": "catalog_name", - "schemaPattern": "schema_pattern.*", - "tableNamePattern": "table_name_pattern.*", - "typeList": [ "TABLE", "VIEW", ... ] -} -{% endhighlight %} - -`catalog` (optional string) The name of a catalog to restrict fetched tables. - -`connectionId` The identifier of the connection to fetch the tables from. - -`schemaPattern` (optional string) A Java Pattern representing schemas to include in fetched tables. - -`tableNamePattern` (optional string) A Java Pattern representing table names to include in fetched tables. - -`typeList` (optional array of string) A list of table types used to restrict fetched tables. - -### TypeInfoRequest - -This request is used to fetch the types available in this database. - -{% highlight json %} -{ - "request": "getTypeInfo", - "connectionId": "000000-0000-0000-00000000" -} -{% endhighlight %} - -`connectionId` The identifier of the connection to fetch the types from. - -## Responses - -The collection of all JSON objects returned as responses from Avatica. All Responses include a `response` attribute -which uniquely identifies the concrete Response from all other Responses. - -### CloseConnectionResponse - -A response to the <a href="#closeconnectionrequest">CloseConnectionRequest</a>. - -{% highlight json %} -{ - "response": "closeConnection", - "rpcMetadata": RpcMetadata -} -{% endhighlight %} - -`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. - -### CloseStatementResponse - -A response to the <a href="#closestatementrequest">CloseStatementRequest</a>. - -{% highlight json %} -{ - "response": "closeStatement", - "rpcMetadata": RpcMetadata -} -{% endhighlight %} - -`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. - -### CommitResponse - -A response to the <a href="#commitrequest">CommitRequest</a>. - -{% highlight json %} -{ - "response": "commit" -} -{% endhighlight %} - -There are no extra attributes on this Response. - -### ConnectionSyncResponse - -A response to the <a href="#connectionsyncrequest">ConnectionSyncRequest</a>. Properties included in the -response are those of the Connection in the Avatica server. - -{% highlight json %} -{ - "response": "connectionSync", - "connProps": ConnectionProperties, - "rpcMetadata": RpcMetadata -} -{% endhighlight %} - -`connProps` The <a href="#connectionproperties">ConnectionProperties</a> that were synchronized. - -`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. - -### CreateStatementResponse - -A response to the <a href="#createstatementrequest">CreateStatementRequest</a>. The ID of the statement -that was created is included in the response. Clients will use this `statementId` in subsequent calls. - -{% highlight json %} -{ - "response": "createStatement", - "connectionId": "000000-0000-0000-00000000", - "statementId": 12345, - "rpcMetadata": RpcMetadata -} -{% endhighlight %} - -`connectionId` The identifier for the connection used to create the statement. - -`statementId` The identifier for the created statement. - -`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. - -### DatabasePropertyResponse - -A response to the <a href="#databasepropertyrequest">DatabasePropertyRequest</a>. See <a hred="#databaseproperty">DatabaseProperty</a> -for information on the available property keys. - -{% highlight json %} -{ - "response": "databaseProperties", - "map": { DatabaseProperty: Object, DatabaseProperty: Object, ... }, - "rpcMetadata": RpcMetadata -} -{% endhighlight %} - -`map` A map of <a href="#databaseproperty">DatabaseProperty</a> to value of that property. The value may be some -primitive type or an array of primitive types. - -`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. - -### ErrorResponse - -A response when an error was caught executing a request. Any request may return this response. - -{% highlight json %} -{ - "response": "error", - "exceptions": [ "stacktrace", "stacktrace", ... ], - "errorMessage": "The error message", - "errorCode": 42, - "sqlState": "ABC12", - "severity": AvaticaSeverity, - "rpcMetadata": RpcMetadata -} -{% endhighlight %} - -`exceptions` A list of stringified Java StackTraces. - -`errorMessage` A human-readable error message. - -`errorCode` A numeric code for this error. - -`sqlState` A five character alphanumeric code for this error. - -`severity` An <a href="#avaticaseverity">AvaticaSeverity</a> object which denotes how critical the error is. - -`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. - -### ExecuteBatchResponse - -A response to <a href="#executebatchrequest">ExecuteBatchRequest</a> and <a href="#prepareandexecutebatchrequest">PrepareAndExecuteRequest</a> -which encapsulates the update counts for a batch of updates. - -{% highlight json %} -{ - "response": "executeBatch", - "connectionId": "000000-0000-0000-00000000", - "statementId": 12345, - "updateCounts": [ 1, 1, 0, 1, ... ], - "missingStatement": false, - "rpcMetadata": RpcMetadata -} -{% endhighlight %} - -`connectionId` The identifier for the connection used to create the statement. - -`statementId` The identifier for the created statement. - -`updateCounts` An array of integers corresponding to each update contained in the batch that was executed. - -`missingStatement` True if the operation failed because the Statement is not cached in the server, false otherwise. - -`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. - - -### ExecuteResponse - -A response to the <a href="#executerequest">ExecuteRequest</a> which contains the results for a metadata query. - -{% highlight json %} -{ - "response": "executeResults", - "resultSets": [ ResultSetResponse, ResultSetResponse, ... ], - "missingStatement": false, - "rpcMetadata": RpcMetadata -} -{% endhighlight %} - -`resultSets` An array of <a href="#resultsetresponse">ResultSetResponse</a>s. - -`missingStatement` A boolean which denotes if the request failed due to a missing Statement. - -`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. - -### FetchResponse - -A response to the <a href="#fetchrequest">FetchRequest</a> which contains the request for the query. - -{% highlight json %} -{ - "response": "fetch", - "frame": Frame, - "missingStatement": false, - "missingResults": false, - "rpcMetadata": RpcMetadata -} -{% endhighlight %} - -`frame` A <a href="#frame">Frame</a> containing the results of the fetch. - -`missingStatement` A boolean which denotes if the request failed due to a missing Statement. - -`missingResults` A boolean which denotes if the request failed due to a missing ResultSet. - -`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. - -### OpenConnectionResponse - -A response to the <a href="#openconnectionrequest">OpenConnectionRequest</a>. The ID for the connection that -the client should use in subsequent calls was provided by the client in the request. - -{% highlight json %} -{ - "response": "openConnection", - "rpcMetadata": RpcMetadata -} -{% endhighlight %} - -`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. - -### PrepareResponse - -A response to the <a href="#preparerequest">PrepareRequest</a>. This response includes a <a href="#statementhandle">StatementHandle</a> -which clients must use to fetch the results from the Statement. - -{% highlight json %} -{ - "response": "prepare", - "statement": StatementHandle, - "rpcMetadata": RpcMetadata -} -{% endhighlight %} - -`statement` A <a href="#statementhandle">StatementHandle</a> object. - -`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. - -### ResultSetResponse - -A response which contains the results and type details from a query. - -{% highlight json %} -{ - "response": "resultSet", - "connectionId": "000000-0000-0000-00000000", - "statementId": 12345, - "ownStatement": true, - "signature": Signature, - "firstFrame": Frame, - "updateCount": 10, - "rpcMetadata": RpcMetadata -} -{% endhighlight %} - -`connectionId` The identifier for the connection used to generate this response. - -`statementId` The identifier for the statement used to generate this response. - -`ownStatement` Whether the result set has its own dedicated statement. If true, the server must automatically close the -statement when the result set is closed. This is used for JDBC metadata result sets, for instance. - -`signature` A non-optional nested object <a href="#signature">Signature</a> - -`firstFrame` A optional nested object <a href="#frame">Frame</a> - -`updateCount` A number which is always `-1` for normal result sets. Any other value denotes a "dummy" result set -that only contains this count and no additional data. - -`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. - -### RollbackResponse - -A response to the <a href="#rollbackrequest">RollBackRequest</a>. - -{% highlight json %} -{ - "response": "rollback" -} -{% endhighlight %} - -There are no extra attributes on this Response. - -### SyncResultsResponse - -A response to the <a href="#syncresultsrequest">SyncResultsRequest</a>. When `moreResults` is true, a <a href="#fetchrequest">FetchRequest</a> -should be issued to get the next batch of records. When `missingStatement` is true, the statement must be re-created using <a href="#preparerequest">PrepareRequest</a> -or the appropriate Request for a DDL request (e.g. <a href="#catalogsrequest">CatalogsRequest</a> or <a href="#schemasrequest">SchemasRequest</a>). - -{% highlight json %} -{ - "response": "syncResults", - "moreResults": true, - "missingStatement": false, - "rpcMetadata": RpcMetadata -} -{% endhighlight %} - -`moreResults` A boolean which denotes if results exist for the ResultSet being "synced" per the request. - -`missingStatement` A boolean which denotes if the statement for the ResultSet still exists. - -`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. - -## Miscellaneous - -### AvaticaParameter - -This object describes the "simple", or scalar, JDBC type representation of a column in a result. This does not include -complex types such as arrays. - -{% highlight json %} -{ - "signed": true, - "precision": 10, - "scale": 2, - "parameterType": 8, - "typeName": "integer", - "className": "java.lang.Integer", - "name": "number" -} -{% endhighlight %} - -`signed` A boolean denoting whether the column is a signed numeric. - -`precision` The maximum numeric precision supported by this column. - -`scale` The maximum numeric scale supported by this column. - -`parameterType` An integer corresponding to the JDBC Types class denoting the column's type. - -`typeName` The JDBC type name for this column. - -`className` The Java class backing the JDBC type for this column. - -`name` The name of the column. - -### AvaticaSeverity - -This enumeration describes the various levels of concern for an error in the Avatica server. - -One of: - -* `UNKNOWN` -* `FATAL` -* `ERROR` -* `WARNING` - -### AvaticaType - -This object describes a simple or complex type for a column. Complex types will contain -additional information in the `component` or `columns` attribute which describe the nested -types of the complex parent type. - -{% highlight json %} -{ - "type": "scalar", - "id": "identifier", - "name": "column", - "rep": Rep, - "columns": [ ColumnMetaData, ColumnMetaData, ... ], - "component": AvaticaType -} -{% endhighlight %} - -`type` One of: `scalar`, `array`, `struct`. - -`id` A numeric value corresponding to the type of the object per the JDBC Types class. - -`name` The readable name of the JDBC type. - -`rep` A nested <a href="#rep">Rep</a> object used by Avatica to hold additional type information. - -`columns` For `STRUCT` types, a list of the columns contained in that `STRUCT`. - -`component` For `ARRAY` types, the type of the elements contained in that `ARRAY`. - -### ColumnMetaData - -This object represents the JDBC ResultSetMetaData for a column. - -{% highlight json %} -{ - "ordinal": 0, - "autoIncrement": true, - "caseSensitive": true, - "searchable": false, - "currency": false, - "nullable": 0, - "signed": true, - "displaySize": 20, - "label": "Description", - "columnName": "col1", - "schemaName": "schema", - "precision": 10, - "scale": 2, - "tableName": "table", - "catalogName": "catalog", - "type": AvaticaType, - "readOnly": false, - "writable": true, - "definitelyWritable": true, - "columnClassName": "java.lang.String" -} -{% endhighlight %} - -`ordinal` A positional offset number. - -`autoIncrement` A boolean denoting whether the column is automatically incremented. - -`caseSensitive` A boolean denoting whether the column is case sensitive. - -`searchable` A boolean denoting whether this column supports all WHERE search clauses. - -`currency` A boolean denoting whether this column represents currency. - -`nullable` A number denoting whether this column supports null values. - -* 0 = No null values are allowed -* 1 = Null values are allowed -* 2 = It is unknown if null values are allowed - -`signed` A boolean denoting whether the column is a signed numeric. - -`displaySize` The character width of the column. - -`label` A description for this column. - -`columnName` The name of the column. - -`schemaName` The schema to which this column belongs. - -`precision` The maximum numeric precision supported by this column. - -`scale` The maximum numeric scale supported by this column. - -`tableName` The name of the table to which this column belongs. - -`catalogName` The name of the catalog to which this column belongs. - -`type` A nested <a href="#avaticatype">AvaticaType</a> representing the type of the column. - -`readOnly` A boolean denoting whether the column is read-only. - -`writable` A boolean denoting whether the column is possible to be updated. - -`definitelyWritable` A boolean denoting whether the column definitely can be updated. - -`columnClassName` The name of the Java class backing the column's type. - -### ConnectionProperties - -This object represents the properties for a given JDBC Connection. - -{% highlight json %} -{ - "connProps": "connPropsImpl", - "autoCommit": true, - "readOnly": true, - "transactionIsolation": 0, - "catalog": "catalog", - "schema": "schema" -} -{% endhighlight %} - -`autoCommit` (optional boolean) A boolean denoting if autoCommit is enabled for transactions. - -`readOnly` (optional boolean) A boolean denoting if a JDBC connection is read-only. - -`transactionIsolation` (optional integer) An integer which denotes the level of transactions isolation per the JDBC -specification. This value is analogous to the values defined in `java.sql.Connection`. - -* 0 = Transactions are not supported -* 1 = Dirty reads, non-repeatable reads and phantom reads may occur. -* 2 = Dirty reads are prevented, but non-repeatable reads and phantom reads may occur. -* 4 = Dirty reads and non-repeatable reads are prevented, but phantom reads may occur. -* 8 = Dirty reads, non-repeatable reads, and phantom reads are all prevented. - -`catalog` (optional string) The name of the catalog to include when fetching connection properties. - -`schema` (optional string) The name of the schema to include when fetching connection properties. - -### CursorFactory - -This object represents the information required to cast untyped objects into the necessary type for some results. - -{% highlight json %} -{ - "style": Style, - "clazz": "java.lang.String", - "fieldNames": [ "column1", "column2", ... ] -} -{% endhighlight %} - -`style` A string denoting the <a href="#style">Style</a> of the contained objects. - -### DatabaseProperty - -This object represents the exposed database properties for a Connection through the Avatica server. - -One of: - -* `GET_STRING_FUNCTIONS` -* `GET_NUMERIC_FUNCTIONS` -* `GET_SYSTEM_FUNCTIONS` -* `GET_TIME_DATE_FUNCTIONS` -* `GET_S_Q_L_KEYWORDS` -* `GET_DEFAULT_TRANSACTION_ISOLATION` - -### Frame - -This object represents a batch of results, tracking the offset into the results and whether more results still exist -to be fetched in the Avatica server. - -{% highlight json %} -{ - "offset": 100, - "done": true, - "rows": [ [ val1, val2, ... ], ... ] -} -{% endhighlight %} - -`offset` The starting position of these `rows` in the encompassing result set. - -`done` A boolean denoting whether more results exist for this result set. - -`rows` An array of arrays corresponding to the rows and columns for the result set. - -### QueryState - -This object represents the way a ResultSet was created in the Avatica server. A ResultSet could be created by a user-provided -SQL or by a DatabaseMetaData operation with arguments on that operation. - -{% highlight json %} -{ - "type": StateType, - "sql": "SELECT * FROM table", - "metaDataOperation": MetaDataOperation, - "operationArgs": ["arg0", "arg1", ... ] -} -{% endhighlight %} - -`type` A <a href="#statetype">StateType</a> object denoting what type of operation backs the ResultSet for this query. - -`sql` The SQL statement which created the ResultSet for this query. Required if the `type` is `SQL`. - -`metaDataOperation` The DML operation which created the ResultSet for this query. Required if the `type` is `METADATA`. - -`operationArgs` The arguments to the invoked DML operation. Required if the `type` is `METADATA`. - -### Rep - -This enumeration represents the concrete Java type for some value. - -One of: - -* `PRIMITIVE_BOOLEAN` -* `PRIMITIVE_BYTE` -* `PRIMITIVE_CHAR` -* `PRIMITIVE_SHORT` -* `PRIMITIVE_INT` -* `PRIMITIVE_LONG` -* `PRIMITIVE_FLOAT` -* `PRIMITIVE_DOUBLE` -* `BOOLEAN` -* `BYTE` -* `CHARACTER` -* `SHORT` -* `INTEGER` -* `LONG` -* `FLOAT` -* `DOUBLE` -* `JAVA_SQL_TIME` -* `JAVA_SQL_TIMESTAMP` -* `JAVA_SQL_DATE` -* `JAVA_UTIL_DATE` -* `BYTE_STRING` -* `STRING` -* `NUMBER` -* `OBJECT` - -### RpcMetadata - -This object contains assorted per-call/contextual metadata returned by the Avatica server. - -{% highlight json %} -{ - "serverAddress": "localhost:8765" -} -{% endhighlight %} - -`serverAddress` The `host:port` of the server which created this object. - -### Signature - -This object represents the result of preparing a Statement in the Avatica server. - -{% highlight json %} -{ - "columns": [ ColumnMetaData, ColumnMetaData, ... ], - "sql": "SELECT * FROM table", - "parameters": [ AvaticaParameter, AvaticaParameter, ... ], - "cursorFactory": CursorFactory, - "statementType": StatementType -} -{% endhighlight %} - -`columns` An array of <a href="#columnmetadata">ColumnMetaData</a> objects denoting the schema of the result set. - -`sql` The SQL executed. - -`parameters` An array of <a href="#avaticaparameter">AvaticaParameter</a> objects denoting type-specific details. - -`cursorFactory` An <a href="#cursorfactory">CursorFactory</a> object representing the Java representation of the frame. - -`statementType` An <a href="#statementtype">StatementType</a> object representing the type of Statement. - -### StateType - -This enumeration denotes whether user-provided SQL or a DatabaseMetaData operation was used to create some ResultSet. - -One of: - -* `SQL` -* `METADATA` - -### StatementHandle - -This object encapsulates all of the information of a Statement created in the Avatica server. - -{% highlight json %} -{ - "connectionId": "000000-0000-0000-00000000", - "id": 12345, - "signature": Signature -} -{% endhighlight %} - -`connectionId` The identifier of the connection to which this statement belongs. - -`id` The identifier of the statement. - -`signature` A <a href="#signature">Signature</a> object for the statement. - -### StatementType - -This enumeration represents what kind the Statement is. - -One of: - -* `SELECT` -* `INSERT` -* `UPDATE` -* `DELETE` -* `UPSERT` -* `MERGE` -* `OTHER_DML` -* `CREATE` -* `DROP` -* `ALTER` -* `OTHER_DDL` -* `CALL` - -### Style - -This enumeration represents the generic "class" of type for a value. - -One of: - -* `OBJECT` -* `RECORD` -* `RECORD_PROJECTION` -* `ARRAY` -* `LIST` -* `MAP` - -### TypedValue - -This object encapsulates the type and value for a column in a row. - -{% highlight json %} -{ - "type": "type_name", - "value": object -} -{% endhighlight %} - -`type` A name referring to the type of the object stored in `value`. - -`value` A JSON representation of a JDBC type. - -The following chart documents how each <a href="#rep">Rep</a> value is serialized -into a JSON value. Consult the [JSON documentation](http://json-spec.readthedocs.org/en/latest/reference.html) -for more information on valid attributes in JSON. - -| <a href="#rep">Rep</a> Value | Serialized | Description | -| PRIMITIVE_BOOLEAN | boolean || -| BOOLEAN | boolean || -| PRIMITIVE_BYTE | number | The numeric value of the `byte`. | -| BYTE | number || -| PRIMITIVE_CHAR | string || -| CHARACTER | string || -| PRIMITIVE_SHORT | number || -| SHORT | number || -| PRIMITIVE_INT | number || -| INTEGER | number || -| PRIMITIVE_LONG | number || -| LONG | number || -| PRIMITIVE_FLOAT | number || -| FLOAT | number || -| PRIMITIVE_DOUBLE | number || -| DOUBLE | number || -| BIG_INTEGER | number | Implicitly handled by Jackson. | -| BIG_DECIMAL | number | Implicitly handled by Jackson. | -| JAVA_SQL_TIME | number | As an integer, milliseconds since midnight. | -| JAVA_SQL_DATE | number | As an integer, the number of days since the epoch. | -| JAVA_SQL_TIMESTAMP | number | As a long, milliseconds since the epoch. | -| JAVA_UTIL_DATE | number | As a long, milliseconds since the epoch. | -| BYTE_STRING | string | A Base64-encoded string. | -| STRING | string | | -| NUMBER | number | A general number, unknown what concrete type. | -| OBJECT | null | Implicitly converted by Jackson. | -| NULL | null | Implicitly converted by Jackson. | -| ARRAY | N/A | Implicitly handled by Jackson. | -| STRUCT | N/A | Implicitly handled by Jackson. | -| MULTISET | N/A | Implicitly handled by Jackson. |
