Merge pull request #344 from fyrz/java-doc-enhancements

JavaDoc improvements on RocksJava

java/org/rocksdb/CompactionStyle.java

@@ -5,6 +5,31 @@
 
 package org.rocksdb;
 
+/**
+ * Enum CompactionStyle
+ *
+ * RocksDB supports different styles of compaction. Available
+ * compaction styles can be chosen using this enumeration.
+ *
+ * <ol>
+ *   <li><strong>LEVEL</strong> - Level based Compaction style</li>
+ *   <li><strong>UNIVERSAL</strong> - Universal Compaction Style is a
+ *   compaction style, targeting the use cases requiring lower write
+ *   amplification, trading off read amplification and space
+ *   amplification.</li>
+ *   <li><strong>FIFO</strong> - FIFO compaction style is the simplest
+ *   compaction strategy. It is suited for keeping event log data with
+ *   very low overhead (query log for example). It periodically deletes
+ *   the old data, so it's basically a TTL compaction style.</li>
+ * </ol>
+ *
+ * @see <a
+ * href="https://github.com/facebook/rocksdb/wiki/Universal-Compaction">
+ * Universal Compaction</a>
+ * @see <a
+ * href="https://github.com/facebook/rocksdb/wiki/FIFO-compaction-style">
+ * FIFO Compaction</a>
+ */
 public enum CompactionStyle {
   LEVEL((byte) 0),
   UNIVERSAL((byte) 1),
@@ -16,6 +41,11 @@ public enum CompactionStyle {
     value_ = value;
   }
 
+  /**
+   * Returns the byte value of the enumerations value
+   *
+   * @return byte representation
+   */
   public byte getValue() {
     return value_;
   }

java/org/rocksdb/CompressionType.java

@@ -5,6 +5,14 @@
 
 package org.rocksdb;
 
+/**
+ * Enum CompressionType
+ *
+ * <p>DB contents are stored in a set of blocks, each of which holds a
+ * sequence of key,value pairs. Each block may be compressed before
+ * being stored in a file. The following enum describes which
+ * compression method (if any) is used to compress a block.</p>
+ */
 public enum CompressionType {
   NO_COMPRESSION((byte) 0),
   SNAPPY_COMPRESSION((byte) 1),
@@ -19,6 +27,11 @@ public enum CompressionType {
     value_ = value;
   }
 
+  /**
+   * Returns the byte value of the enumerations value
+   *
+   * @return byte representation
+   */
   public byte getValue() {
     return value_;
   }

java/org/rocksdb/RocksEnv.java

@@ -6,11 +6,11 @@
 package org.rocksdb;
 
 /**
- * A RocksEnv is an interface used by the rocksdb implementation to access
+ * <p>A RocksEnv is an interface used by the rocksdb implementation to access
- * operating system functionality like the filesystem etc.
+ * operating system functionality like the filesystem etc.</p>
  *
- * All Env implementations are safe for concurrent access from
+ * <p>All Env implementations are safe for concurrent access from
- * multiple threads without any external synchronization.
+ * multiple threads without any external synchronization.</p>
  */
 public class RocksEnv extends RocksObject {
   public static final int FLUSH_POOL = 0;
@@ -22,35 +22,36 @@ public class RocksEnv extends RocksObject {
   private static native long getDefaultEnvInternal();
 
   /**
-   * Returns the default environment suitable for the current operating
+   * <p>Returns the default environment suitable for the current operating
-   * system.
+   * system.</p>
    *
-   * The result of getDefault() is a singleton whose ownership belongs
+   * <p>The result of {@code getDefault()} is a singleton whose ownership
-   * to rocksdb c++.  As a result, the returned RocksEnv will not
+   * belongs to rocksdb c++.  As a result, the returned RocksEnv will not
    * have the ownership of its c++ resource, and calling its dispose()
-   * will be no-op.
+   * will be no-op.</p>
    */
   public static RocksEnv getDefault() {
     return default_env_;
   }
 
   /**
-   * Sets the number of background worker threads of the flush pool
+   * <p>Sets the number of background worker threads of the flush pool
-   * for this environment.
+   * for this environment.</p>
-   * default number: 1
+   * <p>Default number: 1</p>
    */
   public RocksEnv setBackgroundThreads(int num) {
     return setBackgroundThreads(num, FLUSH_POOL);
   }
 
   /**
-   * Sets the number of background worker threads of the specified thread
+   * <p>Sets the number of background worker threads of the specified thread
-   * pool for this environment.
+   * pool for this environment.</p>
    *
    * @param num the number of threads
    * @param poolID the id to specified a thread pool.  Should be either
    *     FLUSH_POOL or COMPACTION_POOL.
-   * Default number: 1
+   *
+   * <p>Default number: 1</p>
    */
   public RocksEnv setBackgroundThreads(int num, int poolID) {
     setBackgroundThreads(nativeHandle_, num, poolID);
@@ -60,8 +61,8 @@ public class RocksEnv extends RocksObject {
       long handle, int num, int priority);
 
   /**
-   * Returns the length of the queue associated with the specified
+   * <p>Returns the length of the queue associated with the specified
-   * thread pool.
+   * thread pool.</p>
    *
    * @param poolID the id to specified a thread pool.  Should be either
    *     FLUSH_POOL or COMPACTION_POOL.
@@ -72,11 +73,13 @@ public class RocksEnv extends RocksObject {
   private native int getThreadPoolQueueLen(long handle, int poolID);
 
   /**
-   * Package-private constructor that uses the specified native handle
+   * <p>Package-private constructor that uses the specified native handle
-   * to construct a RocksEnv.  Note that the ownership of the input handle
+   * to construct a RocksEnv.</p>
+   *
+   * <p>Note that the ownership of the input handle
    * belongs to the caller, and the newly created RocksEnv will not take
-   * the ownership of the input handle.  As a result, calling dispose()
+   * the ownership of the input handle.  As a result, calling
-   * of the created RocksEnv will be no-op.
+   * {@code dispose()} of the created RocksEnv will be no-op.</p>
    */
   RocksEnv(long handle) {
     super();
@@ -85,8 +88,9 @@ public class RocksEnv extends RocksObject {
   }
 
   /**
-   * The helper function of dispose() which all subclasses of RocksObject
+   * The helper function of {@link #dispose()} which all subclasses of
-   * must implement to release their associated C++ resource.
+   * {@link RocksObject} must implement to release their associated C++
+   * resource.
    */
   protected void disposeInternal() {
     disposeInternal(nativeHandle_);
@@ -94,9 +98,9 @@ public class RocksEnv extends RocksObject {
   private native void disposeInternal(long handle);
 
   /**
-   * The static default RocksEnv.  The ownership of its native handle
+   * <p>The static default RocksEnv. The ownership of its native handle
    * belongs to rocksdb c++ and is not able to be released on the Java
-   * side.
+   * side.</p>
    */
   static RocksEnv default_env_;
 }

java/org/rocksdb/RocksIterator.java

@@ -6,15 +6,17 @@
 package org.rocksdb;
 
 /**
- * An iterator yields a sequence of key/value pairs from a source.
+ * <p>An iterator yields a sequence of key/value pairs from a source.
  * The following class defines the interface. Multiple implementations
  * are provided by this library.  In particular, iterators are provided
- * to access the contents of a Table or a DB.
+ * to access the contents of a Table or a DB.</p>
  *
- * Multiple threads can invoke const methods on an RocksIterator without
+ * <p>Multiple threads can invoke const methods on an RocksIterator without
  * external synchronization, but if any of the threads may call a
  * non-const method, all threads accessing the same RocksIterator must use
- * external synchronization.
+ * external synchronization.</p>
+ *
+ * @see org.rocksdb.RocksObject
  */
 public class RocksIterator extends RocksObject {
   public RocksIterator(long nativeHandle) {
@@ -25,6 +27,7 @@ public class RocksIterator extends RocksObject {
   /**
    * An iterator is either positioned at a key/value pair, or
    * not valid.  This method returns true iff the iterator is valid.
+   *
    * @return true if iterator is valid.
    */
   public boolean isValid() {
@@ -43,7 +46,7 @@ public class RocksIterator extends RocksObject {
 
   /**
    * Position at the last key in the source.  The iterator is
-   * Valid() after this call iff the source is not empty.
+   * valid after this call iff the source is not empty.
    */
   public void seekToLast() {
     assert(isInitialized());
@@ -51,9 +54,10 @@ public class RocksIterator extends RocksObject {
   }
 
   /**
-   * Moves to the next entry in the source.  After this call, Valid() is
+   * <p>Moves to the next entry in the source.  After this call, Valid() is
-   * true iff the iterator was not positioned at the last entry in the source.
+   * true iff the iterator was not positioned at the last entry in the source.</p>
-   * REQUIRES: Valid()
+   *
+   * <p>REQUIRES: {@link #isValid()}<p>
    */
   public void next() {
     assert(isInitialized());
@@ -61,9 +65,10 @@ public class RocksIterator extends RocksObject {
   }
 
   /**
-   * Moves to the previous entry in the source.  After this call, Valid() is
+   * <p>Moves to the previous entry in the source.  After this call, Valid() is
-   * true iff the iterator was not positioned at the first entry in source.
+   * true iff the iterator was not positioned at the first entry in source.</p>
-   * REQUIRES: Valid()
+   *
+   * <p>REQUIRES: {@link #isValid()}<p>
    */
   public void prev() {
     assert(isInitialized());
@@ -71,10 +76,12 @@ public class RocksIterator extends RocksObject {
   }
 
   /**
-   * Return the key for the current entry.  The underlying storage for
+   * <p>Return the key for the current entry.  The underlying storage for
    * the returned slice is valid only until the next modification of
-   * the iterator.
+   * the iterator.</p>
-   * REQUIRES: Valid()
+   *
+   * <p>REQUIRES: {@link #isValid()}<p>
+   *
    * @return key for the current entry.
    */
   public byte[] key() {
@@ -83,10 +90,11 @@ public class RocksIterator extends RocksObject {
   }
 
   /**
-   * Return the value for the current entry.  The underlying storage for
+   * <p>Return the value for the current entry.  The underlying storage for
    * the returned slice is valid only until the next modification of
-   * the iterator.
+   * the iterator.</p>
-   * REQUIRES: !AtEnd() && !AtStart()
+   *
+   * <p>REQUIRES: !AtEnd() && !AtStart()</p>
    * @return value for the current entry.
    */
   public byte[] value() {
@@ -95,9 +103,9 @@ public class RocksIterator extends RocksObject {
   }
 
   /**
-   * Position at the first key in the source that at or past target
+   * <p>Position at the first key in the source that at or past target
-   * The iterator is Valid() after this call iff the source contains
+   * The iterator is valid after this call iff the source contains
-   * an entry that comes at or past target.
+   * an entry that comes at or past target.</p>
    */
   public void seek(byte[] target) {
     assert(isInitialized());
@@ -109,6 +117,7 @@ public class RocksIterator extends RocksObject {
    * If non-blocking IO is requested and this operation cannot be
    * satisfied without doing some IO, then this returns Status::Incomplete().
    *
+   * @throws org.rocksdb.RocksDBException
    */
   public void status() throws RocksDBException {
     assert(isInitialized());

java/org/rocksdb/StatisticsCollector.java

@@ -13,13 +13,13 @@ import java.util.concurrent.TimeUnit;
 import java.util.concurrent.atomic.AtomicBoolean;
 
 /**
- * Helper class to collect DB statistics periodically at a period specified in
+ * <p>Helper class to collect DB statistics periodically at a period specified in
  * constructor. Callback function (provided in constructor) is called with
- * every statistics collection.
+ * every statistics collection.</p>
  *
- * Caller should call start() to start statistics collection. Shutdown() should
+ * <p>Caller should call start() to start statistics collection. Shutdown() should
  * be called to stop stats collection and should be called before statistics (
- * provided in constructor) reference has been disposed.
+ * provided in constructor) reference has been disposed.</p>
  */
 public class StatisticsCollector {
   private final List<StatsCollectorInput> _statsCollectorInputList;

java/org/rocksdb/StatisticsCollectorCallback.java

@@ -14,9 +14,7 @@ package org.rocksdb;
  * StatisticsCollector references, then its the responsibility of the
  * user to make StatisticsCollectorCallback's implementation thread-safe.
  *
- * @param tickerType
+ */
- * @param tickerCount
-*/
 public interface StatisticsCollectorCallback {
   /**
    * Callback function to get ticker values.