docs(java): First step into adding Java docs (quickstart, driver mana…

…ger summary, etc.) (apache#1191)

Cleaned up branch of apache#1188

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.

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

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
+
+   <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`.

docs/source/java/index.rst

@@ -22,4 +22,6 @@ Java
 .. toctree::
    :maxdepth: 2
 
-.. note:: Under construction
+   quickstart
+   driver_manager
+   api/index

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.