public class TtlDB extends RocksDB
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
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.
RocksDB.CountAndSize, RocksDB.LiveFiles, RocksDB.Version
DEFAULT_COLUMN_FAMILY, NOT_FOUND, options_
nativeHandle_
owningHandle_
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) . |
Modifier and Type | Method and Description |
---|---|
void |
close()
Close the TtlDB instance and release resource.
|
void |
closeE()
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 |
disposeInternal(long handle) |
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.
|
cancelAllBackgroundWork, compactFiles, compactFiles, compactRange, compactRange, compactRange, compactRange, compactRange, compactRange, compactRange, compactRange, compactRange, continueBackgroundWork, createColumnFamilies, createColumnFamilies, createColumnFamily, delete, delete, delete, delete, delete, delete, delete, delete, delete, delete, deleteFile, deleteFilesInRanges, deleteRange, deleteRange, deleteRange, deleteRange, destroyColumnFamilyHandle, destroyDB, disableFileDeletions, dropColumnFamilies, dropColumnFamily, enableAutoCompaction, enableFileDeletions, endTrace, flush, flush, flush, flushWal, get, get, get, get, get, get, get, get, get, get, get, get, get, get, get, get, get, get, getAggregatedLongProperty, getApproximateMemTableStats, getApproximateMemTableStats, getApproximateSizes, getApproximateSizes, getColumnFamilyMetaData, getColumnFamilyMetaData, getDBOptions, getDefaultColumnFamily, getEnv, getLatestSequenceNumber, getLiveFiles, getLiveFiles, getLiveFilesMetaData, getLongProperty, getLongProperty, getMapProperty, getMapProperty, getName, getOptions, getOptions, getPropertiesOfAllTables, getPropertiesOfAllTables, getPropertiesOfTablesInRange, getPropertiesOfTablesInRange, getProperty, getProperty, getSnapshot, getSortedWalFiles, getUpdatesSince, ingestExternalFile, ingestExternalFile, keyMayExist, keyMayExist, keyMayExist, keyMayExist, keyMayExist, keyMayExist, keyMayExist, keyMayExist, keyMayExist, keyMayExist, keyMayExist, keyMayExist, keyMayExist, keyMayExist, keyMayExist, keyMayExist, level0StopWriteTrigger, level0StopWriteTrigger, listColumnFamilies, loadLibrary, loadLibrary, maxMemCompactionLevel, maxMemCompactionLevel, merge, merge, merge, merge, merge, merge, merge, merge, multiGet, multiGet, multiGet, multiGet, multiGetAsList, multiGetAsList, multiGetAsList, multiGetAsList, multiGetByteBuffers, multiGetByteBuffers, multiGetByteBuffers, multiGetByteBuffers, newIterator, newIterator, newIterator, newIterator, newIterators, newIterators, numberLevels, numberLevels, open, open, open, openAsSecondary, openAsSecondary, openReadOnly, openReadOnly, openReadOnly, openReadOnly, openReadOnly, openReadOnly, pauseBackgroundWork, promoteL0, promoteL0, put, put, put, put, put, put, put, put, put, put, releaseSnapshot, remove, remove, remove, remove, resetStats, rocksdbVersion, setDBOptions, setOptions, setOptions, setPreserveDeletesSequenceNumber, singleDelete, singleDelete, singleDelete, singleDelete, startTrace, storeOptionsInstance, suggestCompactRange, suggestCompactRange, syncWal, tryCatchUpWithPrimary, verifyChecksum, write, write
disposeInternal, getNativeHandle
disOwnNativeHandle, isOwningHandle
dispose, finalize
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)
.
nativeHandle
- The native handle of the C++ TtlDB objectpublic 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.
options
- Options
instance.db_path
- path to database.RocksDBException
- thrown if an error occurs within the native
part of the library.public static TtlDB open(Options options, java.lang.String db_path, int ttl, boolean readOnly) throws RocksDBException
Opens a TtlDB.
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.RocksDBException
- thrown if an error occurs within the native
part of the library.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.
options
- Options
instance.db_path
- path to database.columnFamilyDescriptors
- list of column family descriptorscolumnFamilyHandles
- will be filled with ColumnFamilyHandle instances
on open.ttlValues
- time to live values per column family handlereadOnly
- boolean value indicating if database if db is
opened read-only.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.public void closeE() throws RocksDBException
Close the TtlDB instance and release resource.
This is similar toclose()
except that it
throws an exception if any error occurs.
This will not fsync the WAL files.
If syncing is required, the caller must first call RocksDB.syncWal()
or RocksDB.write(WriteOptions, WriteBatch)
using an empty write batch
with WriteOptions.setSync(boolean)
set to true.
See also close()
.closeE
in class RocksDB
RocksDBException
- if an error occurs whilst closing.public void close()
Close the TtlDB instance and release resource.
This will not fsync the WAL files. If syncing is required, the caller must first callRocksDB.syncWal()
or RocksDB.write(WriteOptions, WriteBatch)
using an empty write batch
with WriteOptions.setSync(boolean)
set to true.
See also close()
.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.
columnFamilyDescriptor
- column family to be created.ttl
- TTL to set for this column family.ColumnFamilyHandle
instance.RocksDBException
- thrown if error happens in underlying
native library.protected void disposeInternal(long handle)
disposeInternal
in class RocksDB