com.neocoretechs.rocksack.session

Class DatabaseManager

java.lang.Object

com.neocoretechs.rocksack.session.DatabaseManager

public final class DatabaseManager
extends java.lang.Object

This factory class enforces a strong typing for the RockSack using the database naming convention linked to the class name of the class stored there.

In almost all cases, this is the main entry point to obtain a BufferedMap or a TransactionalMap.

The DatabaseManager coordinates the VolumeManager the SessionManager and the TransactionManager.

To override options call setDatabaseOptions(Options). If options are not set in this manner the default options will be used.

The main function of this adapter is to ensure that the appropriate map is instantiated.
A map can be obtained by instance of Comparable to impart ordering.
A Buffered map has atomic transactions bounded automatically with each insert/delete.
A transactional map requires commit/rollback and can be checkpointed.
An optimistic transactional map requires commit/rollback, can be snapshotted, and uses optimistic concurrency control, acquiring no locks and checking for conflicts during commit.
The database name is the full path of the top level tablespace and log directory, i.e. /home/db/test would create a 'test' database in the /home/db directory consisting of a series of RocksDB files with the database name appended to the class contained in each 'instance'. For example; if we were to store a series of String instances, the database tablespace name would translate to: /home/db/testjava.lang.String. Upon encountering each new class type a new set of 'instances' for the particular database tablespace would be created. The class name is translated into the appropriate file name via a simple translation table to give us a database/class tablespace identifier for each file used. BufferedMap returns one instance of the class for each call to get the map. Transactional maps create a new instance with a new transaction context using the originally opened database, and so must be maintained in another context for each transaction.

Full control over placement of instances can be achieved with the DatabaseClass annotation on a class to be stored in the RockSack. This annotation controls storage in a particular tablespace, and column. RocksDB uses the 'ColumnFamily' concept to represent 'columns' or collections of data than can be grouped together under a common set of attributes defined in the options upon opening.

It is analogous to separate databases stored under a unified set of files and directories. It can be considered separate columns or tablespaces or other logical divisions in other systems. Here, we can store different class instances such as subclasses.

As described above, the database is stored under the tablespace directory which has the database name concatenated with the class name and is used to obtain the Map. This tablespace directory will then contain the RocksDB files and logs etc.

Using one of the methods in the class below, such as 'getMap', and transparent to the user, DatabaseClass annotation then controls whether instances are stored in a different tablespace and internal column of that tablespace.

Looking at the example in BatteryKVDerived we see that if we want to store subclass instances with a superclass, we have just the 'column' attribute with the fully qualified name of the superclass. This will ensure that sets retrieved include both subclasses and superclasses. If we want to store the subclass in a different column within the same tablespace, we could have a different column name or omit the column attribute, which would then store the instances under the derived class name in the tablespace of the direct superclass. So, omitting both tablespace and column attributes stores the instances in the direct superclass under the column name of the subclass. So using this construct, annotations and combinations of the attributes gives the user full control over placement of the instances.

Author:

Jonathan Groff Copyright (C) NeoCoreTechs 2014,2015,2021,2022,2024

Method Summary

