This is an automated email from the ASF dual-hosted git repository.
lidavidm pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow-adbc.git
The following commit(s) were added to refs/heads/main by this push:
new bbad6830 docs(java): First step into adding Java docs (quickstart,
driver manager summary, etc.) (#1191)
bbad6830 is described below
commit bbad68306277b067aa76aeb1b058c5d5d1c4edb4
Author: Solomon Choe <[email protected]>
AuthorDate: Wed Oct 11 12:00:58 2023 -0700
docs(java): First step into adding Java docs (quickstart, driver manager
summary, etc.) (#1191)
Cleaned up branch of https://github.com/apache/arrow-adbc/pull/1188
---
docs/source/java/api/adbc_driver_manager.rst | 79 +++++++++++++++++++++
docs/source/java/{ => api}/index.rst | 10 +--
docs/source/java/{index.rst => driver_manager.rst} | 25 +++++--
docs/source/java/index.rst | 4 +-
docs/source/java/quickstart.rst | 82 ++++++++++++++++++++++
5 files changed, 188 insertions(+), 12 deletions(-)
diff --git a/docs/source/java/api/adbc_driver_manager.rst
b/docs/source/java/api/adbc_driver_manager.rst
new file mode 100644
index 00000000..6c4ec2d1
--- /dev/null
+++ b/docs/source/java/api/adbc_driver_manager.rst
@@ -0,0 +1,79 @@
+.. 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.
+
+============================
+``Java ADBC Driver Manager``
+============================
+
+Java ADBC Wrapper for JDBC
+==========================
+
+The Java ADBC Driver Manager provides a means to manage ADBC drivers and
facilitate connections to databases using the ADBC API. This particular
implementation wraps around the JDBC API.
+
+Constants
+---------
+
+.. data:: org.apache.arrow.adbc.driver.jdbc.JdbcDriver.PARAM_DATASOURCE
+
+ A parameter for creating an ``AdbcDatabase`` from a ``DataSource``.
+
+.. data:: org.apache.arrow.adbc.driver.jdbc.JdbcDriver.PARAM_JDBC_QUIRKS
+
+ A parameter for specifying backend-specific configuration.
+
+.. data:: org.apache.arrow.adbc.driver.jdbc.JdbcDriver.PARAM_URI
+
+ A parameter for specifying a URI to connect to, aligning with the C/Go
implementations.
+
+Classes
+-------
+
+.. class:: org.apache.arrow.adbc.driver.jdbc.JdbcDriver
+
+ An ADBC driver implementation that wraps around the JDBC API.
+
+ .. method:: open(Map<String, Object> parameters)
+
+ Opens a new database connection using the specified parameters.
+
+.. class:: org.apache.arrow.adbc.driver.jdbc.JdbcDataSourceDatabase
+
+ Represents an ADBC database backed by a JDBC ``DataSource``.
+
+Utilities
+---------
+
+The ``JdbcDriver`` class provides utility methods to fetch and validate
parameters from the provided options map.
+
+.. method:: org.apache.arrow.adbc.driver.jdbc.JdbcDriver.getParam(Class<T>
klass, Map<String, Object> parameters, String... choices)
+
+ Retrieves a parameter from the provided map, validating its type and
ensuring no duplicates.
+
+Usage
+=====
+
+The ``JdbcDriver`` class is registered with the ``AdbcDriverManager`` upon
class loading. To utilize this driver:
+
+1. Ensure the necessary dependencies are in place.
+2. Create a ``Map<String, Object>`` containing the connection parameters.
+3. Use the ``AdbcDriverManager`` to obtain an instance of the ``JdbcDriver``.
+4. Open a new database connection using the driver's ``open`` method.
+
+Exceptions
+==========
+
+Any errors during the driver operations throw the ``AdbcException``. This
exception provides detailed messages indicating the nature of the problem.
diff --git a/docs/source/java/index.rst b/docs/source/java/api/index.rst
similarity index 89%
copy from docs/source/java/index.rst
copy to docs/source/java/api/index.rst
index ccfe071d..e93406f3 100644
--- a/docs/source/java/index.rst
+++ b/docs/source/java/api/index.rst
@@ -15,11 +15,11 @@
.. specific language governing permissions and limitations
.. under the License.
-====
-Java
-====
+====================
+Java API Reference
+====================
.. toctree::
- :maxdepth: 2
+ :maxdepth: 1
-.. note:: Under construction
+ adbc_driver_manager
diff --git a/docs/source/java/index.rst b/docs/source/java/driver_manager.rst
similarity index 64%
copy from docs/source/java/index.rst
copy to docs/source/java/driver_manager.rst
index ccfe071d..78215a0e 100644
--- a/docs/source/java/index.rst
+++ b/docs/source/java/driver_manager.rst
@@ -15,11 +15,24 @@
.. specific language governing permissions and limitations
.. under the License.
-====
-Java
-====
+==============
+Driver Manager
+==============
-.. toctree::
- :maxdepth: 2
+Installation
+============
-.. note:: Under construction
+To include the ADBC Driver Manager in your Maven project, add the following
dependency:
+
+.. code-block:: xml
+
+ <dependency>
+ <groupId>org.apache.arrow.adbc</groupId>
+ <artifactId>adbc-driver-manager</artifactId>
+ <version>${adbc.version}</version>
+ </dependency>
+
+API Reference
+=============
+
+See the API reference: :doc:`./api/adbc_driver_manager`.
diff --git a/docs/source/java/index.rst b/docs/source/java/index.rst
index ccfe071d..c9699417 100644
--- a/docs/source/java/index.rst
+++ b/docs/source/java/index.rst
@@ -22,4 +22,6 @@ Java
.. toctree::
:maxdepth: 2
-.. note:: Under construction
+ quickstart
+ driver_manager
+ api/index
diff --git a/docs/source/java/quickstart.rst b/docs/source/java/quickstart.rst
new file mode 100644
index 00000000..c6255c3a
--- /dev/null
+++ b/docs/source/java/quickstart.rst
@@ -0,0 +1,82 @@
+.. 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.
+
+==========
+Quickstart
+==========
+
+Here we'll briefly tour basic features of ADBC with the PostgreSQL driver for
Java.
+
+Installation
+============
+
+To include ADBC in your Maven project, add the following dependency:
+
+.. code-block:: xml
+
+ <dependency>
+ <groupId>org.apache.arrow.adbc</groupId>
+ <artifactId>adbc-driver-jdbc</artifactId>
+ <version>${adbc.version}</version>
+ </dependency>
+
+For the examples in this section, the following imports are required:
+
+.. code-block:: java
+
+ import org.apache.arrow.adbc.core.AdbcConnection;
+ import org.apache.arrow.adbc.core.AdbcDatabase;
+ import org.apache.arrow.adbc.core.AdbcDriver;
+ import org.apache.arrow.adbc.core.AdbcException;
+ import org.apache.arrow.adbc.core.AdbcStatement;
+
+JDBC-style API
+==============
+
+ADBC provides a high-level API in the style of the JDBC standard.
+
+Usage
+-----
+
+.. code-block:: java
+
+ final Map<String, Object> parameters = new HashMap<>();
+ parameters.put(AdbcDriver.PARAM_URL,
"jdbc:postgresql://localhost:5432/postgres");
+ try (
+ BufferAllocator allocator = new RootAllocator();
+ AdbcDatabase db = new JdbcDriver(allocator).open(parameters);
+ AdbcConnection adbcConnection = db.connect();
+ AdbcStatement stmt = adbcConnection.createStatement()
+
+ ) {
+ stmt.setSqlQuery("select * from foo");
+ AdbcStatement.QueryResult queryResult = stmt.executeQuery();
+ while (queryResult.getReader().loadNextBatch()) {
+ // process batch
+ }
+ } catch (AdbcException e) {
+ // throw
+ }
+
+In application code, the connection must be closed after usage or memory may
leak.
+It is recommended to wrap the connection in a try-with-resources block for
automatic
+resource management. In this example, we are connecting to a PostgreSQL
database,
+specifically the default database "postgres".
+
+Note that creating a statement is also wrapped in the try-with-resources block.
+Assuming we have a table "foo" in the database, an example for setting and
executing the
+query is also provided.
