ARROW-4741: [Java] Add missing type javadoc and enable checkstyle

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

@@ -17,7 +17,11 @@
 
 package org.apache.arrow.adapter.jdbc;
 
+/**
+ * String constants used for metadata returned on Vectors.
+ */
 public class Constants {
+  private Constants() {}
 
   public static final String SQL_CATALOG_NAME_KEY = "SQL_CATALOG_NAME";
   public static final String SQL_TABLE_NAME_KEY = "SQL_TABLE_NAME";

java/dev/checkstyle/checkstyle.xml

@@ -241,6 +241,15 @@
             <property name="suppressLoadErrors" value="true"/>
             <property name="ignoreMethodNamesRegex" value="main"/>
         </module>
+        <module name="JavadocType">
+            <property name="scope" value="public"/>
+        </module>
+        <module name="JavadocType">
+            <property name="scope" value="protected"/>
+        </module>
+        <module name="JavadocType">
+            <property name="scope" value="package"/>
+        </module>
         <module name="MethodName">
             <property name="format" value="^[a-z][a-z0-9][a-zA-Z0-9_]*$"/>
             <message key="name.invalidPattern"

java/dev/checkstyle/suppressions.xml

@@ -25,6 +25,8 @@
   <suppress checks="JavadocPackage" files=".*[\\/]examples[\\/].*"/>
   <!-- Method javadoc not required in testing directories -->
   <suppress checks="JavadocMethod" files=".*[\\/]src[\\/]test[\\/].*"/>
+  <!-- Class javadoc not required in testing directories -->
+  <suppress checks="JavadocType" files=".*[\\/]src[\\/]test[\\/].*"/>
 
   <!-- suppress all checks in the generated directories -->
   <suppress checks=".*" files=".+[\\/]generated[\\/].+\.java" />

java/flight/src/main/java/org/apache/arrow/flight/Action.java

@@ -21,6 +21,11 @@
 
 import com.google.protobuf.ByteString;
 
+/**
+ * An opaque action for the service to perform.
+ *
+ * <p>This is a POJO wrapper around the message of the same name in Flight.proto.
+ */
 public class Action {
 
   private final String type;

java/flight/src/main/java/org/apache/arrow/flight/ArrowMessage.java

@@ -77,6 +77,7 @@ class ArrowMessage implements AutoCloseable {
 
   private static Marshaller<FlightData> NO_BODY_MARSHALLER = ProtoUtils.marshaller(FlightData.getDefaultInstance());
 
+  /** Types of messages that can be sent. */
   public static enum HeaderType {
     NONE,
     SCHEMA,

java/flight/src/main/java/org/apache/arrow/flight/CallOptions.java

@@ -53,6 +53,9 @@ public <T extends AbstractStub<T>> T wrapStub(T stub) {
     }
   }
 
+  /**
+   * CallOptions specific to GRPC stubs.
+   */
   interface GrpcCallOption extends CallOption {
     <T extends AbstractStub<T>> T wrapStub(T stub);
   }

java/flight/src/main/java/org/apache/arrow/flight/Criteria.java

@@ -21,6 +21,11 @@
 
 import com.google.protobuf.ByteString;
 
+/**
+ * An opaque object that can be used to filter a list of streams available from a server.
+ *
+ * <p>This is a POJO wrapper around the protobuf Criteria message.
+ */
 public class Criteria {
 
   public static Criteria ALL = new Criteria((byte[]) null);

java/flight/src/main/java/org/apache/arrow/flight/FlightClient.java

@@ -306,6 +306,9 @@ public PutResult getResult() {
     }
   }
 
+  /**
+   * Interface for subscribers to a stream returned by the server.
+   */
   public interface ClientStreamListener {
 
     public void putNext();

java/flight/src/main/java/org/apache/arrow/flight/FlightConstants.java

@@ -17,8 +17,11 @@
 
 package org.apache.arrow.flight;
 
+/**
+ * String constants relevant to flight implementations.
+ */
 public interface FlightConstants {
 
-  public static final String SERVICE = "arrow.flight.protocol.FlightService";
+  String SERVICE = "arrow.flight.protocol.FlightService";
 
 }

java/flight/src/main/java/org/apache/arrow/flight/FlightDescriptor.java

@@ -27,6 +27,11 @@
 import com.google.common.collect.ImmutableList;
 import com.google.protobuf.ByteString;
 
+/**
+ * An identifier for a particular set of data.  This can either be an opaque command that generates
+ * the data or a static "path" to the data.  This is a POJO wrapper around the protobuf message with
+ * the same name.
+ */
 public class FlightDescriptor {
 
   private boolean isCmd;

java/flight/src/main/java/org/apache/arrow/flight/FlightProducer.java

@@ -27,25 +27,28 @@
  */
 public interface FlightProducer {
 
-  public void getStream(CallContext context, Ticket ticket,
+  void getStream(CallContext context, Ticket ticket,
       ServerStreamListener listener);
 
-  public void listFlights(CallContext context, Criteria criteria,
+  void listFlights(CallContext context, Criteria criteria,
       StreamListener<FlightInfo> listener);
 
-  public FlightInfo getFlightInfo(CallContext context,
+  FlightInfo getFlightInfo(CallContext context,
       FlightDescriptor descriptor);
 
-  public Callable<PutResult> acceptPut(CallContext context,
+  Callable<PutResult> acceptPut(CallContext context,
       FlightStream flightStream);
 
-  public void doAction(CallContext context, Action action,
+  void doAction(CallContext context, Action action,
       StreamListener<Result> listener);
 
-  public void listActions(CallContext context,
+  void listActions(CallContext context,
       StreamListener<ActionType> listener);
 
-  public interface ServerStreamListener {
+  /**
+   * Listener for creating a stream on the server side.
+   */
+  interface ServerStreamListener {
 
     boolean isCancelled();
 
@@ -61,7 +64,12 @@ public interface ServerStreamListener {
 
   }
 
-  public interface StreamListener<T> {
+  /**
+   * Callbacks for pushing objects to a receiver.
+   *
+   * @param <T> Type of the values in the stream.
+   */
+  interface StreamListener<T> {
 
     void onNext(T val);
 

java/flight/src/main/java/org/apache/arrow/flight/FlightServer.java

@@ -39,6 +39,10 @@
 import io.netty.channel.EventLoopGroup;
 import io.netty.channel.ServerChannel;
 
+/**
+ * Generic server of flight data that is customized via construction with delegate classes for the
+ * actual logic.  The server currently uses GRPC as its transport mechanism.
+ */
 public class FlightServer implements AutoCloseable {
 
   private static final org.slf4j.Logger logger = org.slf4j.LoggerFactory.getLogger(FlightServer.class);

java/flight/src/main/java/org/apache/arrow/flight/FlightService.java

@@ -43,6 +43,9 @@
 import io.grpc.stub.ServerCallStreamObserver;
 import io.grpc.stub.StreamObserver;
 
+/**
+ * GRPC service implementation for a flight server.
+ */
 class FlightService extends FlightServiceImplBase {
 
   private static final Logger logger = LoggerFactory.getLogger(FlightService.class);
@@ -188,6 +191,9 @@ public void getFlightInfo(Flight.FlightDescriptor request, StreamObserver<Flight
     }
   }
 
+  /**
+   * Call context for the service.
+   */
   static class CallContext implements FlightProducer.CallContext {
 
     private final String peerIdentity;

java/flight/src/main/java/org/apache/arrow/flight/FlightStream.java

@@ -222,13 +222,19 @@ StreamObserver<ArrowMessage> asObserver() {
     return new Observer();
   }
 
+  /**
+   * Provides a callback to cancel a process that is in progress.
+   */
   public interface Cancellable {
     void cancel(String message, Throwable exception);
   }
 
+  /**
+   * Provides a interface to request more items from a stream producer.
+   */
   public interface Requestor {
     /**
-     * Requests <code>count</code> more messages from the reuqestor.
+     * Requests <code>count</code> more messages from the instance of this object.
      */
     void request(int count);
   }

java/flight/src/main/java/org/apache/arrow/flight/GenericOperation.java

@@ -17,6 +17,9 @@
 
 package org.apache.arrow.flight;
 
+/**
+ * Unused?.
+ */
 class GenericOperation {
 
   private final String type;

java/flight/src/main/java/org/apache/arrow/flight/NoOpFlightProducer.java

@@ -21,6 +21,9 @@
 
 import org.apache.arrow.flight.impl.Flight.PutResult;
 
+/**
+ * A {@link FlightProducer} that throws on all operations.
+ */
 public class NoOpFlightProducer implements FlightProducer {
 
   @Override

java/flight/src/main/java/org/apache/arrow/flight/Result.java

@@ -21,6 +21,11 @@
 
 import com.google.protobuf.ByteString;
 
+/**
+ * Opaque result returned after executing an action.
+ *
+ * <p>POJO wrapper around the Flight protocol buffer message sharing the same name.
+ */
 public class Result {
 
   private final byte[] body;

java/flight/src/main/java/org/apache/arrow/flight/auth/AuthConstants.java

@@ -24,6 +24,9 @@
 import io.grpc.Metadata.Key;
 import io.grpc.MethodDescriptor;
 
+/**
+ * Constants used in authorization of flight connections.
+ */
 public final class AuthConstants {
 
   public static final String HANDSHAKE_DESCRIPTOR_NAME = MethodDescriptor

java/flight/src/main/java/org/apache/arrow/flight/auth/BasicServerAuthHandler.java

@@ -40,6 +40,9 @@ public BasicServerAuthHandler(BasicAuthValidator authValidator) {
     this.authValidator = authValidator;
   }
 
+  /**
+   * Interface that this handler delegates for determining if credentials are valid.
+   */
   public interface BasicAuthValidator {
 
     public byte[] getToken(String username, String password) throws Exception;

java/flight/src/main/java/org/apache/arrow/flight/auth/ClientAuthInterceptor.java

@@ -25,6 +25,9 @@
 import io.grpc.Metadata;
 import io.grpc.MethodDescriptor;
 
+/**
+ * GRPC client intercepter that handles authentication with the server.
+ */
 public class ClientAuthInterceptor implements ClientInterceptor {
   private volatile ClientAuthHandler authHandler = null;
 

java/flight/src/main/java/org/apache/arrow/flight/auth/ClientAuthWrapper.java

@@ -30,6 +30,9 @@
 
 import io.grpc.stub.StreamObserver;
 
+/**
+ * Utility class for performing authorization over using a GRPC stub.
+ */
 public class ClientAuthWrapper {
 
   /**

java/flight/src/main/java/org/apache/arrow/flight/auth/ServerAuthHandler.java

@@ -20,6 +20,9 @@
 import java.util.Iterator;
 import java.util.Optional;
 
+/**
+ * Interface for Server side authentication handlers.
+ */
 public interface ServerAuthHandler {
 
   /**
@@ -37,11 +40,15 @@ public interface ServerAuthHandler {
    */
   boolean authenticate(ServerAuthSender outgoing, Iterator<byte[]> incoming);
 
-  public interface ServerAuthSender {
+  /**
+   * Interface for an server implementations to send back authentication messages
+   * back to the client.
+   */
+  interface ServerAuthSender {
 
-    public void send(byte[] payload);
+    void send(byte[] payload);
 
-    public void onError(String message, Throwable cause);
+    void onError(String message, Throwable cause);
 
   }
 

java/flight/src/main/java/org/apache/arrow/flight/auth/ServerAuthInterceptor.java

@@ -28,6 +28,9 @@
 import io.grpc.ServerInterceptor;
 import io.grpc.Status;
 
+/**
+ * GRPC Interceptor for performing authentication.
+ */
 public class ServerAuthInterceptor implements ServerInterceptor {
 
   private final ServerAuthHandler authHandler;

java/flight/src/main/java/org/apache/arrow/flight/auth/ServerAuthWrapper.java

@@ -31,6 +31,9 @@
 import io.grpc.Status;
 import io.grpc.stub.StreamObserver;
 
+/**
+ * Contains utility methods for integrating authorization into a GRPC stream.
+ */
 public class ServerAuthWrapper {
 
   /**

java/flight/src/main/java/org/apache/arrow/flight/example/integration/IntegrationTestServer.java

@@ -28,6 +28,9 @@
 import org.apache.commons.cli.Options;
 import org.apache.commons.cli.ParseException;
 
+/**
+ * Flight server for integration testing.
+ */
 class IntegrationTestServer {
   private static final org.slf4j.Logger LOGGER = org.slf4j.LoggerFactory.getLogger(IntegrationTestServer.class);
   private final Options options;

java/gandiva/src/main/java/org/apache/arrow/gandiva/evaluator/DecimalTypeUtil.java

@@ -19,8 +19,15 @@
 
 import org.apache.arrow.vector.types.pojo.ArrowType.Decimal;
 
+/**
+ * Utility methods for working with {@link Decimal} values.
+ */
 public class DecimalTypeUtil {
+  private DecimalTypeUtil() {}
 
+  /**
+   * Enum for supported mathematical operations.
+   */
   public enum OperationType {
     ADD,
     SUBTRACT,

java/gandiva/src/main/java/org/apache/arrow/gandiva/evaluator/SelectionVectorInt16.java

@@ -21,7 +21,7 @@
 
 import io.netty.buffer.ArrowBuf;
 
-/*
+/**
  * Selection vector with records of arrow type INT16.
  */
 public class SelectionVectorInt16 extends SelectionVector {

java/gandiva/src/main/java/org/apache/arrow/gandiva/evaluator/SelectionVectorInt32.java

@@ -21,7 +21,7 @@
 
 import io.netty.buffer.ArrowBuf;
 
-/*
+/**
  * Selection vector with records of arrow type INT32.
  */
 public class SelectionVectorInt32 extends SelectionVector {

java/gandiva/src/main/java/org/apache/arrow/gandiva/exceptions/EvaluatorClosedException.java

@@ -17,6 +17,7 @@
 
 package org.apache.arrow.gandiva.exceptions;
 
+/** Indicates an attempted call to methods on a closed evaluator. */
 public class EvaluatorClosedException extends GandivaException {
   public EvaluatorClosedException() {
     super("Cannot invoke methods on evaluator after closing it");

java/gandiva/src/main/java/org/apache/arrow/gandiva/exceptions/GandivaException.java

@@ -17,6 +17,7 @@
 
 package org.apache.arrow.gandiva.exceptions;
 
+/** Base class for all specialized exceptions this package uses. */
 public class GandivaException extends Exception {
 
   public GandivaException(String msg) {