Modifier and Type	Method and Description
static void	associateSession(TransactionId xid, TransactionalMap tm) TransactionalMap contains a Session or its subclasses TransactionSession or TransactionSessionAlias.
static void	checkpointTransaction(Alias alias, TransactionId xid)
static void	checkpointTransaction(TransactionId xid)
static void	clearAllOutstandingTransactions()
static void	clearOutstandingTransaction(TransactionId xid)
static void	commitTransaction(Alias alias, TransactionId xid)
static void	commitTransaction(TransactionId xid)
static void	endTransaction(TransactionId xid)
static java.lang.String[][]	getAliases()
static java.lang.String	getAliasToPath(Alias alias) Get the tablespace path for the given alias VolumeManager
static java.lang.String	getDatabaseName(java.lang.Class clazz) Get the fully qualified database name using default tablespace and translated class name
static java.lang.String	getDatabaseName(java.lang.String clazz) Get the fully qualified database name using string version of class and default tablespace.
static org.rocksdb.ColumnFamilyOptions	getDefaultColumnFamilyOptions() Get the default ColumnFamily options using default options.
static org.rocksdb.DBOptions	getDefaultDBOptions() Get the default options using default options.
static org.rocksdb.Options	getDefaultOptions(org.rocksdb.AbstractComparator comparator) Get the default options using a different comparator, primarily to provide hooks inside compare method.
static DatabaseManager	getInstance()
static BufferedMap	getMap(Alias alias, java.lang.Class clazz) Get a Map via Java Class type.
static BufferedMap	getMap(Alias alias, java.lang.Comparable clazz) Get a Map via Comparable instance.
static BufferedMap	getMap(java.lang.Class clazz) Get a Map via Java Class type.
static BufferedMap	getMap(java.lang.Comparable clazz) Get a Map via Comparable instance.
static TransactionalMap	getOptimisticTransactionalMap(Alias alias, java.lang.Class clazz, TransactionId xid)
static TransactionalMap	getOptimisticTransactionalMap(Alias alias, java.lang.Comparable clazz, TransactionId xid) Start a new transaction for the given class in the aliased database
static TransactionalMap	getOptimisticTransactionalMap(java.lang.Class clazz, TransactionId xid) Start a new optimistic transaction for the given class in the current database
static TransactionalMap	getOptimisticTransactionalMap(java.lang.Comparable clazz, TransactionId xid) Start a new optimistic transaction for the given class in the current database
static java.util.List<org.rocksdb.Transaction>	getOutstandingTransactionsByAliasAndId(Alias alias, TransactionId uid)
static java.util.List<org.rocksdb.Transaction>	getOutstandingTransactionsByPathAndId(java.lang.String path, TransactionId uid)
static java.util.List<java.lang.String>	getOutstandingTransactionState() Return a list of the state of all transactions with id's mapped to transactions in the set of active volumes.
static java.lang.String	getTableSpaceDir() Get the default tablespace set by explicit previous call.
static java.lang.String	getTableSpaceDir(Alias alias) Get the tablespace by given alias
static TransactionalMap	getTransactionalMap(Alias alias, java.lang.Class clazz, TransactionId xid)
static TransactionalMap	getTransactionalMap(Alias alias, java.lang.Comparable clazz, TransactionId xid) Start a new transaction for the given class in the aliased database
static TransactionalMap	getTransactionalMap(java.lang.Class clazz, TransactionId xid) Start a new transaction for the given class in the current database
static TransactionalMap	getTransactionalMap(java.lang.Comparable clazz, TransactionId xid) Start a new transaction for the given class in the current database
static TransactionId	getTransactionId() Generate a transaction with random UUID
static TransactionId	getTransactionId(long timeout) Generate a transaction with random UUID
static boolean	isSessionAssociated(TransactionId xid, TransactionalMap tm) TransactionalMap contains a Session or its subclasses TransactionSession or TransactionSessionAlias.
static void	main(java.lang.String[] args)
static void	remove(java.lang.String path) Remove the given tablespace path.
static void	removeAlias(Alias alias) Remove the given alias.
static void	removeMap(Alias alias, SetInterface tmap) Remove the given Map from active DB/transaction collection
static void	removeMap(SetInterface tmap) Remove the given Map from active DB/transaction collection
static void	removeTransaction(Alias alias, TransactionId xid) Remove from classToIso then idToTransaction in VolumeManager
static void	removeTransaction(TransactionId xid) Remove from classToIso then idToTransaction in VolumeManager
static void	removeTransactionalMap(Alias alias, TransactionId xid) Remove the given TransactionalMap from active DB/transaction collection
static void	removeTransactionalMap(Alias alias, TransactionSetInterface tmap) Remove the given TransactionalMap from active DB/transaction collection
static void	removeTransactionalMap(SetInterface tmap) Remove the given TransactionalMap from active DB/transaction collection
static void	removeTransactionalMap(TransactionId xid, TransactionSetInterface tmap) Remove the given TransactionalMap from active DB/transaction collection
static void	rollbackToCheckpoint(Alias alias, TransactionId xid)
static void	rollbackToCheckpoint(TransactionId xid)
static void	rollbackTransaction(Alias alias, TransactionId xid)
static void	rollbackTransaction(TransactionId xid)
static void	setDatabaseOptions(org.rocksdb.Options dboptions) Set the RocksDB options for all subsequent databases
static void	setTableSpaceDir(Alias alias, java.lang.String path) Set the tablespace for a given alias
static void	setTableSpaceDir(java.lang.String path) Set the default tablespace for operations not using alias
static java.lang.String	translateClass(java.lang.String clazz) Translate a class name into a legitimate file name with some aesthetics.

