From 70294c911412c4b8a6484c593b7f0974454d6c93 Mon Sep 17 00:00:00 2001 From: fyrz Date: Wed, 8 Oct 2014 22:45:12 +0200 Subject: [PATCH] JavaDoc improvements on RocksJava Added some more documentation improvements and readability improvements. --- java/org/rocksdb/CompactionStyle.java | 30 +++++++++++ java/org/rocksdb/CompressionType.java | 13 +++++ java/org/rocksdb/RocksEnv.java | 54 ++++++++++--------- java/org/rocksdb/RocksIterator.java | 51 ++++++++++-------- java/org/rocksdb/StatisticsCollector.java | 8 +-- .../rocksdb/StatisticsCollectorCallback.java | 4 +- 6 files changed, 107 insertions(+), 53 deletions(-) diff --git a/java/org/rocksdb/CompactionStyle.java b/java/org/rocksdb/CompactionStyle.java index ade48358e..76064395c 100644 --- a/java/org/rocksdb/CompactionStyle.java +++ b/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. + * + *
    + *
  1. LEVEL - Level based Compaction style
    2. + *
  2. UNIVERSAL - Universal Compaction Style is a + * compaction style, targeting the use cases requiring lower write + * amplification, trading off read amplification and space + * amplification.
    3. + *
  3. FIFO - 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.
    4. + *
+ * + * @see + * Universal Compaction + * @see + * FIFO Compaction + */ 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_; } diff --git a/java/org/rocksdb/CompressionType.java b/java/org/rocksdb/CompressionType.java index f29eccb9b..9c158ccf4 100644 --- a/java/org/rocksdb/CompressionType.java +++ b/java/org/rocksdb/CompressionType.java @@ -5,6 +5,14 @@ package org.rocksdb; +/** + * Enum CompressionType + * + *

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.

+ */ 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_; } diff --git a/java/org/rocksdb/RocksEnv.java b/java/org/rocksdb/RocksEnv.java index ce73ba654..21a4b2777 100644 --- a/java/org/rocksdb/RocksEnv.java +++ b/java/org/rocksdb/RocksEnv.java @@ -6,11 +6,11 @@ package org.rocksdb; /** - * A RocksEnv is an interface used by the rocksdb implementation to access - * operating system functionality like the filesystem etc. + *

A RocksEnv is an interface used by the rocksdb implementation to access + * operating system functionality like the filesystem etc.

* - * All Env implementations are safe for concurrent access from - * multiple threads without any external synchronization. + *

All Env implementations are safe for concurrent access from + * multiple threads without any external synchronization.

*/ 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 - * system. + *

Returns the default environment suitable for the current operating + * system.

* - * The result of getDefault() is a singleton whose ownership belongs - * to rocksdb c++. As a result, the returned RocksEnv will not + *

The result of {@see #getDefault()} is a singleton whose ownership + * 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.

*/ public static RocksEnv getDefault() { return default_env_; } /** - * Sets the number of background worker threads of the flush pool - * for this environment. - * default number: 1 + *

Sets the number of background worker threads of the flush pool + * for this environment.

+ *

Default number: 1

*/ public RocksEnv setBackgroundThreads(int num) { return setBackgroundThreads(num, FLUSH_POOL); } /** - * Sets the number of background worker threads of the specified thread - * pool for this environment. + *

Sets the number of background worker threads of the specified thread + * pool for this environment.

* * @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 + * + *

Default number: 1

*/ 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 - * thread pool. + *

Returns the length of the queue associated with the specified + * thread pool.

* * @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 - * to construct a RocksEnv. Note that the ownership of the input handle + *

Package-private constructor that uses the specified native handle + * to construct a RocksEnv.

+ * + *

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() - * of the created RocksEnv will be no-op. + * the ownership of the input handle. As a result, calling + * {@see #dispose()} of the created RocksEnv will be no-op.

*/ RocksEnv(long handle) { super(); @@ -85,8 +88,9 @@ public class RocksEnv extends RocksObject { } /** - * The helper function of dispose() which all subclasses of RocksObject - * must implement to release their associated C++ resource. + * The helper function of {@link #dispose()} which all subclasses of + * {@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 + *

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.

*/ static RocksEnv default_env_; } diff --git a/java/org/rocksdb/RocksIterator.java b/java/org/rocksdb/RocksIterator.java index 9ef2e8c24..2adff26cc 100644 --- a/java/org/rocksdb/RocksIterator.java +++ b/java/org/rocksdb/RocksIterator.java @@ -6,15 +6,17 @@ package org.rocksdb; /** - * An iterator yields a sequence of key/value pairs from a source. - * The following class defines the interface. Multiple implementations + *

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.

* - * Multiple threads can invoke const methods on an RocksIterator without + *

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.

+ * + * @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 - * true iff the iterator was not positioned at the last entry in the source. - * REQUIRES: Valid() + *

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.

+ * + *

REQUIRES: {@link #isValid()}

*/ 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 - * true iff the iterator was not positioned at the first entry in source. - * REQUIRES: Valid() + *

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.

+ * + *

REQUIRES: {@link #isValid()}

*/ 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 + *

Return the key for the current entry. The underlying storage for * the returned slice is valid only until the next modification of - * the iterator. - * REQUIRES: Valid() + * the iterator.

+ * + *

REQUIRES: {@link #isValid()}

+ * * @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 + *

Return the value for the current entry. The underlying storage for * the returned slice is valid only until the next modification of - * the iterator. - * REQUIRES: !AtEnd() && !AtStart() + * the iterator.

+ * + *

REQUIRES: !AtEnd() && !AtStart()

* @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 - * The iterator is Valid() after this call iff the source contains - * an entry that comes at or past target. + *

Position at the first key in the source that at or past target + * The iterator is valid after this call iff the source contains + * an entry that comes at or past target.

*/ 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()); diff --git a/java/org/rocksdb/StatisticsCollector.java b/java/org/rocksdb/StatisticsCollector.java index 965637697..524756a6c 100644 --- a/java/org/rocksdb/StatisticsCollector.java +++ b/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 + *

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.

* - * Caller should call start() to start statistics collection. Shutdown() should + *

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.

*/ public class StatisticsCollector { private final List _statsCollectorInputList; diff --git a/java/org/rocksdb/StatisticsCollectorCallback.java b/java/org/rocksdb/StatisticsCollectorCallback.java index b8d7a24ec..2ce92c5ee 100644 --- a/java/org/rocksdb/StatisticsCollectorCallback.java +++ b/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.