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 b6a0d0dfd feat(java/driver/jni): enable driver manifests/profiles
(#4202)
b6a0d0dfd is described below
commit b6a0d0dfd114ae7787a82080c5bc202ef417b281
Author: David Li <[email protected]>
AuthorDate: Mon Apr 13 14:17:38 2026 +0900
feat(java/driver/jni): enable driver manifests/profiles (#4202)
Closes #3258.
---
ci/scripts/docs_build.sh | 2 +-
docs/source/java/driver_manager.rst | 8 +-
docs/source/java/index.rst | 1 +
docs/source/java/jni.rst | 91 ++++++++++++++++++++++
.../apache/arrow/adbc/driver/jni/JniDriver.java | 33 +++++---
.../arrow/adbc/driver/jni/JniDriverTest.java | 64 ++++++++++++++-
6 files changed, 185 insertions(+), 14 deletions(-)
diff --git a/ci/scripts/docs_build.sh b/ci/scripts/docs_build.sh
index be2adecbb..01aa3e8d7 100755
--- a/ci/scripts/docs_build.sh
+++ b/ci/scripts/docs_build.sh
@@ -26,7 +26,7 @@ main() {
popd
pushd "$source_dir/java"
- mvn --no-transfer-progress site
+ mvn --no-transfer-progress -Pjni site
popd
pushd "$source_dir/docs"
diff --git a/docs/source/java/driver_manager.rst
b/docs/source/java/driver_manager.rst
index 5ff360cf5..7eac779d0 100644
--- a/docs/source/java/driver_manager.rst
+++ b/docs/source/java/driver_manager.rst
@@ -19,7 +19,13 @@
Driver Manager
==============
-This document describes the installation of the Java :term:`driver manager`.
+This document describes the Java :term:`driver manager`.
+
+.. note:: This driver manager can only load drivers developed in Java (or
+ other JVM languages). The :doc:`./jni` should be used to load
+ drivers from other ecosystems (including drivers developed in C/C++,
+ Go, and Rust). Currently, far more drivers are available though JNI
+ than are available in pure-Java.
Installation
============
diff --git a/docs/source/java/index.rst b/docs/source/java/index.rst
index c96994172..fe0db39e5 100644
--- a/docs/source/java/index.rst
+++ b/docs/source/java/index.rst
@@ -24,4 +24,5 @@ Java
quickstart
driver_manager
+ jni
api/index
diff --git a/docs/source/java/jni.rst b/docs/source/java/jni.rst
new file mode 100644
index 000000000..1fbe0a550
--- /dev/null
+++ b/docs/source/java/jni.rst
@@ -0,0 +1,91 @@
+.. 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.
+
+==================
+JNI Driver Manager
+==================
+
+The JNI driver manager wraps the :doc:`C/C++ driver manager
+<../cpp/driver_manager>`, making it possible to use drivers written in C/C++,
+Go, Rust, and more from Java. As the name implies, this requires JNI.
+
+Installation
+============
+
+To include the JNI driver manager in your Maven project, add the following
dependency:
+
+.. code-block:: xml
+
+ <dependency>
+ <groupId>org.apache.arrow.adbc</groupId>
+ <artifactId>adbc-driver-jni</artifactId>
+ <version>${adbc.version}</version>
+ </dependency>
+
+Usage
+=====
+
+The JNI driver manager is implemented as a "driver"; parameters for opening an
+:external+java_adbc:jtype:`AdbcDatabase
+<org.apache.arrow.adbc.core.AdbcDatabase>` are passed to the C/C++ driver
+manager, and the "real" driver is loaded. Once loaded, the Java ADBC APIs are
+forwarded to the equivalent C APIs, so there is no difference from other
+drivers in Java, and the resulting object can be used the same way as drivers
+written in Java or another JVM language.
+
+Drivers can be directly loaded via the
+:external+java_adbc:jmember:`PARAM_DRIVER
+<org.apache.arrow.adbc.driver.jni.JniDriver#PARAM_PROFILE>` option. This takes
+a path to a driver, a :doc:`driver manifest <../format/driver_manifests>`, or
+a name that will be passed to ``dlopen`` (or equivalent):
+
+.. code-block:: java
+
+ JniDriver driver = new JniDriver(allocator);
+ Map<String, Object> parameters = new HashMap<>();
+ // path to driver:
+ JniDriver.PARAM_DRIVER.set(parameters, "/path/to/libadbc_driver_sqlite.so");
+
+ // manifest:
+ JniDriver.PARAM_DRIVER.set(parameters, "sqlite");
+
+ // library name:
+ JniDriver.PARAM_DRIVER.set(parameters, "adbc_driver_sqlite");
+
+ AdbcDatabase db = driver.open(parameters);
+
+Another option is to pass only a URI, in which case the URI scheme will be
+used to find and load the driver or driver manifest:
+
+.. code-block:: java
+
+ JniDriver driver = new JniDriver(allocator);
+ Map<String, Object> parameters = new HashMap<>();
+ // Expects a profile named "postgresql" to exist (or libpostgresql.so, etc.)
+ AdbcDriver.PARAM_URI.set(parameters, "postgresql://localhost:5432/dev");
+ AdbcDatabase db = driver.open(parameters);
+
+To use :doc:`connection profiles <../format/connection_profiles>`, pass the
+:external+java_adbc:jmember:`PARAM_PROFILE
+<org.apache.arrow.adbc.driver.jni.JniDriver#PARAM_PROFILE>` option:
+
+.. code-block:: java
+
+ JniDriver driver = new JniDriver(allocator);
+ Map<String, Object> parameters = new HashMap<>();
+ JniDriver.PARAM_PROFILE.set(parameters, "staging_aws");
+ AdbcDatabase db = driver.open(parameters);
diff --git
a/java/driver/jni/src/main/java/org/apache/arrow/adbc/driver/jni/JniDriver.java
b/java/driver/jni/src/main/java/org/apache/arrow/adbc/driver/jni/JniDriver.java
index 8d084f54e..9188207fe 100644
---
a/java/driver/jni/src/main/java/org/apache/arrow/adbc/driver/jni/JniDriver.java
+++
b/java/driver/jni/src/main/java/org/apache/arrow/adbc/driver/jni/JniDriver.java
@@ -29,8 +29,25 @@ import org.apache.arrow.memory.BufferAllocator;
/** An ADBC driver wrapping Arrow Flight SQL. */
public class JniDriver implements AdbcDriver {
+ /**
+ * The driver to load.
+ *
+ * <p>Can be a path to a driver, a name (which will be found via dlopen or
equivalent), or a
+ * manifest name (which will be loaded from platform-specific paths).
+ */
public static final TypedKey<String> PARAM_DRIVER = new
TypedKey<>("jni.driver", String.class);
+ /** The profile to load. */
+ public static final TypedKey<String> PARAM_PROFILE = new
TypedKey<>("jni.profile", String.class);
+
+ /** Additional paths to search for driver manifests. */
+ public static final TypedKey<String> PARAM_MANIFEST_SEARCH_PATH =
+ new TypedKey<>("jni.additional_manifest_search_path_list", String.class);
+
+ /** Additional paths to search for connection profiles. */
+ public static final TypedKey<String> PARAM_PROFILE_SEARCH_PATH =
+ new TypedKey<>("jni.additional_profile_search_path_list", String.class);
+
private final BufferAllocator allocator;
public JniDriver(BufferAllocator allocator) {
@@ -39,20 +56,14 @@ public class JniDriver implements AdbcDriver {
@Override
public AdbcDatabase open(Map<String, Object> parameters) throws
AdbcException {
- String driverName = PARAM_DRIVER.get(parameters);
- if (driverName == null) {
- throw AdbcException.invalidArgument(
- "[JNI] Must provide String " + PARAM_DRIVER + " parameter");
- }
-
Map<String, String> nativeParameters = new HashMap<>();
- nativeParameters.put("driver", driverName);
-
for (Map.Entry<String, Object> param : parameters.entrySet()) {
- if (param.getKey().equals(PARAM_DRIVER.getKey())) continue;
-
if (param.getValue() instanceof String) {
- nativeParameters.put(param.getKey(), (String) param.getValue());
+ String key = param.getKey();
+ if (key.startsWith("jni.")) {
+ key = key.substring(4);
+ }
+ nativeParameters.put(key, (String) param.getValue());
} else {
throw AdbcException.invalidArgument("[jni] only String parameters are
supported");
}
diff --git
a/java/driver/jni/src/test/java/org/apache/arrow/adbc/driver/jni/JniDriverTest.java
b/java/driver/jni/src/test/java/org/apache/arrow/adbc/driver/jni/JniDriverTest.java
index a29f5de0b..c61fa8d2b 100644
---
a/java/driver/jni/src/test/java/org/apache/arrow/adbc/driver/jni/JniDriverTest.java
+++
b/java/driver/jni/src/test/java/org/apache/arrow/adbc/driver/jni/JniDriverTest.java
@@ -21,6 +21,9 @@ import static org.assertj.core.api.Assertions.assertThat;
import static org.junit.jupiter.api.Assertions.assertThrows;
import java.io.File;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
import java.util.ArrayList;
import java.util.Collections;
import java.util.HashMap;
@@ -30,10 +33,12 @@ import java.util.stream.Collectors;
import java.util.stream.LongStream;
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;
import org.apache.arrow.adbc.core.AdbcStatusCode;
import org.apache.arrow.adbc.core.BulkIngestMode;
+import org.apache.arrow.adbc.core.TypedKey;
import org.apache.arrow.memory.BufferAllocator;
import org.apache.arrow.memory.RootAllocator;
import org.apache.arrow.vector.BigIntVector;
@@ -44,6 +49,7 @@ import org.apache.arrow.vector.types.pojo.Field;
import org.apache.arrow.vector.types.pojo.Schema;
import org.assertj.core.api.InstanceOfAssertFactories;
import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
class JniDriverTest {
@Test
@@ -52,7 +58,63 @@ class JniDriverTest {
JniDriver driver = new JniDriver(allocator);
Map<String, Object> parameters = new HashMap<>();
JniDriver.PARAM_DRIVER.set(parameters, "adbc_driver_sqlite");
+ driver.open(parameters).close();
+ }
+ }
+
+ @Test
+ void loadManifest(@TempDir Path tempDir) throws Exception {
+ Path tempFile = Files.createFile(tempDir.resolve("mydriver.toml"));
+ // TODO(https://github.com/apache/arrow-adbc/issues/3536): use proper
multiline string
+ Files.write(
+ tempFile,
+ String.join("\n", "manifest_version = 1", "[Driver]", "shared =
\"adbc_driver_sqlite\"")
+ .getBytes(StandardCharsets.UTF_8));
+
+ try (final BufferAllocator allocator = new RootAllocator()) {
+ JniDriver driver = new JniDriver(allocator);
+ Map<String, Object> parameters = new HashMap<>();
+ JniDriver.PARAM_DRIVER.set(parameters, "mydriver");
+ JniDriver.PARAM_MANIFEST_SEARCH_PATH.set(parameters, tempDir.toString());
+ driver.open(parameters).close();
+ }
+ }
+
+ @Test
+ void loadProfile(@TempDir Path tempDir) throws Exception {
+ Path tempFile = Files.createFile(tempDir.resolve("myprofile.toml"));
+ // TODO(https://github.com/apache/arrow-adbc/issues/3536): use proper
multiline string
+ Files.write(
+ tempFile,
+ String.join(
+ "\n",
+ "profile_version = 1",
+ "driver = \"adbc_driver_sqlite\"",
+ "[Options]",
+ "adbc.sqlite.query.batch_rows = 1024")
+ .getBytes(StandardCharsets.UTF_8));
+ try (final BufferAllocator allocator = new RootAllocator()) {
+ JniDriver driver = new JniDriver(allocator);
+ Map<String, Object> parameters = new HashMap<>();
+ JniDriver.PARAM_PROFILE.set(parameters, "myprofile");
+ JniDriver.PARAM_PROFILE_SEARCH_PATH.set(parameters, tempDir.toString());
+ try (final AdbcDatabase db = driver.open(parameters)) {
+ // TODO(lidavidm): getOption not implemented
+ AdbcException e =
+ assertThrows(
+ AdbcException.class,
+ () -> db.getOption(new
TypedKey<>("adbc.sqlite.query.batch_rows", Long.class)));
+ assertThat(e).hasMessageContaining("Unsupported option");
+ }
+ }
+ }
+ @Test
+ void loadUri() throws Exception {
+ try (final BufferAllocator allocator = new RootAllocator()) {
+ JniDriver driver = new JniDriver(allocator);
+ Map<String, Object> parameters = new HashMap<>();
+ AdbcDriver.PARAM_URI.set(parameters, "adbc_driver_sqlite://");
driver.open(parameters).close();
}
}
@@ -191,7 +253,7 @@ class JniDriverTest {
final AdbcStatement stmt = conn.createStatement();
final VectorSchemaRoot root = VectorSchemaRoot.create(paramSchema,
allocator)) {
((BigIntVector) root.getVector(0)).setSafe(0, 41);
- ((BigIntVector) root.getVector(0)).setNull(1);
+ root.getVector(0).setNull(1);
root.setRowCount(2);
stmt.setSqlQuery("SELECT 1 + ?");