Methods inherited from class java.lang.Object

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

Method Detail

getInstance

public static DatabaseManager getInstance()

getTableSpaceDir

public static java.lang.String getTableSpaceDir(Alias alias)

Get the tablespace by given alias

Parameters:

alias -

Returns:

The path for this alias or null if none

getTableSpaceDir

public static java.lang.String getTableSpaceDir()

Get the default tablespace set by explicit previous call.

Returns:

getAliases

public static java.lang.String[][] getAliases()

Returns:

The aliases and paths as 2d array, if none first dimension is zero.

setTableSpaceDir

public static void setTableSpaceDir(Alias alias,
                                    java.lang.String path)
                             throws java.io.IOException

Set the tablespace for a given alias

Parameters:

alias - the alias name, which will be appended to tablespace path to create a database name, that class names will be then appended to.

path - Tablespace path

Throws:

java.io.IOException

setTableSpaceDir

public static void setTableSpaceDir(java.lang.String path)
                             throws java.io.IOException

Set the default tablespace for operations not using alias

Parameters:

path - The path of the tablespace; which is a directory appended with a database name, which will then have class names appended. Such as /home/dir/data with database name being data.

Throws:

java.io.IOException

removeAlias

public static void removeAlias(Alias alias)

Remove the given alias. Affects only the alias reference, nothing else.

Parameters:

alias -

remove

public static void remove(java.lang.String path)

Remove the given tablespace path.

Parameters:

path - The tablespace path, which is a directory with appended database name such as /home/dir/data with database name being data

getDatabaseName

public static java.lang.String getDatabaseName(java.lang.Class clazz)

Get the fully qualified database name using default tablespace and translated class name

Parameters:

clazz -

Returns:

getDatabaseName

public static java.lang.String getDatabaseName(java.lang.String clazz)

Get the fully qualified database name using string version of class and default tablespace.

Parameters:

clazz -

Returns:

getAliasToPath

public static java.lang.String getAliasToPath(Alias alias)

Get the tablespace path for the given alias VolumeManager

Parameters:

alias - the database alias

Returns:

the path for this alias or null if none

getOutstandingTransactionsByAliasAndId

public static java.util.List<org.rocksdb.Transaction> getOutstandingTransactionsByAliasAndId(Alias alias,
                                                                                             TransactionId uid)

getOutstandingTransactionsByPathAndId

public static java.util.List<org.rocksdb.Transaction> getOutstandingTransactionsByPathAndId(java.lang.String path,
                                                                                            TransactionId uid)
                                                                                     throws java.io.IOException

Throws:

java.io.IOException

getOutstandingTransactionState

public static java.util.List<java.lang.String> getOutstandingTransactionState()

Return a list of the state of all transactions with id's mapped to transactions in the set of active volumes. According to docs states are: AWAITING_COMMIT AWAITING_PREPARE AWAITING_ROLLBACK COMMITED COMMITTED (?) LOCKS_STOLEN PREPARED ROLLEDBACK STARTED. In practice, it seems to mainly vary between STARTED and COMMITTED. The 'COMMITED' state doesnt seem to manifest.

Returns:

setDatabaseOptions

public static void setDatabaseOptions(org.rocksdb.Options dboptions)

Set the RocksDB options for all subsequent databases

Parameters:

dboptions -

getDefaultOptions

public static org.rocksdb.Options getDefaultOptions(org.rocksdb.AbstractComparator comparator)

Get the default options using a different comparator, primarily to provide hooks inside compare method. The call sequence would be DatabaseManager.setDatabaseOptions(DatabaseManager.getDefaultOptions(your SerializedComparator)) WARNING: must provide all functionality of RockSack SerializedComparator

