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 0000000000..6c4ec2d10f --- /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 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 klass, Map 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`` 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/api/index.rst b/docs/source/java/api/index.rst new file mode 100644 index 0000000000..e93406f3c4 --- /dev/null +++ b/docs/source/java/api/index.rst @@ -0,0 +1,25 @@ +.. 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 API Reference +==================== + +.. toctree:: + :maxdepth: 1 + + adbc_driver_manager diff --git a/docs/source/java/driver_manager.rst b/docs/source/java/driver_manager.rst new file mode 100644 index 0000000000..78215a0e90 --- /dev/null +++ b/docs/source/java/driver_manager.rst @@ -0,0 +1,38 @@ +.. 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. + +============== +Driver Manager +============== + +Installation +============ + +To include the ADBC Driver Manager in your Maven project, add the following dependency: + +.. code-block:: xml + + + org.apache.arrow.adbc + adbc-driver-manager + ${adbc.version} + + +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 ccfe071d92..c969941722 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 0000000000..c6255c3ae0 --- /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 + + + org.apache.arrow.adbc + adbc-driver-jdbc + ${adbc.version} + + +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 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.