org.rocksdb

Class TtlDB

java.lang.Object

org.rocksdb.AbstractNativeReference

org.rocksdb.AbstractImmutableNativeReference

org.rocksdb.RocksObject

org.rocksdb.RocksDB

org.rocksdb.TtlDB

All Implemented Interfaces:

java.lang.AutoCloseable

public class TtlDB
extends RocksDB

Database with TTL support.

Use case

This API should be used to open the db when key-values inserted are meant to be removed from the db in a non-strict 'ttl' amount of time Therefore, this guarantees that key-values inserted will remain in the db for >= ttl amount of time and the db will make efforts to remove the key-values as soon as possible after ttl seconds of their insertion.

Behaviour

TTL is accepted in seconds (int32_t)Timestamp(creation) is suffixed to values in Put internally Expired TTL values deleted in compaction only:(Timestamp+ttl<time_now) Get/Iterator may return expired entries(compaction not run on them yet) Different TTL may be used during different Opens

Example

• Open1 at t=0 with ttl=4 and insert k1,k2, close at t=2
• Open2 at t=3 with ttl=5. Now k1,k2 should be deleted at t>=5

read_only=true opens in the usual read-only mode. Compactions will not be triggered(neither manual nor automatic), so no expired entries removed

Constraints

Not specifying/passing or non-positive TTL behaves like TTL = infinity

!!!WARNING!!!

Calling DB::Open directly to re-open a db created by this API will get corrupt values(timestamp suffixed) and no ttl effect will be there during the second Open, so use this API consistently to open the db Be careful when passing ttl with a small positive value because the whole database may be deleted in a small amount of time.

Field Summary

Fields inherited from class org.rocksdb.RocksDB

DEFAULT_COLUMN_FAMILY, NOT_FOUND, options_

Fields inherited from class org.rocksdb.RocksObject

nativeHandle_

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	TtlDB(long nativeHandle) A protected constructor that will be used in the static factory method open(Options, String, int, boolean) and open(DBOptions, String, java.util.List, java.util.List, java.util.List, boolean).

Method Summary

Modifier and Type	Method and Description
void	close() Close the TtlDB instance and release resource.
ColumnFamilyHandle	createColumnFamilyWithTtl(ColumnFamilyDescriptor columnFamilyDescriptor, int ttl) Creates a new ttl based column family with a name defined in given ColumnFamilyDescriptor and allocates a ColumnFamilyHandle within an internal structure.
protected void	finalize() Simply calls AbstractNativeReference.dispose() to free any underlying C++ object reference which has not yet been manually released.
static TtlDB	open(DBOptions options, java.lang.String db_path, java.util.List<ColumnFamilyDescriptor> columnFamilyDescriptors, java.util.List<ColumnFamilyHandle> columnFamilyHandles, java.util.List<java.lang.Integer> ttlValues, boolean readOnly) Opens a TtlDB.
static TtlDB	open(Options options, java.lang.String db_path) Opens a TtlDB.
static TtlDB	open(Options options, java.lang.String db_path, int ttl, boolean readOnly) Opens a TtlDB.

Methods inherited from class org.rocksdb.RocksDB

compactRange, compactRange, compactRange, compactRange, compactRange, compactRange, compactRange, compactRange, continueBackgroundWork, createColumnFamily, delete, delete, delete, delete, delete, delete, delete, delete, deleteRange, deleteRange, deleteRange, deleteRange, deleteRange, deleteRange, deleteRange, deleteRange, destroyDB, disableFileDeletions, disposeInternal, dropColumnFamily, enableFileDeletions, flush, flush, get, get, get, get, get, get, get, get, get, get, get, get, get, get, get, get, getDefaultColumnFamily, getLatestSequenceNumber, getLongProperty, getLongProperty, getLongProperty, getLongProperty, getProperty, getProperty, getProperty0, getProperty0, getSnapshot, getSnapshot, getUpdatesSince, ingestExternalFile, ingestExternalFile, iterator, iterator, iteratorCF, iteratorCF, iterators, keyMayExist, keyMayExist, keyMayExist, keyMayExist, keyMayExist, keyMayExist, keyMayExist, keyMayExist, listColumnFamilies, listColumnFamilies, loadLibrary, loadLibrary, merge, merge, merge, merge, merge, merge, merge, merge, multiGet, multiGet, multiGet, multiGet, multiGet, multiGet, multiGet, multiGet, newIterator, newIterator, newIterator, newIterator, newIterators, newIterators, open, open, open, open, open, openReadOnly, openReadOnly, openReadOnly, openReadOnly, openROnly, openROnly, pauseBackgroundWork, put, put, put, put, put, put, put, put, releaseSnapshot, releaseSnapshot, remove, remove, remove, remove, setOptions, singleDelete, singleDelete, singleDelete, singleDelete, singleDelete, singleDelete, singleDelete, singleDelete, write, write, write0, write1

