Cleanup and Fix JavaDoc issues in RocksJava

.github/workflows/pr-jobs.yml

@@ -514,6 +514,35 @@ jobs:
     - name: Build RocksDBJava Static Library
       run: scl enable devtoolset-7 'make V=1 J=8 -j8 rocksdbjavastatic'
     # NOTE: post-steps skipped because of compatibility issues with docker image
+  check-javadocs:
+    if: ${{ github.repository_owner == 'facebook' }}
+    runs-on:
+      labels: 4-core-ubuntu
+    container:
+      image: evolvedbinary/rocksjava:centos6_x64-be
+      options: --shm-size=16gb
+    steps:
+    # The docker image is based on such an old OS that it has a GLIBC
+    # incompatibility with actions/checkout and other actions. Thus we
+    # implement a manual checkout step.
+    - name: Checkout
+      env:
+        GH_TOKEN: ${{ github.token }}
+      run: |
+        chown `whoami` . || true
+        git clone --no-checkout https://oath2:[email protected]/${{ github.repository }}.git .
+        git -c protocol.version=2 fetch --update-head-ok --no-tags --prune --no-recurse-submodules --depth=1 origin +${{ github.sha }}:${{ github.ref }}
+        git checkout --progress --force ${{ github.ref }}
+        git log -1 --format='%H'
+    - uses: "./.github/actions/pre-steps"
+    - name: Set Java Environment
+      run: |-
+        echo "JAVA_HOME=${JAVA_HOME}"
+        which java && java -version
+        which javac && javac -version
+    - name: Check RocksDBJava JavaDocs
+      run: scl enable devtoolset-7 'pushd java; make V=1 J=8 -j8 javadocs'
+    # NOTE: post-steps skipped because of compatibility issues with docker image
   build-macos-java:
     if: ${{ github.repository_owner == 'facebook' }}
     runs-on: macos-13

include/rocksdb/utilities/table_properties_collectors.h

@@ -69,7 +69,7 @@ class CompactOnDeletionCollectorFactory
 };
 
 // Creates a factory of a table property collector that marks a SST
-// file as need-compaction when it observe at least "D" deletion
+// file as need-compaction when it observes at least "D" deletion
 // entries in any "N" consecutive entries, or the ratio of tombstone
 // entries >= deletion_ratio.
 //

java/Makefile

@@ -115,12 +115,11 @@ JAVA_TESTS = \
 	org.rocksdb.BuiltinComparatorTest\
 	org.rocksdb.ByteBufferUnsupportedOperationTest\
 	org.rocksdb.BytewiseComparatorRegressionTest\
-	org.rocksdb.util.BytewiseComparatorTest\
-	org.rocksdb.util.BytewiseComparatorIntTest\
 	org.rocksdb.CheckPointTest\
 	org.rocksdb.ClockCacheTest\
 	org.rocksdb.ColumnFamilyOptionsTest\
 	org.rocksdb.ColumnFamilyTest\
+	org.rocksdb.CompactRangeOptionsTest\
 	org.rocksdb.CompactionFilterFactoryTest\
 	org.rocksdb.CompactionJobInfoTest\
 	org.rocksdb.CompactionJobStatsTest\
@@ -132,32 +131,32 @@ JAVA_TESTS = \
 	org.rocksdb.ComparatorOptionsTest\
 	org.rocksdb.CompressionOptionsTest\
 	org.rocksdb.CompressionTypesTest\
+	org.rocksdb.ConcurrentTaskLimiterTest\
+	org.rocksdb.DefaultEnvTest\
 	org.rocksdb.DBOptionsTest\
 	org.rocksdb.DirectSliceTest\
-	org.rocksdb.util.EnvironmentTest\
 	org.rocksdb.EnvOptionsTest\
 	org.rocksdb.EventListenerTest\
-	org.rocksdb.IngestExternalFileOptionsTest\
-	org.rocksdb.util.IntComparatorTest\
-	org.rocksdb.util.JNIComparatorTest\
 	org.rocksdb.FilterTest\
+	org.rocksdb.FlushOptionsTest\
 	org.rocksdb.FlushTest\
+	org.rocksdb.HyperClockCacheTest\
 	org.rocksdb.ImportColumnFamilyTest\
 	org.rocksdb.InfoLogLevelTest\
+	org.rocksdb.IngestExternalFileOptionsTest\
 	org.rocksdb.KeyExistsTest \
 	org.rocksdb.KeyMayExistTest\