Parameters:

comparator - the AbstractComparator instance

Returns:

the populated RocksDB options instance

getDefaultDBOptions

public static org.rocksdb.DBOptions getDefaultDBOptions()

Get the default options using default options.

Returns:

the populated DBOptions from default getDefaultOptions method

getDefaultColumnFamilyOptions

public static org.rocksdb.ColumnFamilyOptions getDefaultColumnFamilyOptions()

Get the default ColumnFamily options using default options.

Returns:

the populated ColumnFamilyOptions from default getDefaultOptions method

getMap

public static BufferedMap getMap(java.lang.Comparable clazz)
                          throws java.lang.IllegalAccessException,
                                 java.io.IOException

Get a Map via Comparable instance.

Parameters:

clazz - The Comparable object that the java class name is extracted from

Returns:

A BufferedMap for the clazz instances.

Throws:

java.lang.IllegalAccessException

java.io.IOException

getMap

public static BufferedMap getMap(java.lang.Class clazz)
                          throws java.lang.IllegalAccessException,
                                 java.io.IOException

Get a Map via Java Class type.

Parameters:

clazz - The Java Class of the intended database

Returns:

The BufferedMap for the clazz type.

Throws:

java.lang.IllegalAccessException

java.io.IOException

getMap

public static BufferedMap getMap(Alias alias,
                                 java.lang.Comparable clazz)
                          throws java.lang.IllegalAccessException,
                                 java.io.IOException,
                                 java.util.NoSuchElementException

Get a Map via Comparable instance.

Parameters:

alias - The database alias for tablespace

clazz - The Comparable object that the java class name is extracted from

Returns:

A BufferedMap for the clazz instances.

Throws:

java.lang.IllegalAccessException

java.util.NoSuchElementException - if alias was not found

java.io.IOException

getMap

public static BufferedMap getMap(Alias alias,
                                 java.lang.Class clazz)
                          throws java.lang.IllegalAccessException,
                                 java.io.IOException,
                                 java.util.NoSuchElementException

Get a Map via Java Class type.

Parameters:

alias - The database alias for tablespace

clazz - The Java Class of the intended database

Returns:

The BufferedMap for the clazz type.

Throws:

java.lang.IllegalAccessException

java.util.NoSuchElementException - if alias was not found

java.io.IOException

getTransactionId

public static TransactionId getTransactionId()

Generate a transaction with random UUID

Returns:

the TransactionId with string value randomUUID that will serve as unique globally unique transaction ID

getTransactionId

public static TransactionId getTransactionId(long timeout)

Generate a transaction with random UUID

Parameters:

timeout - the lock timeout in milliseconds

Returns:

the LockingTransactionId with timeout and string value randomUUID that will serve as unique globally unique transaction ID

getTransactionalMap

public static TransactionalMap getTransactionalMap(java.lang.Comparable clazz,
                                                   TransactionId xid)
                                            throws java.lang.IllegalAccessException,
                                                   java.io.IOException,
                                                   org.rocksdb.RocksDBException

Start a new transaction for the given class in the current database

Parameters:

clazz -

Returns:

Throws:

java.lang.IllegalAccessException

java.io.IOException

org.rocksdb.RocksDBException

getTransactionalMap

public static TransactionalMap getTransactionalMap(java.lang.Class clazz,
                                                   TransactionId xid)
                                            throws java.lang.IllegalAccessException,
                                                   java.io.IOException,
                                                   org.rocksdb.RocksDBException

Start a new transaction for the given class in the current database

Parameters:

clazz -

Returns:

Throws:

java.lang.IllegalAccessException

java.io.IOException

org.rocksdb.RocksDBException

getOptimisticTransactionalMap

public static TransactionalMap getOptimisticTransactionalMap(java.lang.Comparable clazz,
                                                             TransactionId xid)
                                                      throws java.lang.IllegalAccessException,
                                                             java.io.IOException,
                                                             org.rocksdb.RocksDBException

Start a new optimistic transaction for the given class in the current database

Parameters:

clazz -

Returns:

Throws:

java.lang.IllegalAccessException

java.io.IOException

