ARROW-3273: [Java] Fix checkstyle for Javadocs

Enable checkstyle rules for Javadoc and apply fixes. Suppressing missing Javadocs for now because there are to many to add here. Also, changed the checkstyle DTD links to point to more official files located at checkstyle.org. This was done because to suppress a check with a specific message required an update to the suppress filter DTD. Author: Bryan Cutler <[email protected]> Closes #3009 from BryanCutler/java-checkstyle-javadoc-ARROW-3273 and squashes the following commits: 528eb27 <Bryan Cutler> fixed for arrow-gandiva 91656e3 <Bryan Cutler> rename vector banner getter to retrieval, which was more common a640b04 <Bryan Cutler> fixed for arrow-flight 90eddbc <Bryan Cutler> fixed for arrow-plasma b158614 <Bryan Cutler> fixed for arrow-jdbc 93a8bbe <Bryan Cutler> fixed for arrow-tools 00b58be <Bryan Cutler> fixed for arrow-vector 1592fcf <Bryan Cutler> fixed for arrow-memory 336420d <Bryan Cutler> Update checkstyle DTD link to official and upgrade suppression DTD to 1.3. Suppress only missing Javadoc check
apache · Nov 28, 2018 · 87feee3 · 87feee3
1 parent 99b3b0a
commit 87feee3
Show file tree

Hide file tree

Showing 109 changed files with 1,230 additions and 966 deletions.
diff --git a/java/adapter/jdbc/src/main/java/org/apache/arrow/adapter/jdbc/JdbcToArrow.java b/java/adapter/jdbc/src/main/java/org/apache/arrow/adapter/jdbc/JdbcToArrow.java
@@ -34,10 +34,10 @@
 
 /**
  * Utility class to convert JDBC objects to columnar Arrow format objects.
- * <p>
- * This utility uses following data mapping to map JDBC/SQL datatype to Arrow data types.
- * <p>
- * CHAR --> ArrowType.Utf8
+ *
+ * <p>This utility uses following data mapping to map JDBC/SQL datatype to Arrow data types.
+ *
+ * <p>CHAR --> ArrowType.Utf8
  * NCHAR --> ArrowType.Utf8
  * VARCHAR --> ArrowType.Utf8
  * NVARCHAR --> ArrowType.Utf8
@@ -61,8 +61,8 @@
  * TIMESTAMP --> ArrowType.Timestamp(TimeUnit.MILLISECOND, timezone=null)
  * CLOB --> ArrowType.Utf8
  * BLOB --> ArrowType.Binary
- * <p>
- * TODO: At this time, SQL Data type java.sql.Types.ARRAY is still not supported.
+ *
+ * <p>TODO: At this time, SQL Data type java.sql.Types.ARRAY is still not supported.
  *
  * @since 0.10.0
  */