Methods inherited from class org.rocksdb.RocksObject

disposeInternal

Methods inherited from class org.rocksdb.AbstractImmutableNativeReference

disOwnNativeHandle, isOwningHandle

Methods inherited from class org.rocksdb.AbstractNativeReference

dispose

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TtlDB

protected TtlDB(long nativeHandle)

A protected constructor that will be used in the static factory method open(Options, String, int, boolean) and open(DBOptions, String, java.util.List, java.util.List, java.util.List, boolean).

Parameters:

nativeHandle - The native handle of the C++ TtlDB object

Method Detail

open

public static TtlDB open(Options options,
                         java.lang.String db_path)
                  throws RocksDBException

Opens a TtlDB.

Database is opened in read-write mode without default TTL.

Parameters:

options - Options instance.

db_path - path to database.

Returns:

TtlDB instance.

Throws:

RocksDBException - thrown if an error occurs within the native part of the library.

open

public static TtlDB open(Options options,
                         java.lang.String db_path,
                         int ttl,
                         boolean readOnly)
                  throws RocksDBException

Opens a TtlDB.

Parameters:

options - Options instance.

db_path - path to database.

ttl - time to live for new entries.

readOnly - boolean value indicating if database if db is opened read-only.

Returns:

TtlDB instance.

Throws:

RocksDBException - thrown if an error occurs within the native part of the library.

open

public static TtlDB open(DBOptions options,
                         java.lang.String db_path,
                         java.util.List<ColumnFamilyDescriptor> columnFamilyDescriptors,
                         java.util.List<ColumnFamilyHandle> columnFamilyHandles,
                         java.util.List<java.lang.Integer> ttlValues,
                         boolean readOnly)
                  throws RocksDBException

Opens a TtlDB.

Parameters:

options - Options instance.

db_path - path to database.

columnFamilyDescriptors - list of column family descriptors

columnFamilyHandles - will be filled with ColumnFamilyHandle instances on open.

ttlValues - time to live values per column family handle

readOnly - boolean value indicating if database if db is opened read-only.

Returns:

TtlDB instance.

Throws:

RocksDBException - thrown if an error occurs within the native part of the library.

java.lang.IllegalArgumentException - when there is not a ttl value per given column family handle.

createColumnFamilyWithTtl

public ColumnFamilyHandle createColumnFamilyWithTtl(ColumnFamilyDescriptor columnFamilyDescriptor,
                                                    int ttl)
                                             throws RocksDBException

Creates a new ttl based column family with a name defined in given ColumnFamilyDescriptor and allocates a ColumnFamilyHandle within an internal structure.

The ColumnFamilyHandle is automatically disposed with DB disposal.

Parameters:

columnFamilyDescriptor - column family to be created.

ttl - TTL to set for this column family.

Returns:

ColumnFamilyHandle instance.

Throws:

RocksDBException - thrown if error happens in underlying native library.

close

public void close()

Close the TtlDB instance and release resource.

Internally, TtlDB owns the rocksdb::DB pointer to its associated RocksDB. The release of that RocksDB pointer is handled in the destructor of the c++ rocksdb::TtlDB and should be transparent to Java developers.

Specified by:

close in interface java.lang.AutoCloseable

Overrides:

close in class AbstractImmutableNativeReference

finalize

protected void finalize()
                 throws java.lang.Throwable

Description copied from class: AbstractNativeReference

Simply calls AbstractNativeReference.dispose() to free any underlying C++ object reference which has not yet been manually released.

Overrides:

finalize in class AbstractNativeReference

Throws:

java.lang.Throwable