org.rocksdb.RocksDBException

getOptimisticTransactionalMap

public static TransactionalMap getOptimisticTransactionalMap(java.lang.Class clazz,
                                                             TransactionId xid)
                                                      throws java.lang.IllegalAccessException,
                                                             java.io.IOException,
                                                             org.rocksdb.RocksDBException

Start a new optimistic transaction for the given class in the current database

Parameters:

clazz -

Returns:

Throws:

java.lang.IllegalAccessException

java.io.IOException

org.rocksdb.RocksDBException

getTransactionalMap

public static TransactionalMap getTransactionalMap(Alias alias,
                                                   java.lang.Comparable clazz,
                                                   TransactionId xid)
                                            throws java.lang.IllegalAccessException,
                                                   java.io.IOException,
                                                   java.util.NoSuchElementException

Start a new transaction for the given class in the aliased database

Parameters:

alias - The alias for the tablespace

clazz -

Returns:

the TransactionalMap for the alias/class/xid

Throws:

java.lang.IllegalAccessException

java.util.NoSuchElementException - if The alias cant be located

java.io.IOException

getTransactionalMap

public static TransactionalMap getTransactionalMap(Alias alias,
                                                   java.lang.Class clazz,
                                                   TransactionId xid)
                                            throws java.lang.IllegalAccessException,
                                                   java.io.IOException,
                                                   java.util.NoSuchElementException

Throws:

java.lang.IllegalAccessException

java.io.IOException

java.util.NoSuchElementException

getOptimisticTransactionalMap

public static TransactionalMap getOptimisticTransactionalMap(Alias alias,
                                                             java.lang.Comparable clazz,
                                                             TransactionId xid)
                                                      throws java.lang.IllegalAccessException,
                                                             java.io.IOException,
                                                             java.util.NoSuchElementException

Start a new transaction for the given class in the aliased database

Parameters:

alias - The alias for the tablespace

clazz -

Returns:

the TransactionalMap for the alias/class/xid

Throws:

java.lang.IllegalAccessException

java.util.NoSuchElementException - if The alias cant be located

java.io.IOException

getOptimisticTransactionalMap

public static TransactionalMap getOptimisticTransactionalMap(Alias alias,
                                                             java.lang.Class clazz,
                                                             TransactionId xid)
                                                      throws java.lang.IllegalAccessException,
                                                             java.io.IOException,
                                                             java.util.NoSuchElementException

Throws:

java.lang.IllegalAccessException

java.io.IOException

java.util.NoSuchElementException

associateSession

public static void associateSession(TransactionId xid,
                                    TransactionalMap tm)
                             throws java.io.IOException

TransactionalMap contains a Session or its subclasses TransactionSession or TransactionSessionAlias. Purpose here is to associate a transaction id TransactionId with a mangled name and 'session to transaction' in SessionTransaction in TransactionManager. The overriden method in TransactionSession.setTransactionalMap will generate a mangled name and start a Transaction.

Parameters:

xid -

tm -

Throws:

java.io.IOException

isSessionAssociated

public static boolean isSessionAssociated(TransactionId xid,
                                          TransactionalMap tm)
                                   throws java.io.IOException

TransactionalMap contains a Session or its subclasses TransactionSession or TransactionSessionAlias. Purpose here is to determine whether a transaction id TransactionId with a mangled name and 'session to transaction' in SessionTransaction in TransactionManager. contains a mangled name and a Transaction.

Parameters:

xid -

tm -

Returns:

true if transaction id is associated to a TransactionalMap

Throws:

java.io.IOException

removeTransactionalMap

public static void removeTransactionalMap(SetInterface tmap)

Remove the given TransactionalMap from active DB/transaction collection

Parameters:

tmap - the TransactionalMap for a given transaction Id

removeTransaction

public static void removeTransaction(TransactionId xid)
                              throws java.io.IOException

Remove from classToIso then idToTransaction in VolumeManager

Parameters:

xid -

Throws:

java.io.IOException - If the transaction is not in a state to be removed. i.e. not COMMITTED, ROLLEDBACK or STARTED

removeTransaction

