[Java] Add basic Flight SQL driver (#47)

* [Java] Add basic Flight SQL driver

* [Java] Add partition descriptor support

* [Java] Properly handle FlightEndpoint.locations

* [Java] Refactor handling of FlightEndpoint

* [Java] Consolidate catches

Author: lidavidm

java/core/src/main/java/org/apache/arrow/adbc/core/AdbcDriver.java

@@ -21,6 +21,11 @@
 
 /** A handle to an ADBC database driver. */
 public interface AdbcDriver {
+  /** The standard parameter name for a connection URL (type String). */
+  String PARAM_URL = "adbc.url";
+  /** The standard parameter name for SQL quirks configuration (type SqlQuirks). */
+  String PARAM_SQL_QUIRKS = "adbc.sql.quirks";
+
   /**
    * Open a database via this driver.
    *

java/core/src/main/java/org/apache/arrow/adbc/core/AdbcException.java

@@ -48,6 +48,11 @@ public static AdbcException invalidArgument(String message) {
     return new AdbcException(message, /*cause*/ null, AdbcStatusCode.INVALID_ARGUMENT, null, 0);
   }
 
+  /** Create a new exception with code {@link AdbcStatusCode#IO}. */
+  public static AdbcException io(String message) {
+    return new AdbcException(message, /*cause*/ null, AdbcStatusCode.IO, null, 0);
+  }
+
   /** Create a new exception with code {@link AdbcStatusCode#INVALID_STATE}. */
   public static AdbcException invalidState(String message) {
     return new AdbcException(message, /*cause*/ null, AdbcStatusCode.INVALID_STATE, null, 0);
@@ -70,6 +75,13 @@ public int getVendorCode() {
     return vendorCode;
   }
 
+  /**
+   * Copy this exception with a different cause (a convenience for use with the static factories).
+   */
+  public AdbcException withCause(Throwable cause) {
+    return new AdbcException(this.getMessage(), cause, status, sqlState, vendorCode);
+  }
+
   @Override
   public String toString() {
     return "AdbcException{"

java/core/src/main/java/org/apache/arrow/adbc/core/PartitionDescriptor.java

@@ -21,11 +21,9 @@
 
 /** An opaque descriptor for a part of a potentially distributed or partitioned result set. */
 public final class PartitionDescriptor {
-  private final String friendlyName;
   private final ByteBuffer descriptor;
 
-  public PartitionDescriptor(final String friendlyName, final ByteBuffer descriptor) {
-    this.friendlyName = friendlyName;
+  public PartitionDescriptor(final ByteBuffer descriptor) {
     this.descriptor = Objects.requireNonNull(descriptor);
   }
 
@@ -42,23 +40,16 @@ public boolean equals(Object o) {
       return false;
     }
     PartitionDescriptor that = (PartitionDescriptor) o;
-    return Objects.equals(friendlyName, that.friendlyName)
-        && getDescriptor().equals(that.getDescriptor());
+    return descriptor.equals(that.descriptor);
   }
 
   @Override
   public int hashCode() {
-    return Objects.hash(friendlyName, getDescriptor());
+    return Objects.hash(descriptor);
   }
 
   @Override
   public String toString() {
-    return "PartitionDescriptor{"
-        + "friendlyName='"
-        + friendlyName
-        + '\''
-        + ", descriptor="
-        + descriptor
-        + '}';
+    return "PartitionDescriptor{" + "descriptor=" + descriptor + '}';
   }
 }

java/driver/flight-sql-validation/pom.xml

@@ -0,0 +1,55 @@
+<?xml version="1.0"?>
+<!-- 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. -->
+<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>
+  <parent>
+    <artifactId>arrow-adbc-java-root</artifactId>
+    <groupId>org.apache.arrow.adbc</groupId>
+    <version>9.0.0-SNAPSHOT</version>
+    <relativePath>../../pom.xml</relativePath>
+  </parent>
+
+  <artifactId>adbc-driver-flight-sql-validation</artifactId>
+  <packaging>jar</packaging>
+  <name>Arrow ADBC Driver Flight SQL Validation</name>
+  <description>Tests validating the Flight SQL driver.</description>
+
+  <dependencies>
+    <dependency>
+      <groupId>org.apache.arrow.adbc</groupId>
+      <artifactId>adbc-core</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.arrow.adbc</groupId>
+      <artifactId>adbc-driver-flight-sql</artifactId>
+      <scope>test</scope>
+    </dependency>
+
+    <!-- Testing -->
+    <dependency>
+      <groupId>org.assertj</groupId>
+      <artifactId>assertj-core</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.arrow.adbc</groupId>
+      <artifactId>adbc-driver-validation</artifactId>
+      <scope>test</scope>
+    </dependency>
+  </dependencies>
+</project>

java/driver/flight-sql-validation/src/test/java/org/apache/arrow/adbc/driver/flightsql/FlightSqlConnectionMetadataTest.java

@@ -0,0 +1,61 @@
+/*
+ * 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.
+ */
+
+package org.apache.arrow.adbc.driver.flightsql;
+
+import org.apache.arrow.adbc.driver.testsuite.AbstractConnectionMetadataTest;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Disabled;
+
+public class FlightSqlConnectionMetadataTest extends AbstractConnectionMetadataTest {
+  @BeforeAll
+  public static void beforeAll() {
+    quirks = new FlightSqlQuirks();
+  }
+
+  @Override
+  @Disabled("Not yet implemented")
+  public void getObjectsColumns() throws Exception {}
+
+  @Override
+  @Disabled("Not yet implemented")
+  public void getObjectsCatalogs() throws Exception {}
+
+  @Override
+  @Disabled("Not yet implemented")
+  public void getObjectsDbSchemas() throws Exception {
+    super.getObjectsDbSchemas();
+  }
+
+  @Override
+  @Disabled("Not yet implemented")
+  public void getObjectsTables() throws Exception {
+    super.getObjectsTables();
+  }
+
+  @Override
+  @Disabled("Not yet implemented")
+  public void getTableSchema() throws Exception {
+    super.getTableSchema();
+  }
+
+  @Override
+  @Disabled("Not yet implemented")
+  public void getTableTypes() throws Exception {
+    super.getTableTypes();
+  }
+}

java/driver/flight-sql-validation/src/test/java/org/apache/arrow/adbc/driver/flightsql/FlightSqlConnectionTest.java

@@ -0,0 +1,28 @@
+/*
+ * 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.
+ */
+
+package org.apache.arrow.adbc.driver.flightsql;
+
+import org.apache.arrow.adbc.driver.testsuite.AbstractConnectionTest;
+import org.junit.jupiter.api.BeforeAll;
+
+public class FlightSqlConnectionTest extends AbstractConnectionTest {
+  @BeforeAll
+  public static void beforeAll() {
+    quirks = new FlightSqlQuirks();
+  }
+}

java/driver/flight-sql-validation/src/test/java/org/apache/arrow/adbc/driver/flightsql/FlightSqlPartitionDescriptorTest.java

@@ -0,0 +1,28 @@
+/*
+ * 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.
+ */
+
+package org.apache.arrow.adbc.driver.flightsql;
+
+import org.apache.arrow.adbc.driver.testsuite.AbstractPartitionDescriptorTest;
+import org.junit.jupiter.api.BeforeAll;
+
+class FlightSqlPartitionDescriptorTest extends AbstractPartitionDescriptorTest {
+  @BeforeAll
+  public static void beforeAll() {
+    quirks = new FlightSqlQuirks();
+  }
+}

java/driver/flight-sql-validation/src/test/java/org/apache/arrow/adbc/driver/flightsql/FlightSqlQuirks.java

@@ -0,0 +1,75 @@
+/*
+ * 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.
+ */
+
+package org.apache.arrow.adbc.driver.flightsql;
+
+import java.util.HashMap;
+import java.util.Map;
+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.driver.testsuite.SqlValidationQuirks;
+import org.apache.arrow.flight.FlightClient;
+import org.apache.arrow.flight.FlightRuntimeException;
+import org.apache.arrow.flight.Location;
+import org.apache.arrow.flight.sql.FlightSqlClient;
+import org.apache.arrow.memory.BufferAllocator;
+import org.apache.arrow.memory.RootAllocator;
+import org.junit.jupiter.api.Assumptions;
+
+public class FlightSqlQuirks extends SqlValidationQuirks {
+  static final String FLIGHT_SQL_LOCATION_ENV_VAR = "ADBC_FLIGHT_SQL_LOCATION";
+
+  static String getFlightLocation() {
+    final String location = System.getenv(FLIGHT_SQL_LOCATION_ENV_VAR);
+    Assumptions.assumeFalse(
+        location == null || location.isEmpty(),
+        "Flight SQL server not found, set " + FLIGHT_SQL_LOCATION_ENV_VAR);
+    return location;
+  }
+
+  @Override
+  public AdbcDatabase initDatabase() throws AdbcException {
+    String url = getFlightLocation();
+
+    final Map<String, Object> parameters = new HashMap<>();
+    parameters.put(AdbcDriver.PARAM_URL, url);
+    return FlightSqlDriver.INSTANCE.open(parameters);
+  }
+
+  @Override
+  public void cleanupTable(String name) throws Exception {
+    try (final BufferAllocator allocator = new RootAllocator();
+        final FlightSqlClient client =
+            new FlightSqlClient(
+                FlightClient.builder(allocator, new Location(getFlightLocation())).build())) {
+      client.executeUpdate("DROP TABLE " + name);
+    } catch (FlightRuntimeException e) {
+      // Ignored
+    }
+  }
+
+  @Override
+  public String caseFoldTableName(String name) {
+    return name.toUpperCase();
+  }
+
+  @Override
+  public String caseFoldColumnName(String name) {
+    return name.toUpperCase();
+  }
+}

java/driver/flight-sql-validation/src/test/java/org/apache/arrow/adbc/driver/flightsql/FlightSqlStatementTest.java

@@ -0,0 +1,33 @@
+/*
+ * 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.
+ */
+
+package org.apache.arrow.adbc.driver.flightsql;
+
+import org.apache.arrow.adbc.driver.testsuite.AbstractStatementTest;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Disabled;
+
+class FlightSqlStatementTest extends AbstractStatementTest {
+  @BeforeAll
+  public static void beforeAll() {
+    quirks = new FlightSqlQuirks();
+  }
+
+  @Override
+  @Disabled("Requires spec clarification")
+  public void prepareQueryWithParameters() {}
+}