Fix some checkstyle exceptions, and remove entries from the checkstyl…

…e suppressions file.

Obsolete one class where we can use Guava instead.

core/src/main/java/net/hydromatic/optiq/Schema.java

@@ -117,6 +117,7 @@ public interface Schema {
    * stores the defined objects in a wrapper object. */
   boolean isMutable();
 
+  /** Table type. */
   enum TableType {
     /** A regular table. */
     TABLE,

core/src/main/java/net/hydromatic/optiq/TableFactory.java

@@ -72,6 +72,8 @@
  *
  * <p>A class that implements TableFactory specified in a schema must have a
  * public default constructor.</p>
+ *
+ * @param <T> Sub-type of table created by this factory
  */
 public interface TableFactory<T extends Table> {
   /** Creates a Table.

core/src/main/java/net/hydromatic/optiq/impl/AbstractTableQueryable.java

@@ -28,7 +28,7 @@
 
 /**
  * Abstract implementation of {@link net.hydromatic.linq4j.Queryable} for
- * {@link Table}.
+ * {@link QueryableTable}.
  *
  * <p>Not to be confused with
  * {@link net.hydromatic.optiq.impl.java.AbstractQueryableTable}.</p>

core/src/main/java/net/hydromatic/optiq/impl/clone/ColumnLoader.java

@@ -40,6 +40,8 @@
 
 /**
  * Column loader.
+ *
+ * @param <T> Element type of source table
  */
 class ColumnLoader<T> {
   static final int[] INT_B = {0x2, 0xC, 0xF0, 0xFF00, 0xFFFF0000};

core/src/main/java/net/hydromatic/optiq/jdbc/OptiqJdbc41Factory.java

@@ -96,6 +96,7 @@ public ResultSetMetaData newResultSetMetaData(
         statement, null, columnMetaDataList);
   }
 
+  /** Implementation of connection for JDBC 4.1. */
   private static class OptiqJdbc41Connection extends OptiqConnectionImpl {
     OptiqJdbc41Connection(Driver driver, AvaticaFactory factory, String url,
         Properties info, OptiqRootSchema rootSchema,

core/src/main/java/net/hydromatic/optiq/jdbc/OptiqPrepare.java

@@ -104,6 +104,8 @@ RelNode flattenTypes(RelOptPlanner planner, RelNode rootRel,
     Object sparkContext();
   }
 
+  /** Namespace that allows us to define non-abstract methods inside an
+   * interface. */
   public static class Dummy {
     private static SparkHandler sparkHandler;
 
@@ -145,6 +147,8 @@ public static void pop(Context context) {
       Stacks.pop(THREAD_CONTEXT_STACK.get(), context);
     }
 
+    /** Implementation of {@link SparkHandler} that either does nothing or
+     * throws for each method. Use this if Spark is not installed. */
     private static class TrivialSparkHandler implements SparkHandler {
       public RelNode flattenTypes(RelOptPlanner planner, RelNode rootRel,
           boolean restructure) {
@@ -168,6 +172,7 @@ public Object sparkContext() {
     }
   }
 
+  /** The result of parsing and validating a SQL query. */
   public static class ParseResult {
     public final OptiqPrepareImpl prepare;
     public final String sql; // for debug
@@ -187,6 +192,9 @@ public ParseResult(OptiqPrepareImpl prepare, SqlValidator validator,
     }
   }
 
+  /** The result of preparing a query. It gives the Avatica driver framework
+   * the information it needs to create a prepared statement, or to execute a
+   * statement directly, without an explicit prepare step. */
   public static class PrepareResult<T> implements AvaticaPrepareResult {
     public final String sql; // for debug
     public final List<AvaticaParameter> parameterList;

core/src/main/java/net/hydromatic/optiq/jdbc/OptiqSchema.java

@@ -162,6 +162,16 @@ public static OptiqSchema from(SchemaPlus plus) {
     return ((SchemaPlusImpl) plus).optiqSchema();
   }
 
+  /**
+   * Entry in a schema, such as a table or sub-schema.
+   *
+   * <p>Each object's name is a property of its membership in a schema;
+   * therefore in principle it could belong to several schemas, or
+   * even the same schema several times, with different names. In this
+   * respect, it is like an inode in a Unix file system.</p>
+   *
+   * <p>The members of a schema must have unique names.
+   */
   public abstract static class Entry {
     public final OptiqSchema schema;
     public final String name;
@@ -179,6 +189,7 @@ public final List<String> path() {
     }
   }
 
+  /** Membership of a table in a schema. */
   public abstract static class TableEntry extends Entry {
     public TableEntry(OptiqSchema schema, String name) {
       super(schema, name);
@@ -187,6 +198,7 @@ public TableEntry(OptiqSchema schema, String name) {
     public abstract Table getTable();
   }
 
+  /** Membership of a table-function in a schema. */
   public abstract static class TableFunctionEntry extends Entry {
     public TableFunctionEntry(OptiqSchema schema, String name) {
       super(schema, name);
@@ -199,6 +211,7 @@ public TableFunctionEntry(OptiqSchema schema, String name) {
     public abstract boolean isMaterialization();
   }
 
+  /** Implementation of {@link SchemaPlus} based on an {@code OptiqSchema}. */
   private class SchemaPlusImpl implements SchemaPlus {
     public OptiqSchema optiqSchema() {
       return OptiqSchema.this;

core/src/main/java/net/hydromatic/optiq/materialize/MaterializationActor.java

@@ -34,6 +34,8 @@ class MaterializationActor {
   final Map<MaterializationKey, Materialization> keyMap =
       new HashMap<MaterializationKey, Materialization>();
 
+  /** A query materialized in a table, so that reading from the table gives the
+   * same results as executing the query. */
   static class Materialization {
     final MaterializationKey key;
     final OptiqRootSchema rootSchema;

core/src/main/java/net/hydromatic/optiq/prepare/PlannerImpl.java

@@ -200,6 +200,7 @@ public RelNode transform(int ruleSetIndex, RelTraitSet requiredOutputTraits,
     return planner.findBestExp();
   }
 
+  /** Stage of a statement in the query-preparation lifecycle. */
   private enum State {
     STATE_0_CLOSED {
       @Override

core/src/main/java/net/hydromatic/optiq/prepare/Prepare.java

@@ -347,6 +347,7 @@ private boolean shouldTrim(RelNode rootRel) {
 
   /** Returns the number of {@link JoinRelBase} nodes in a tree. */
   private static int countJoins(RelNode rootRel) {
+    /** Visitor that counts join nodes. */
     class JoinCounter extends RelVisitor {
       int joinCount;
 
@@ -386,6 +387,7 @@ public RelNode expandView(
 
   protected abstract SqlValidator getSqlValidator();
 
+  /** Interface by which validator and planner can read table metadata. */
   public interface CatalogReader
       extends RelOptSchema, SqlValidatorCatalogReader {
     PreparingTable getTableForMember(List<String> names);
@@ -397,6 +399,7 @@ public interface CatalogReader
     PreparingTable getTable(List<String> names);
   }
 
+  /** Definition of a table, for the purposes of the validator and planner. */
   public interface PreparingTable
       extends RelOptTable, SqlValidatorTable {
   }

core/src/main/java/net/hydromatic/optiq/prepare/QueryableRelBuilder.java

@@ -52,6 +52,8 @@
  *
  * <p>NOTE: Many methods currently throw {@link UnsupportedOperationException}.
  * These method need to be implemented.</p>
+ *
+ * @param <T> Element type
  */
 class QueryableRelBuilder<T> implements QueryableFactory<T> {
   private final LixToRelTranslator translator;

core/src/main/java/net/hydromatic/optiq/rules/java/EnumerableRel.java

@@ -82,6 +82,8 @@ public Prefer of(JavaRowFormat format) {
     }
   }
 
+  /** Result of implementing an enumerable relational expression by generating
+   * Java code. */
   class Result {
     public final BlockStatement block;
 

core/src/main/java/net/hydromatic/optiq/rules/java/EnumerableRelImplementor.java

@@ -352,6 +352,7 @@ public EnumerableRel.Result result(PhysType physType, BlockStatement block) {
         block, physType, ((PhysTypeImpl) physType).format);
   }
 
+  /** Visitor that finds types in an {@link Expression} tree. */
   private static class TypeFinder extends Visitor {
     private final LinkedHashSet<Type> types;
 

core/src/main/java/net/hydromatic/optiq/rules/java/RexImpTable.java

@@ -644,13 +644,31 @@ Expression implementResultPlus(
         Expression end, Expression rows, Expression current);
   }
 
+  /** Strategy what an operator should return if one of its
+   * arguments is null. */
   public enum NullAs {
+    /** The most common policy among the SQL built-in operators. If
+     * one of the arguments is null, returns null. */
     NULL,
+
+    /** If one of the arguments is null, the function returns
+     * false. Example: {@code IS NOT NULL}. */
     FALSE,
+
+    /** If one of the arguments is null, the function returns
+     * true. Example: {@code IS NULL}. */
     TRUE,
+
+    /** It is not possible for any of the arguments to be null.  If
+     * the argument type is nullable, the enclosing code will already
+     * have performed a not-null check. This may allow the operator
+     * implementor to generate a more efficient implementation, for
+     * example, by avoiding boxing or unboxing. */
     NOT_POSSIBLE,
+
     /** Return false if result is not null, true if result is null. */
     IS_NULL,
+
     /** Return true if result is not null, false if result is null. */
     IS_NOT_NULL;
 

core/src/main/java/net/hydromatic/optiq/runtime/AbstractCursor.java

@@ -204,6 +204,7 @@ static Timestamp longToTimestamp(long v, Calendar calendar) {
     return new Timestamp(v);
   }
 
+  /** Implementation of {@link Accessor}. */
   static class AccessorImpl implements Accessor {
     protected final Getter getter;
 

core/src/main/java/net/hydromatic/optiq/runtime/ArrayComparator.java

@@ -17,6 +17,8 @@
 */
 package net.hydromatic.optiq.runtime;
 
+import com.google.common.collect.Ordering;
+
 import java.util.Collections;
 import java.util.Comparator;
 
@@ -41,7 +43,7 @@ private static Comparator[] comparators(boolean[] descendings) {
       comparators[i] =
           descending
               ? Collections.reverseOrder()
-              : ComparableComparator.instance();
+              : Ordering.natural();
     }
     return comparators;
   }

core/src/main/java/net/hydromatic/optiq/runtime/ArrayEnumeratorCursor.java

@@ -48,6 +48,8 @@ public void close() {
     enumerator.close();
   }
 
+  /** Implementation of {@link Getter} that reads from records that are
+   * arrays. */
   class ArrayEnumeratorGetter extends AbstractGetter {
     protected final int field;
 

core/src/main/java/net/hydromatic/optiq/runtime/Bindable.java

@@ -23,6 +23,8 @@
 
 /**
  * Statement that can be bound to a {@link DataContext} and then executed.
+ *
+ * @param <T> Element type of the resulting enumerable
  */
 public interface Bindable<T> {
   /**

core/src/main/java/net/hydromatic/optiq/runtime/FlatLists.java

@@ -119,6 +119,7 @@ public static <T> List<T> of(List<T> t) {
     }
   }
 
+  /** Base class for flat lists. */
   public abstract static class AbstractFlatList<T>
       implements List<T>, RandomAccess {
     protected final List<T> asArrayList() {
@@ -477,6 +478,7 @@ public int compareTo(List o) {
     }
   }
 
+  /** Empty list that implements the {@link Comparable} interface. */
   private static class ComparableEmptyList
       extends AbstractList
       implements Comparable<List> {
@@ -519,6 +521,8 @@ public int compareTo(List o) {
   public interface ComparableList<T> extends List<T>, Comparable<List> {
   }
 
+  /** Wrapper around a list that makes it implement the {@link Comparable}
+   * interface using lexical ordering. The elements must be comparable. */
   static class ComparableListImpl<T extends Comparable<T>>
       extends AbstractList<T>
       implements ComparableList<T> {

core/src/main/java/net/hydromatic/optiq/runtime/ObjectEnumeratorCursor.java

@@ -48,6 +48,9 @@ public void close() {
     enumerator.close();
   }
 
+  /** Implementation of {@link Getter} for records that consist of a single
+   * field. Each record is represented as an object, and the value of the sole
+   * field is that object. */
   class ObjectEnumeratorGetter extends AbstractGetter {
     public ObjectEnumeratorGetter(int field) {
       assert field == 0;

core/src/main/java/net/hydromatic/optiq/runtime/RecordEnumeratorCursor.java

@@ -26,6 +26,8 @@
  * {@link net.hydromatic.linq4j.Enumerator} that
  * returns a record for each row. The record is a synthetic class whose fields
  * are all public.
+ *
+ * @param <E> Element type
  */
 public class RecordEnumeratorCursor<E> extends AbstractCursor {
   private final Enumerator<E> enumerator;
@@ -56,6 +58,7 @@ public void close() {
     enumerator.close();
   }
 
+  /** Implementation of {@link Getter} that reads fields via reflection. */
   class RecordEnumeratorGetter extends AbstractGetter {
     protected final Field field;
 

core/src/main/java/net/hydromatic/optiq/runtime/ResultSetEnumerable.java

@@ -31,6 +31,8 @@
 
 /**
  * Executes a SQL statement and returns the result as an {@link Enumerable}.
+ *
+ * @param <T> Element type
  */
 public class ResultSetEnumerable<T> extends AbstractEnumerable<T> {
   private final DataSource dataSource;
@@ -148,6 +150,8 @@ public Enumerator<T> enumerator() {
     }
   }
 
+  /** Implementation of {@link Enumerator} that reads from a
+   * {@link ResultSet}. */
   private static class ResultSetEnumerator<T> implements Enumerator<T> {
     private final Function0<T> rowBuilder;
     private ResultSet resultSet;

core/src/main/java/net/hydromatic/optiq/runtime/SortedMultiMap.java

@@ -22,6 +22,9 @@
 /**
  * Map that allows you to partition values into lists according to a common
  * key, and then convert those lists into an iterator of sorted arrays.
+ *
+ * @param <K> Key type
+ * @param <V> Value type
  */
 public class SortedMultiMap<K, V> extends HashMap<K, List<V>> {
   public void putMulti(K key, V value) {

core/src/main/java/net/hydromatic/optiq/runtime/SqlFunctions.java

@@ -1454,6 +1454,9 @@ public static boolean isNotFalse(Boolean b) {
     return b == null || b;
   }
 
+  /** A range of time units. The first is more significant than the
+   * other (e.g. year-to-day) or the same as the other
+   * (e.g. month). */
   public enum TimeUnitRange {
     YEAR,
     YEAR_TO_MONTH,