-	org.rocksdb.ConcurrentTaskLimiterTest\
 	org.rocksdb.LoggerTest\
 	org.rocksdb.LRUCacheTest\
 	org.rocksdb.MemoryUtilTest\
 	org.rocksdb.MemTableTest\
 	org.rocksdb.MergeCFVariantsTest\
 	org.rocksdb.MergeTest\
 	org.rocksdb.MergeVariantsTest\
-	org.rocksdb.MultiColumnRegressionTest \
+	org.rocksdb.MixedOptionsTest\
+	org.rocksdb.MultiColumnRegressionTest\
 	org.rocksdb.MultiGetManyKeysTest\
 	org.rocksdb.MultiGetTest\
-	org.rocksdb.MixedOptionsTest\
 	org.rocksdb.MutableColumnFamilyOptionsTest\
 	org.rocksdb.MutableDBOptionsTest\
 	org.rocksdb.MutableOptionsGetSetTest \
@@ -166,48 +165,53 @@ JAVA_TESTS = \
 	org.rocksdb.OptimisticTransactionTest\
 	org.rocksdb.OptimisticTransactionDBTest\
 	org.rocksdb.OptimisticTransactionOptionsTest\
-	org.rocksdb.OptionsUtilTest\
 	org.rocksdb.OptionsTest\
-	org.rocksdb.PerfLevelTest \
+	org.rocksdb.OptionsUtilTest\
 	org.rocksdb.PerfContextTest \
+	org.rocksdb.PerfLevelTest \
+	org.rocksdb.PlainTableConfigTest\
 	org.rocksdb.PutCFVariantsTest\
+	org.rocksdb.PutMultiplePartsTest\
 	org.rocksdb.PutVariantsTest\
-	org.rocksdb.PlainTableConfigTest\
 	org.rocksdb.RateLimiterTest\
 	org.rocksdb.ReadOnlyTest\
 	org.rocksdb.ReadOptionsTest\
-	org.rocksdb.util.ReverseBytewiseComparatorIntTest\
-	org.rocksdb.RocksDBTest\
 	org.rocksdb.RocksDBExceptionTest\
-	org.rocksdb.DefaultEnvTest\
+	org.rocksdb.RocksDBTest\
 	org.rocksdb.RocksIteratorTest\
 	org.rocksdb.RocksMemEnvTest\
-	org.rocksdb.util.SizeUnitTest\
 	org.rocksdb.SecondaryDBTest\
 	org.rocksdb.SliceTest\
 	org.rocksdb.SnapshotTest\
 	org.rocksdb.SstFileManagerTest\
-	org.rocksdb.SstFileWriterTest\
 	org.rocksdb.SstFileReaderTest\
+	org.rocksdb.SstFileWriterTest\
 	org.rocksdb.SstPartitionerTest\
+	org.rocksdb.StatisticsCollectorTest\
+	org.rocksdb.StatisticsTest\
 	org.rocksdb.TableFilterTest\
 	org.rocksdb.TimedEnvTest\
-	org.rocksdb.TransactionTest\
-	org.rocksdb.TransactionDBTest\
-	org.rocksdb.TransactionOptionsTest\
 	org.rocksdb.TransactionDBOptionsTest\
+	org.rocksdb.TransactionDBTest\
 	org.rocksdb.TransactionLogIteratorTest\
+	org.rocksdb.TransactionOptionsTest\
+	org.rocksdb.TransactionTest\
 	org.rocksdb.TtlDBTest\
-	org.rocksdb.StatisticsTest\
-	org.rocksdb.StatisticsCollectorTest\
 	org.rocksdb.VerifyChecksumsTest\
 	org.rocksdb.WalFilterTest\
 	org.rocksdb.WALRecoveryModeTest\
 	org.rocksdb.WriteBatchHandlerTest\
 	org.rocksdb.WriteBatchTest\
 	org.rocksdb.WriteBatchThreadedTest\
-	org.rocksdb.WriteOptionsTest\
 	org.rocksdb.WriteBatchWithIndexTest\
+	org.rocksdb.WriteOptionsTest\
+	org.rocksdb.util.BytewiseComparatorIntTest\
+	org.rocksdb.util.BytewiseComparatorTest\
+	org.rocksdb.util.EnvironmentTest\
+	org.rocksdb.util.IntComparatorTest\
+	org.rocksdb.util.JNIComparatorTest\
+	org.rocksdb.util.ReverseBytewiseComparatorIntTest\
+	org.rocksdb.util.SizeUnitTest\
 	org.rocksdb.util.StdErrLoggerTest
 
 MAIN_SRC = src/main/java
@@ -343,7 +347,7 @@ clean-downloaded:
 
 javadocs: java
 	$(AM_V_GEN)mkdir -p $(JAVADOC)