@@ -124,9 +124,9 @@ public static VectorSchemaRoot sqlToArrow(
    * For the given JDBC {@link ResultSet}, fetch the data from Relational DB and convert it to Arrow objects. This
    * method uses the default RootAllocator and Calendar object.
    *
-   * @param resultSet
+   * @param resultSet ResultSet to use to fetch the data from underlying database
    * @return Arrow Data Objects {@link VectorSchemaRoot}
-   * @throws SQLException
+   * @throws SQLException on error
    */
   public static VectorSchemaRoot sqlToArrow(ResultSet resultSet) throws SQLException, IOException {
     Preconditions.checkNotNull(resultSet, "JDBC ResultSet object can not be null");
@@ -137,10 +137,10 @@ public static VectorSchemaRoot sqlToArrow(ResultSet resultSet) throws SQLExcepti
   /**
    * For the given JDBC {@link ResultSet}, fetch the data from Relational DB and convert it to Arrow objects.
    *
-   * @param resultSet
+   * @param resultSet ResultSet to use to fetch the data from underlying database
    * @param allocator Memory allocator
    * @return Arrow Data Objects {@link VectorSchemaRoot}
-   * @throws SQLException
+   * @throws SQLException on error
    */
   public static VectorSchemaRoot sqlToArrow(ResultSet resultSet, BaseAllocator allocator)
       throws SQLException, IOException {
@@ -153,10 +153,10 @@ public static VectorSchemaRoot sqlToArrow(ResultSet resultSet, BaseAllocator all
   /**
    * For the given JDBC {@link ResultSet}, fetch the data from Relational DB and convert it to Arrow objects.
    *
-   * @param resultSet
+   * @param resultSet ResultSet to use to fetch the data from underlying database
    * @param calendar  Calendar instance to use for Date, Time and Timestamp datasets.
    * @return Arrow Data Objects {@link VectorSchemaRoot}
-   * @throws SQLException
+   * @throws SQLException on error
    */
   public static VectorSchemaRoot sqlToArrow(ResultSet resultSet, Calendar calendar) throws SQLException, IOException {
     Preconditions.checkNotNull(resultSet, "JDBC ResultSet object can not be null");
@@ -171,11 +171,11 @@ public static VectorSchemaRoot sqlToArrow(ResultSet resultSet, Calendar calendar
   /**
    * For the given JDBC {@link ResultSet}, fetch the data from Relational DB and convert it to Arrow objects.
    *
-   * @param resultSet
+   * @param resultSet ResultSet to use to fetch the data from underlying database
    * @param allocator Memory allocator to use.
    * @param calendar  Calendar instance to use for Date, Time and Timestamp datasets.
    * @return Arrow Data Objects {@link VectorSchemaRoot}
-   * @throws SQLException
+   * @throws SQLException on error
    */
   public static VectorSchemaRoot sqlToArrow(ResultSet resultSet, BaseAllocator allocator, Calendar calendar)
       throws SQLException, IOException {

diff --git a/java/adapter/jdbc/src/main/java/org/apache/arrow/adapter/jdbc/JdbcToArrowUtils.java b/java/adapter/jdbc/src/main/java/org/apache/arrow/adapter/jdbc/JdbcToArrowUtils.java
@@ -92,10 +92,10 @@ public class JdbcToArrowUtils {
 
   /**
    * Create Arrow {@link Schema} object for the given JDBC {@link ResultSetMetaData}.
-   * <p>
-   * This method currently performs following type mapping for JDBC SQL data types to corresponding Arrow data types.
-   * <p>
-   * CHAR --> ArrowType.Utf8
+   *
+   * <p>This method currently performs following type mapping for JDBC SQL data types to corresponding Arrow data types.
+   *
+   * <p>CHAR --> ArrowType.Utf8
    * NCHAR --> ArrowType.Utf8
    * VARCHAR --> ArrowType.Utf8
    * NVARCHAR --> ArrowType.Utf8
@@ -122,7 +122,7 @@ public class JdbcToArrowUtils {
    *
    * @param rsmd ResultSetMetaData
    * @return {@link Schema}
-   * @throws SQLException
+   * @throws SQLException on error
    */
   public static Schema jdbcToArrowSchema(ResultSetMetaData rsmd, Calendar calendar) throws SQLException {
 
@@ -224,7 +224,7 @@ private static void allocateVectors(VectorSchemaRoot root, int size) {
    *
    * @param rs   ResultSet to use to fetch the data from underlying database
    * @param root Arrow {@link VectorSchemaRoot} object to populate
-   * @throws SQLException
+   * @throws SQLException on error
    */
   public static void jdbcToArrowVectors(ResultSet rs, VectorSchemaRoot root, Calendar calendar)
       throws SQLException, IOException {

diff --git a/java/adapter/jdbc/src/test/java/org/apache/arrow/adapter/jdbc/AbstractJdbcToArrowTest.java b/java/adapter/jdbc/src/test/java/org/apache/arrow/adapter/jdbc/AbstractJdbcToArrowTest.java
@@ -39,11 +39,11 @@ public abstract class AbstractJdbcToArrowTest {
   protected Table table;
 
   /**
-   * This method creates Table object after reading YAML file
+   * This method creates Table object after reading YAML file.
    *
-   * @param ymlFilePath
-   * @return
-   * @throws IOException
+   * @param ymlFilePath path to file
+   * @return Table object
+   * @throws IOException on error
    */
   protected static Table getTable(String ymlFilePath, Class clss) throws IOException {
     return new ObjectMapper(new YAMLFactory()).readValue(
@@ -52,10 +52,10 @@ protected static Table getTable(String ymlFilePath, Class clss) throws IOExcepti
 
 
   /**
-   * This method creates Connection object and DB table and also populate data into table for test
+   * This method creates Connection object and DB table and also populate data into table for test.
    *
-   * @throws SQLException
-   * @throws ClassNotFoundException
+   * @throws SQLException on error
+   * @throws ClassNotFoundException on error
    */
   @Before
   public void setUp() throws SQLException, ClassNotFoundException {
@@ -72,9 +72,9 @@ public void setUp() throws SQLException, ClassNotFoundException {
   }
 
   /**
-   * Clean up method to close connection after test completes
+   * Clean up method to close connection after test completes.
    *
-   * @throws SQLException
+   * @throws SQLException on error
    */
   @After
   public void destroy() throws SQLException {
@@ -85,12 +85,14 @@ public void destroy() throws SQLException {
   }
 
   /**
-   * This method returns collection of Table object for each test iteration
+   * Prepares test data and returns collection of Table object for each test iteration.
    *
-   * @return
-   * @throws SQLException
-   * @throws ClassNotFoundException
-   * @throws IOException
+   * @param testFiles files for test
+   * @param clss Class type
+   * @return Collection of Table objects
+   * @throws SQLException on error
+   * @throws ClassNotFoundException on error
+   * @throws IOException on error
    */
   public static Object[][] prepareTestData(String[] testFiles, Class clss)
       throws SQLException, ClassNotFoundException, IOException {
@@ -103,18 +105,18 @@ public static Object[][] prepareTestData(String[] testFiles, Class clss)
   }
 
   /**
-   * Abstract method to implement test Functionality to test JdbcToArrow methods
+   * Abstract method to implement test Functionality to test JdbcToArrow methods.
    *
-   * @throws SQLException
-   * @throws IOException
+   * @throws SQLException on error
+   * @throws IOException on error
    */
   @Test
   public abstract void testJdbcToArroValues() throws SQLException, IOException;
 
   /**
-   * Abstract method to implement logic to assert test various datatype values
+   * Abstract method to implement logic to assert test various datatype values.
    *
-   * @param root
+   * @param root VectorSchemaRoot for test
    */
   public abstract void testDataSets(VectorSchemaRoot root);
 

diff --git a/java/adapter/jdbc/src/test/java/org/apache/arrow/adapter/jdbc/JdbcToArrowTestHelper.java b/java/adapter/jdbc/src/test/java/org/apache/arrow/adapter/jdbc/JdbcToArrowTestHelper.java
@@ -41,7 +41,7 @@
 import org.apache.arrow.vector.VarCharVector;
 
 /**
- * This is a Helper class which has functionalities to read and assert the values from the given FieldVector object
+ * This is a Helper class which has functionalities to read and assert the values from the given FieldVector object.
  */
 public class JdbcToArrowTestHelper {
 

diff --git a/java/adapter/jdbc/src/test/java/org/apache/arrow/adapter/jdbc/h2/JdbcToArrowCharSetTest.java b/java/adapter/jdbc/src/test/java/org/apache/arrow/adapter/jdbc/h2/JdbcToArrowCharSetTest.java
@@ -43,7 +43,7 @@
 
 /**
  * JUnit Test Class which contains methods to test JDBC to Arrow data conversion functionality with UTF-8 Charset,
- * including the multi-byte CJK characters for H2 database
+ * including the multi-byte CJK characters for H2 database.
  */
 @RunWith(Parameterized.class)
 public class JdbcToArrowCharSetTest extends AbstractJdbcToArrowTest {
@@ -59,19 +59,19 @@ public class JdbcToArrowCharSetTest extends AbstractJdbcToArrowTest {
   };
 
   /**
-   * Constructor which populate table object for each test iteration
+   * Constructor which populate table object for each test iteration.
    *
-   * @param table
+   * @param table Table oject
    */
   public JdbcToArrowCharSetTest(Table table) {
     this.table = table;
   }
 
   /**
-   * This method creates Connection object and DB table and also populate data into table for test
+   * This method creates Connection object and DB table and also populate data into table for test.
    *
-   * @throws SQLException
-   * @throws ClassNotFoundException
+   * @throws SQLException on error
+   * @throws ClassNotFoundException on error
    */
   @Before
   public void setUp() throws SQLException, ClassNotFoundException {
@@ -88,12 +88,12 @@ public void setUp() throws SQLException, ClassNotFoundException {
   }
 
   /**
-   * This method returns collection of Table object for each test iteration
+   * Get the test data as a collection of Table objects for each test iteration.
    *
-   * @return
-   * @throws SQLException
-   * @throws ClassNotFoundException
-   * @throws IOException
+   * @return Collection of Table objects
+   * @throws SQLException on error
+   * @throws ClassNotFoundException on error
+   * @throws IOException on error
    */
   @Parameters
   public static Collection<Object[]> getTestData() throws SQLException, ClassNotFoundException, IOException {
@@ -102,7 +102,7 @@ public static Collection<Object[]> getTestData() throws SQLException, ClassNotFo
 
   /**
    * Test Method to test JdbcToArrow Functionality for various H2 DB based datatypes with UTF-8 Charset, including
-   * the multi-byte CJK characters
+   * the multi-byte CJK characters.
    */
   @Test
   public void testJdbcToArroValues() throws SQLException, IOException {
@@ -119,9 +119,9 @@ public void testJdbcToArroValues() throws SQLException, IOException {
   }
 
   /**
-   * This method calls the assert methods for various DataSets
+   * This method calls the assert methods for various DataSets.
    *
-   * @param root
+   * @param root VectorSchemaRoot for test
    */
   public void testDataSets(VectorSchemaRoot root) {
     assertVarcharVectorValues((VarCharVector) root.getVector(CLOB), table.getRowCount(),

diff --git a/...adapter/jdbc/src/test/java/org/apache/arrow/adapter/jdbc/h2/JdbcToArrowDataTypesTest.java b/...adapter/jdbc/src/test/java/org/apache/arrow/adapter/jdbc/h2/JdbcToArrowDataTypesTest.java
@@ -63,7 +63,7 @@
 
 /**
  * JUnit Test Class which contains methods to test JDBC to Arrow data conversion functionality with various data types
- * for H2 database using multiple test data files
+ * for H2 database using multiple test data files.
  */
 @RunWith(Parameterized.class)
 public class JdbcToArrowDataTypesTest extends AbstractJdbcToArrowTest {
@@ -107,29 +107,29 @@ public class JdbcToArrowDataTypesTest extends AbstractJdbcToArrowTest {
   };
 
   /**
-   * Constructor which populate table object for each test iteration
+   * Constructor which populate table object for each test iteration.
    *
-   * @param table
+   * @param table Table object
    */
   public JdbcToArrowDataTypesTest(Table table) {
     this.table = table;
   }
 
   /**
-   * This method returns collection of Table object for each test iteration
+   * Get the test data as a collection of Table objects for each test iteration.
    *
-   * @return
-   * @throws SQLException
-   * @throws ClassNotFoundException
-   * @throws IOException
+   * @return Collection of Table objects
+   * @throws SQLException on error
+   * @throws ClassNotFoundException on error
+   * @throws IOException on error
    */
   @Parameters
   public static Collection<Object[]> getTestData() throws SQLException, ClassNotFoundException, IOException {
     return Arrays.asList(prepareTestData(testFiles, JdbcToArrowDataTypesTest.class));
   }
 
   /**
-   * Test Method to test JdbcToArrow Functionality for various H2 DB based datatypes
+   * Test Method to test JdbcToArrow Functionality for various H2 DB based datatypes.
    */
   @Test
   public void testJdbcToArroValues() throws SQLException, IOException {
@@ -145,9 +145,9 @@ public void testJdbcToArroValues() throws SQLException, IOException {
   }
 
   /**
-   * This method calls the assert methods for various DataSets
+   * This method calls the assert methods for various DataSets.
    *
-   * @param root
+   * @param root VectorSchemaRoot for test
    */
   public void testDataSets(VectorSchemaRoot root) {
     switch (table.getType()) {