public static void removeTransaction(Alias alias,
                                     TransactionId xid)
                              throws java.util.NoSuchElementException,
                                     java.io.IOException

Remove from classToIso then idToTransaction in VolumeManager

Parameters:

alias -

xid -

Throws:

java.util.NoSuchElementException - if the alias doesnt exist

java.io.IOException - If the transaction is not in a state to be removed. i.e. not COMMITTED, ROLLEDBACK or STARTED

commitTransaction

public static void commitTransaction(TransactionId xid)
                              throws java.io.IOException

Throws:

java.io.IOException

commitTransaction

public static void commitTransaction(Alias alias,
                                     TransactionId xid)
                              throws java.io.IOException,
                                     java.util.NoSuchElementException

Throws:

java.io.IOException

java.util.NoSuchElementException

rollbackTransaction

public static void rollbackTransaction(TransactionId xid)
                                throws java.io.IOException

Throws:

java.io.IOException

rollbackTransaction

public static void rollbackTransaction(Alias alias,
                                       TransactionId xid)
                                throws java.io.IOException,
                                       java.util.NoSuchElementException

Throws:

java.io.IOException

java.util.NoSuchElementException

checkpointTransaction

public static void checkpointTransaction(TransactionId xid)
                                  throws java.io.IOException

Throws:

java.io.IOException

checkpointTransaction

public static void checkpointTransaction(Alias alias,
                                         TransactionId xid)
                                  throws java.io.IOException,
                                         java.util.NoSuchElementException

Throws:

java.io.IOException

java.util.NoSuchElementException

rollbackToCheckpoint

public static void rollbackToCheckpoint(TransactionId xid)
                                 throws java.io.IOException

Throws:

java.io.IOException

rollbackToCheckpoint

public static void rollbackToCheckpoint(Alias alias,
                                        TransactionId xid)
                                 throws java.io.IOException,
                                        java.util.NoSuchElementException

Throws:

java.io.IOException

java.util.NoSuchElementException

removeMap

public static void removeMap(Alias alias,
                             SetInterface tmap)
                      throws java.util.NoSuchElementException

Remove the given Map from active DB/transaction collection

Parameters:

alias - The alias for the tablespace

tmap - the Map for a given transaction Id

Throws:

java.util.NoSuchElementException

removeMap

public static void removeMap(SetInterface tmap)

Remove the given Map from active DB/transaction collection

Parameters:

tmap - the Map to remove

removeTransactionalMap

public static void removeTransactionalMap(Alias alias,
                                          TransactionSetInterface tmap)
                                   throws java.util.NoSuchElementException

Remove the given TransactionalMap from active DB/transaction collection

Parameters:

alias - The alias for the tablespace

tmap - the TransactionalMap for a given transaction Id

Throws:

java.util.NoSuchElementException

removeTransactionalMap

public static void removeTransactionalMap(TransactionId xid,
                                          TransactionSetInterface tmap)
                                   throws java.io.IOException

Remove the given TransactionalMap from active DB/transaction collection

Parameters:

xid - the transaction id

tmap - the TransactionalMap for a given transaction Id

Throws:

java.io.IOException

removeTransactionalMap

public static void removeTransactionalMap(Alias alias,
                                          TransactionId xid)
                                   throws java.util.NoSuchElementException

Remove the given TransactionalMap from active DB/transaction collection

Parameters:

alias - The alias for the tablespace

xid - The Transaction Id

Throws:

java.util.NoSuchElementException - if the alias does not exist

endTransaction

public static void endTransaction(TransactionId xid)
                           throws java.io.IOException

Throws:

java.io.IOException

clearAllOutstandingTransactions

public static void clearAllOutstandingTransactions()

clearOutstandingTransaction

public static void clearOutstandingTransaction(TransactionId xid)
                                        throws java.io.IOException,
                                               org.rocksdb.RocksDBException

Throws:

java.io.IOException

org.rocksdb.RocksDBException

translateClass

public static java.lang.String translateClass(java.lang.String clazz)

Translate a class name into a legitimate file name with some aesthetics.

Parameters:

clazz -

Returns:

main

public static void main(java.lang.String[] args)
                 throws java.lang.Exception

Throws:

java.lang.Exception