-	$(AM_V_at)$(JAVADOC_CMD) -d $(JAVADOC) -sourcepath $(MAIN_SRC) -subpackages org
+	$(AM_V_at)$(JAVADOC_CMD) -Xwerror -d $(JAVADOC) -sourcepath $(MAIN_SRC) -subpackages org
 
 javalib: java java_test javadocs
 

java/src/main/java/org/rocksdb/AbstractCompactionFilter.java

@@ -10,14 +10,24 @@
  * <p>
  * At present, we just permit an overriding Java class to wrap a C++
  * implementation
+ *
+ * @param <T> the concrete type of the {@link AbstractSlice} that the Compaction Filter uses.
  */
 public abstract class AbstractCompactionFilter<T extends AbstractSlice<?>>
     extends RocksObject {
-
+  /**
+   * Context of the Compaction Filter.
+   */
   public static class Context {
     private final boolean fullCompaction;
     private final boolean manualCompaction;
 
+    /**
+     * Context constructor.
+     *
+     * @param fullCompaction true to filter full compaction, false otherwise.
+     * @param manualCompaction true to filter manual compaction, false otherwise.
+     */
     public Context(final boolean fullCompaction, final boolean manualCompaction) {
       this.fullCompaction = fullCompaction;
       this.manualCompaction = manualCompaction;
@@ -43,6 +53,13 @@ public boolean isManualCompaction() {
     }
   }
 
+  /**
+   * Constructor to be called by subclasses to set the
+   * handle to the underlying C++ object.
+   *
+   * @param nativeHandle reference to the value of the C++ pointer pointing to the underlying native
+   *     RocksDB C++ Compaction Filter.
+   */
   protected AbstractCompactionFilter(final long nativeHandle) {
     super(nativeHandle);
   }

java/src/main/java/org/rocksdb/AbstractCompactionFilterFactory.java

@@ -13,7 +13,9 @@
  */
 public abstract class AbstractCompactionFilterFactory<T extends AbstractCompactionFilter<?>>
     extends RocksCallbackObject {
-
+  /**
+   * Constructs a new Compaction Filter Factory which has no underlying C++ object.
+   */
   public AbstractCompactionFilterFactory() {
     super(0L);
   }
@@ -26,8 +28,8 @@ protected long initializeNative(final long... nativeParameterHandles) {
   /**
    * Called from JNI, see compaction_filter_factory_jnicallback.cc
    *
-   * @param fullCompaction {@link AbstractCompactionFilter.Context#fullCompaction}
-   * @param manualCompaction {@link AbstractCompactionFilter.Context#manualCompaction}
+   * @param fullCompaction {@link AbstractCompactionFilter.Context#isFullCompaction()}
+   * @param manualCompaction {@link AbstractCompactionFilter.Context#isManualCompaction()}
    *
    * @return native handle of the CompactionFilter
    */

java/src/main/java/org/rocksdb/AbstractComparator.java

@@ -10,7 +10,7 @@
 /**
  * Comparators are used by RocksDB to determine
  * the ordering of keys.
- *
+ * <p>
  * Implementations of Comparators in Java should extend this class.
  */
 public abstract class AbstractComparator
@@ -20,6 +20,11 @@ public abstract class AbstractComparator
     super();
   }
 
+  /**
+   * Construct an AbstractComparator.
+   *
+   * @param comparatorOptions options for the comparator.
+   */
   protected AbstractComparator(final ComparatorOptions comparatorOptions) {
     super(comparatorOptions.nativeHandle_);
   }
@@ -59,7 +64,7 @@ ComparatorType getComparatorType() {
    * Three-way key comparison. Implementations should provide a
    * <a href="https://en.wikipedia.org/wiki/Total_order">total order</a>
    * on keys that might be passed to it.
-   *
+   * <p>
    * The implementation may modify the {@code ByteBuffer}s passed in, though
    * it would be unconventional to modify the "limit" or any of the
    * underlying bytes. As a callback, RocksJava will ensure that {@code a}
@@ -114,6 +119,11 @@ public void findShortSuccessor(final ByteBuffer key) {
     // no-op
   }
 
+  /**
+   * Returns true if we are using direct byte buffers.
+   *
+   * @return true if we are using direct byte buffers, false otherwise.
+   */
   public final boolean usingDirectBuffers() {
     return usingDirectBuffers(nativeHandle_);
   }

java/src/main/java/org/rocksdb/AbstractComparatorJniBridge.java

@@ -12,7 +12,7 @@
  * it holds methods which are called
  * from C++ to interact with a Comparator
  * written in Java.
- *
+ * <p>
  * Placing these bridge methods in this
  * class keeps the API of the
  * {@link org.rocksdb.AbstractComparator} clean.