andreacavalli/rocksdb
0
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

JavaDoc improvements on RocksJava

Browse Source 
Added some more documentation improvements and readability
improvements.
This commit is contained in:
fyrz 2014-10-08 22:45:12 +02:00
parent 833357402c
commit 70294c9114
6 changed files with 107 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
java/org/rocksdb/CompactionStyle.java
View File

@ -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_;
}

13
java/org/rocksdb/CompressionType.java
View File

@ -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_;
}

54
java/org/rocksdb/RocksEnv.java
View File

@ -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.
* <p>A RocksEnv is an interface used by the rocksdb implementation to access
* operating system functionality like the filesystem etc.</p>
*
* All Env implementations are safe for concurrent access from
* multiple threads without any external synchronization.
* <p>All Env implementations are safe for concurrent access from
* 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
* system.
* <p>Returns the default environment suitable for the current operating
* system.</p>
*
* The result of getDefault() is a singleton whose ownership belongs
* to rocksdb c++. As a result, the returned RocksEnv will not
* <p>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.</p>
*/
public static RocksEnv getDefault() {
return default_env_;
}
/**
* Sets the number of background worker threads of the flush pool
* for this environment.
* default number: 1
* <p>Sets the number of background worker threads of the flush pool
* for this environment.</p>
* <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
* pool for this environment.
* <p>Sets the number of background worker threads of the specified thread
* 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
* thread pool.
* <p>Returns the length of the queue associated with the specified
* 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
* to construct a RocksEnv. Note that the ownership of the input handle
* <p>Package-private constructor that uses the specified native 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()
* 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.</p>
*/
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
* <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_;
}

49
java/org/rocksdb/RocksIterator.java
View File

@ -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
* true iff the iterator was not positioned at the last entry in the source.
* REQUIRES: Valid()
* <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.</p>
*
* <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
* true iff the iterator was not positioned at the first entry in source.
* REQUIRES: Valid()
* <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.</p>
*
* <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.
* REQUIRES: Valid()
* the iterator.</p>
*
* <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.
* REQUIRES: !AtEnd() && !AtStart()
* the iterator.</p>
*
* <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
* The iterator is Valid() after this call iff the source contains
* an entry that comes 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
* 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());

8
java/org/rocksdb/StatisticsCollector.java
View File

@ -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;

2
java/org/rocksdb/StatisticsCollectorCallback.java
View File

@ -14,8 +14,6 @@ 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 {
/**