Updated validaton & documentation, and unit tests for the new JdbcToArrowConfig.

Author: Mike Pigott

java/adapter/jdbc/src/main/java/org/apache/arrow/adapter/jdbc/JdbcToArrowConfig.java

@@ -25,11 +25,27 @@
 
 /**
  * This class configures the JDBC-to-Arrow conversion process.
+ * <p>
+ * The allocator is used to construct the {@link org.apache.arrow.vector.VectorSchemaRoot},
+ * and the calendar is used to define the time zone of any {@link org.apahe.arrow.vector.pojo.ArrowType.Timestamp}
+ * fields that are created during the conversion.
+ * </p>
+ * <p>
+ * Neither field may be <code>null</code>.
+ * </p>
  */
 public final class JdbcToArrowConfig {
   private Calendar calendar;
   private BaseAllocator allocator;
 
+  /**
+   * Constructs a new configuration from the provided allocator and calendar.  The <code>allocator</code>
+   * is used when constructing the Arrow vectors from the ResultSet, and the calendar is used to define
+   * Arrow Timestamp fields, and to read time-based fields from the JDBC <code>ResultSet</code>. 
+   *
+   * @param allocator The memory allocator to construct the Arrow vectors with.
+   * @param calendar The calendar to use when constructing Timestamp fields and reading time-based results.
+   */
   public JdbcToArrowConfig(BaseAllocator allocator, Calendar calendar) {
     Preconditions.checkNotNull(allocator, "Memory allocator cannot be null");
     Preconditions.checkNotNull(calendar, "Calendar object can not be null");
@@ -48,10 +64,16 @@ public Calendar getCalendar() {
   }
 
   /**
+   * Sets the {@link Calendar} to use when constructing timestamp fields in the
+   * Arrow schema, and reading time-based fields from the JDBC <code>ResultSet</code>.
+   *
    * @param calendar the calendar to set.
+   * @exception NullPointerExeption if <code>calendar</code> is <code>null</code>.
    */
-  public void setCalendar(Calendar calendar) {
+  public JdbcToArrowConfig setCalendar(Calendar calendar) {
+    Preconditions.checkNotNull(calendar, "Calendar object can not be null");
     this.calendar = calendar;
+    return this;
   }
 
   /**
@@ -63,13 +85,27 @@ public BaseAllocator getAllocator() {
   }
 
   /**
+   * Sets the memory allocator to use when construting the Arrow vectors from the ResultSet.
+   *
    * @param allocator the allocator to set.
+   * @exception NullPointerException if <code>allocator</code> is null.
    */
-  public void setAllocator(BaseAllocator allocator) {
+  public JdbcToArrowConfig setAllocator(BaseAllocator allocator) {
+    Preconditions.checkNotNull(allocator, "Memory allocator cannot be null");
     this.allocator = allocator;
+    return this;
   }
 
+  /**
+   * Whether this configuration is valid.  The configuration is valid when:
+   * <ul>
+   *   <li>A memory allocator is provided.</li>
+   *   <li>A calendar is provided.</li>
+   * </ul>
+   *
+   * @return Whether this configuration is valid.
+   */
   public boolean isValid() {
-    return (calendar != null) || (allocator != null);
+    return (calendar != null) && (allocator != null);
   }
 }

java/adapter/jdbc/src/test/java/org/apache/arrow/adapter/jdbc/AbstractJdbcToArrowTest.java

@@ -45,7 +45,7 @@ public abstract class AbstractJdbcToArrowTest {
    * @return Table object
    * @throws IOException on error
    */
-  protected static Table getTable(String ymlFilePath, Class clss) throws IOException {
+  protected static Table getTable(String ymlFilePath, @SuppressWarnings("rawtypes") Class clss) throws IOException {
     return new ObjectMapper(new YAMLFactory()).readValue(
             clss.getClassLoader().getResourceAsStream(ymlFilePath), Table.class);
   }
@@ -94,7 +94,7 @@ public void destroy() throws SQLException {
    * @throws ClassNotFoundException on error
    * @throws IOException on error
    */
-  public static Object[][] prepareTestData(String[] testFiles, Class clss)
+  public static Object[][] prepareTestData(String[] testFiles, @SuppressWarnings("rawtypes") Class clss)
       throws SQLException, ClassNotFoundException, IOException {
     Object[][] tableArr = new Object[testFiles.length][];
     int i = 0;

java/adapter/jdbc/src/test/java/org/apache/arrow/adapter/jdbc/JdbcToArrowConfigTest.java

@@ -0,0 +1,78 @@
+/*
+ * 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.adapter.jdbc;
+
+import static org.junit.Assert.*;
+
+import java.util.Calendar;
+import java.util.Locale;
+import java.util.TimeZone;
+
+import org.apache.arrow.memory.BaseAllocator;
+import org.apache.arrow.memory.RootAllocator;
+import org.junit.Test;
+
+public class JdbcToArrowConfigTest {
+
+  private static final RootAllocator allocator = new RootAllocator(Integer.MAX_VALUE);
+  private static final Calendar calendar = Calendar.getInstance(TimeZone.getTimeZone("UTC"), Locale.ROOT);
+
+  @Test(expected = NullPointerException.class)
+  public void testNullArguments() {
+    new JdbcToArrowConfig(null, null);
+  }
+
+  @Test(expected = NullPointerException.class)
+  public void testNullCalendar() {
+    new JdbcToArrowConfig(allocator, null);
+  }
+
+  @Test(expected = NullPointerException.class)
+  public void testNullAllocator() {
+    new JdbcToArrowConfig(null, calendar);
+  }
+
+  @Test(expected = NullPointerException.class)
+  public void testSetNullAllocator() {
+    JdbcToArrowConfig config = new JdbcToArrowConfig(allocator, calendar);
+    config.setAllocator(null);
+  }
+
+  @Test(expected = NullPointerException.class)
+  public void testSetNullCalendar() {
+    JdbcToArrowConfig config = new JdbcToArrowConfig(allocator, calendar);
+    config.setCalendar(null);
+  }
+
+  @Test
+  public void testConfig() {
+    JdbcToArrowConfig config = new JdbcToArrowConfig(allocator, calendar);
+    assertTrue(config.isValid());
+    assertTrue(allocator == config.getAllocator());
+    assertTrue(calendar == config.getCalendar());
+
+    Calendar newCalendar = Calendar.getInstance();
+    BaseAllocator newAllocator = new RootAllocator(Integer.SIZE);
+
+    config.setAllocator(newAllocator).setCalendar(newCalendar);
+
+    assertTrue(config.isValid());
+    assertTrue(newAllocator == config.getAllocator());
+    assertTrue(newCalendar == config.getCalendar());
+  }
+}