org.iq80.leveldb

Interface DB

All Superinterfaces:

AutoCloseable, Closeable, Iterable<Map.Entry<byte[],byte[]>>

public interface DB
extends Iterable<Map.Entry<byte[],byte[]>>, Closeable

A DB is a persistent ordered map from keys to values. A DB is safe for concurrent access from multiple threads without any external synchronization.

Author:

Hiram Chirino

Method Summary

Modifier and Type	Method and Description
void	compactRange(byte[] begin, byte[] end) Compact the underlying storage for the key range [begin, end].
WriteBatch	createWriteBatch()
void	delete(byte[] key)
Snapshot	delete(byte[] key, WriteOptions options) Remove the database entry (if any) for "key".
byte[]	get(byte[] key) Same as calling get(byte[], ReadOptions) with default options
byte[]	get(byte[] key, ReadOptions options) If the database contains an entry for "key" return its corresponding value.
long[]	getApproximateSizes(Range... ranges) For each i in [0,n-1], store in "sizes[i]", the approximate file system space used by keys in "[range[i].start ..
String	getProperty(String name) DB implementations can export properties about their state via this method.
Snapshot	getSnapshot() Return a handle to the current DB state.
DBIterator	iterator() Same as calling iterator(ReadOptions) with default options
DBIterator	iterator(ReadOptions options) Return a iterator over the contents of the database.
void	put(byte[] key, byte[] value)
Snapshot	put(byte[] key, byte[] value, WriteOptions options) Set the database entry for "key" to "value".
void	resumeCompactions() Resumes the background compaction threads.
void	suspendCompactions() Suspends any background compaction threads.
void	write(WriteBatch updates)
Snapshot	write(WriteBatch updates, WriteOptions options) Apply the specified updates to the database.

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Methods inherited from interface java.io.Closeable

close

Method Detail

get

byte[] get(byte[] key)
    throws DBException

Same as calling get(byte[], ReadOptions) with default options

Throws:

DBException

get

byte[] get(byte[] key,
           ReadOptions options)
    throws DBException

If the database contains an entry for "key" return its corresponding value.

If there is no entry for "key" return null.

Parameters:

key - key to search for

options - read option

Returns:

key value or null

Throws:

DBException - if error occurred in accessing db sate

iterator

DBIterator iterator()

Same as calling iterator(ReadOptions) with default options

Specified by:

iterator in interface Iterable<Map.Entry<byte[],byte[]>>

iterator

DBIterator iterator(ReadOptions options)

Return a iterator over the contents of the database. The result of iterator(ReadOptions) will automatically position itsel to first entry if seek method is not called.

It is preferable to call one of the Seek methods on the iterator before using it.

Caller should call DBIterator.close() when it is no longer needed. The returned iterator should be closed before this db is deleted.

Parameters:

options - iterator read options

Returns:

new iterator content of the database

put

void put(byte[] key,
         byte[] value)
  throws DBException

Throws:

DBException

delete

void delete(byte[] key)
     throws DBException

Throws:

DBException

write

void write(WriteBatch updates)
    throws DBException

Throws:

DBException

createWriteBatch

WriteBatch createWriteBatch()

put

Snapshot put(byte[] key,
             byte[] value,
             WriteOptions options)
      throws DBException

Set the database entry for "key" to "value".

Note: consider setting options.sync = true.

Parameters:

key - entry key

value - entry valye

Returns:

null if options.isSnapshot()==false otherwise returns a snapshot of the DB after this operation.

Throws:

DBException - on any write failure

delete

Snapshot delete(byte[] key,
                WriteOptions options)
         throws DBException

Remove the database entry (if any) for "key".

Returns:

null if WriteOptions.snapshot()==false otherwise returns a snapshot of the DB after this operation.

Throws:

DBException - on any write failure. It is not an error if "key" did not exist in the database.

write

Snapshot write(WriteBatch updates,
               WriteOptions options)
        throws DBException

Apply the specified updates to the database.

Note: consider setting options.sync = true.

Returns:

null if WriteOptions.snapshot()==false otherwise returns a snapshot of the DB after this operation.

Throws:

DBException - on any write failure

getSnapshot

Snapshot getSnapshot()

Return a handle to the current DB state. Iterators created with this handle will all observe a stable snapshot of the current DB state. The caller must call Closeable.close() when the snapshot is no longer needed.

Returns:

current db state Snapshot handle

getApproximateSizes

long[] getApproximateSizes(Range... ranges)

For each i in [0,n-1], store in "sizes[i]", the approximate file system space used by keys in "[range[i].start .. range[i].limit)".

Note that the returned sizes measure file system space usage, so if the user data compresses by a factor of ten, the returned sizes will be one-tenth the size of the corresponding user data size.

The results may not include the sizes of recently written data.

Parameters:

ranges - each range to test for

Returns:

array with size result of each range

getProperty

String getProperty(String name)

DB implementations can export properties about their state via this method. If "property" is a valid property understood by this DB implementation, fills "*value" with its current value and returns true. Otherwise returns false.

Valid property names include:

• "leveldb.num-files-at-level" - return the number of files at level , where is an ASCII representation of a level number (e.g. "0").
• "leveldb.stats" - returns a multi-line string that describes statistics about the internal operation of the DB.
• "leveldb.sstables" - returns a multi-line string that describes all of the sstables that make up the db contents.
• "leveldb.approximate-memory-usage" - returns the approximate number of bytes of memory in use by the DB.

Parameters:

name - property name

Returns:

property value, null if property does not exist

suspendCompactions

void suspendCompactions()
                 throws InterruptedException

Suspends any background compaction threads. This methods returns once the background compactions are suspended.

Throws:

InterruptedException

resumeCompactions

void resumeCompactions()

Resumes the background compaction threads.

compactRange

void compactRange(byte[] begin,
                  byte[] end)
           throws DBException

Compact the underlying storage for the key range [begin, end]. In particular, deleted and overwritten versions are discarded, and the data is rearranged to reduce the cost of operations needed to access the data. This operation should typically only be invoked by users who understand the underlying implementation.

begin == null is treated as before all keys in the database. end == null is treated as a key after all keys in the database.

Therefore the call to db.compactRange(null, null); will compact the entire database.

Parameters:

begin - if null then compaction start from the first key

end - if null then compaction ends at the last key

Throws:

DBException