Add javadoc and some assertions

h2/src/main/org/h2/mvstore/db/MVPlainTempResult.java

@@ -22,20 +22,54 @@ import org.h2.value.ValueLong;
  */
 class MVPlainTempResult extends MVTempResult {
 
+    /**
+     * The type of the values in the main map and keys in the index.
+     */
     private final ValueDataType valueType;
+
+    /**
+     * Map with identities of rows as keys rows as values.
+     */
     private final MVMap<ValueLong, ValueArray> map;
+
+    /**
+     * Counter for the identities of rows. A separate counter is used instead of
+     * {@link #rowCount} because rows due to presence of {@link #removeRow(Value[])}
+     * method to ensure that each row will have an own identity.
+     */
     private long counter;
 
+    /**
+     * Optional index. This index is created only if {@link #contains(Value[])}
+     * method is invoked. Only the root result should have an index if required.
+     */
     private MVMap<ValueArray, Boolean> index;
 
+    /**
+     * Cursor for the {@link #next()} method.
+     */
     private Cursor<ValueLong, ValueArray> cursor;
 
+    /**
+     * Creates a shallow copy of the result.
+     *
+     * @param parent
+     *                   parent result
+     */
     private MVPlainTempResult(MVPlainTempResult parent) {
         super(parent);
         this.valueType = null;
         this.map = parent.map;
     }
 
+    /**
+     * Creates a new plain temporary result.
+     *
+     * @param session
+     *                        database session.
+     * @param expressions
+     *                        column expressions
+     */
     MVPlainTempResult(Session session, Expression[] expressions) {
         super(session);
         Database db = session.getDatabase();
@@ -48,12 +82,14 @@ class MVPlainTempResult extends MVTempResult {
 
     @Override
     public int addRow(Value[] values) {
+        assert parent == null && index == null;
         map.put(ValueLong.get(counter++), ValueArray.get(values));
         return ++rowCount;
     }
 
     @Override
     public boolean contains(Value[] values) {
+        // Only parent result maintains the index
         if (parent != null) {
             return parent.contains(values);
         }

h2/src/main/org/h2/mvstore/db/MVSortedTempResult.java

@@ -20,17 +20,53 @@ import org.h2.value.ValueArray;
 
 /**
  * Sorted temporary result.
+ *
+ * <p>
+ * This result is used for distinct and/or sorted results.
+ * </p>
  */
 class MVSortedTempResult extends MVTempResult {
 
+    /**
+     * Whether this result is distinct.
+     */
     private final boolean distinct;
+
+    /**
+     * Mapping of indexes of columns to its positions in the store, or {@code null}
+     * if columns are not reordered.
+     */
     private final int[] indexes;
+
+    /**
+     * Map with rows as keys and counts of duplicate rows as values. If this map is
+     * distinct all values are 1.
+     */
     private final MVMap<ValueArray, Long> map;
 
+    /**
+     * Cursor for the {@link #next()} method.
+     */
     private Cursor<ValueArray, Long> cursor;
+
+    /**
+     * Current value for the {@link #next()} method. Used in non-distinct results
+     * with duplicate rows.
+     */
     private Value[] current;
+
+    /**
+     * Count of remaining duplicate rows for the {@link #next()} method. Used in
+     * non-distinct results.
+     */
     private long valueCount;
 
+    /**
+     * Creates a shallow copy of the result.
+     *
+     * @param parent
+     *                   parent result
+     */
     private MVSortedTempResult(MVSortedTempResult parent) {
         super(parent);
         this.distinct = parent.distinct;
@@ -41,6 +77,16 @@ class MVSortedTempResult extends MVTempResult {
 
     /**
      * Creates a new sorted temporary result.
+     *
+     * @param session
+     *                        database session
+     * @param expressions
+     *                        column expressions
+     * @param distinct
+     *                        whether this result should be distinct
+     * @param sort
+     *                        sort order, or {@code null} if this result does not
+     *                        need any sorting
      */
     MVSortedTempResult(Session session, Expression[] expressions, boolean distinct, SortOrder sort) {
         super(session);
@@ -50,31 +96,53 @@ class MVSortedTempResult extends MVTempResult {
         int[] sortTypes = new int[length];
         int[] indexes;
         if (sort != null) {
+            /*
+             * If sorting is specified we need to reorder columns in requested order and set
+             * sort types (ASC, DESC etc) for them properly.
+             */
             indexes = new int[length];
             int[] colIndex = sort.getQueryColumnIndexes();
             int len = colIndex.length;
+            // This set is used to remember columns that are already included
             BitSet used = new BitSet();
             for (int i = 0; i < len; i++) {
                 int idx = colIndex[i];
+                assert !used.get(idx);
                 used.set(idx);
                 indexes[i] = idx;
                 sortTypes[i] = sort.getSortTypes()[i];
             }
+            /*
+             * Because this result may have more columns than specified in sorting we need
+             * to add all remaining columns to the mapping of columns. A default sorting
+             * order (ASC / 0) will be used for them.
+             */
             int idx = 0;
             for (int i = len; i < length; i++) {
                 idx = used.nextClearBit(idx);
                 indexes[i] = idx;
                 idx++;
             }
+            /*
+             * Sometimes columns may be not reordered. Because reordering of columns
+             * slightly slows down other methods we check whether columns are really
+             * reordered or have the same order.
+             */
             sameOrder: {
                 for (int i = 0; i < length; i++) {
                     if (indexes[i] != i) {
+                        // Columns are reordered
                         break sameOrder;
                     }
                 }
+                /*
+                 * Columns are not reordered, set this field to null to disable reordering in
+                 * other methods.
+                 */
                 indexes = null;
             }
         } else {
+            // Columns are not reordered if sort order is not specified
             indexes = null;
         }
         this.indexes = indexes;
@@ -85,14 +153,18 @@ class MVSortedTempResult extends MVTempResult {
 
     @Override
     public int addRow(Value[] values) {
+        assert parent == null;
         ValueArray key = getKey(values);
         if (distinct) {
+            // Add a row and increment the counter only if row does not exist
             if (map.putIfAbsent(key, 1L) == null) {
                 rowCount++;
             }
         } else {
+            // Try to set counter to 1 first if such row does not exist yet
             Long old = map.putIfAbsent(key, 1L);
             if (old != null) {
+                // This rows is already in the map, increment its own counter
                 map.put(key, old + 1);
             }
             rowCount++;
@@ -117,6 +189,13 @@ class MVSortedTempResult extends MVTempResult {
         return new MVSortedTempResult(this);
     }
 
+    /**
+     * Reorder values if required and convert them into {@link ValueArray}.
+     *
+     * @param values
+     *                   values
+     * @return ValueArray for maps
+     */
     private ValueArray getKey(Value[] values) {
         if (indexes != null) {
             Value[] r = new Value[indexes.length];
@@ -128,6 +207,13 @@ class MVSortedTempResult extends MVTempResult {
         return ValueArray.get(values);
     }
 
+    /**
+     * Reorder values back if required.
+     *
+     * @param key
+     *                reordered values
+     * @return original values
+     */
     private Value[] getValue(Value[] key) {
         if (indexes != null) {
             Value[] r = new Value[indexes.length];
@@ -146,22 +232,35 @@ class MVSortedTempResult extends MVTempResult {
             current = null;
             valueCount = 0L;
         }
+        // If we have multiple rows with the same values return them all
         if (--valueCount > 0) {
+            /*
+             * Underflow in valueCount is hypothetically possible after a lot of invocations
+             * (not really possible in practice), but current will be null anyway.
+             */
             return current;
         }
-        current = null;
         if (!cursor.hasNext()) {
+            // Set current to null to be sure
+            current = null;
             return null;
         }
+        // Read the next row
         current = getValue(cursor.next().getList());
+        /*
+         * If valueCount is greater than 1 that is possible for non-distinct results the
+         * following invocations of next() will use this.current and this.valueCount.
+         */
         valueCount = cursor.getValue();
         return current;
     }
 
     @Override
     public int removeRow(Value[] values) {
+        assert parent == null;
         ValueArray key = getKey(values);
         if (distinct) {
+            // If an entry was removed decrement the counter
             if (map.remove(key) != null) {
                 rowCount--;
             }
@@ -170,6 +269,10 @@ class MVSortedTempResult extends MVTempResult {
             if (old != null) {
                 long l = old;
                 if (l > 1) {
+                    /*
+                     * We have more than one such row. Decrement its counter by 1 and put this row
+                     * back into map.
+                     */
                     map.put(key, l - 1);
                 }
                 rowCount--;

h2/src/main/org/h2/mvstore/db/MVTempResult.java

@@ -23,6 +23,13 @@ import org.h2.value.Value;
 
 /**
  * Temporary result.
+ *
+ * <p>
+ * A separate MVStore in a temporary file is used for each result. The file is
+ * removed when this result and all its copies are closed.
+ * {@link TempFileDeleter} is also used to delete this file if results are not
+ * closed properly.
+ * </p>
  */
 public abstract class MVTempResult implements ResultExternal {
 
@@ -44,20 +51,52 @@ public abstract class MVTempResult implements ResultExternal {
                 : new MVPlainTempResult(session, expressions);
     }
 
+    /**
+     * MVStore.
+     */
     final MVStore store;
 
+    /**
+     * Count of rows. Used only in a root results, copies always have 0 value.
+     */
     int rowCount;
 
+    /**
+     * Parent store for copies. If {@code null} this result is a root result.
+     */
     final MVTempResult parent;
 
+    /**
+     * Count of child results.
+     */
     int childCount;
 
+    /**
+     * Whether this result is closed.
+     */
     boolean closed;
 
+    /**
+     * Temporary file deleter.
+     */
     private final TempFileDeleter tempFileDeleter;
+
+    /**
+     * Name of the temporary file.
+     */
     private final String fileName;
+
+    /**
+     * Reference to the record in the temporary file deleter.
+     */
     private final Reference<?> fileRef;
 
+    /**
+     * Creates a shallow copy of the result.
+     *
+     * @param parent
+     *                   parent result
+     */
     MVTempResult(MVTempResult parent) {
         this.parent = parent;
         this.store = parent.store;
@@ -66,6 +105,12 @@ public abstract class MVTempResult implements ResultExternal {
         this.fileRef = null;
     }
 
+    /**
+     * Creates a new temporary result.
+     *
+     * @param session
+     *                    database session
+     */
     MVTempResult(Session session) {
         try {
             fileName = FileUtils.createTempFile("h2tmp", Constants.SUFFIX_TEMP_FILE, false, true);