jetbrains.exodus.env

Interface Environment

All Superinterfaces:

java.lang.AutoCloseable, Backupable, java.io.Closeable

All Known Subinterfaces:

ContextualEnvironment

public interface Environment
extends java.io.Closeable, Backupable

Environment encapsulates one or more stores that contain data. It allows to perform read/modify operations against multiple stores within a single transaction. In short, Environment is a transactional key-value storage.

Instance of Environment can be created with the help of the Environments utility class:

     Environment env = Environments.newInstance("/home/me/.myAppData");
 

Environment will be created if specified database directory doesn't contain database files. It's impossible to share single database directory amongst different Environment instances. An attempt to do this (from within any process, current or not) will fail.

To open Environment with custom settings, use EnvironmentConfig class. E.g., opening environment with disabled garbage collector looks as follows:

     Environment env = Environments.newInstance("/home/me/.myAppData", new EnvironmentConfig().setGcEnabled(false));
 

After finishing working with the Environment you should close() it.

Method Summary

Modifier and Type	Method and Description
@NotNull Transaction	beginExclusiveTransaction() Starts new exclusive transaction which can be used to read and write data.
@NotNull Transaction	beginExclusiveTransaction(java.lang.Runnable beginHook) Starts new exclusive transaction which can be used to read and write data.
@NotNull Transaction	beginReadonlyTransaction() Starts new transaction which can be used to only read data.
@NotNull Transaction	beginReadonlyTransaction(java.lang.Runnable beginHook) Starts new transaction which can be used to only read data.
@NotNull Transaction	beginTransaction() Starts new transaction which can be used to read and write data.
@NotNull Transaction	beginTransaction(java.lang.Runnable beginHook) Starts new transaction which can be used to read and write data.
void	clear() Clears all the data in the environment.
void	close() Closes environment instance.
<T> T	computeInExclusiveTransaction(@NotNull TransactionalComputable<T> computable) Computes and returns a value by calling specified computable in a new exclusive transaction.
<T> T	computeInReadonlyTransaction(@NotNull TransactionalComputable<T> computable) Computes and returns a value by calling specified computable in a new read-only transaction.
<T> T	computeInTransaction(@NotNull TransactionalComputable<T> computable) Computes and returns a value by calling specified computable in a new transaction.
void	executeInExclusiveTransaction(@NotNull TransactionalExecutable executable) Executes specified executable in a new exclusive transaction.
void	executeInReadonlyTransaction(@NotNull TransactionalExecutable executable) Executes specified executable in a new read-only transaction.
void	executeInTransaction(@NotNull TransactionalExecutable executable) Executes specified executable in a new transaction.
void	executeTransactionSafeTask(@NotNull java.lang.Runnable task) Executes a task after all currently started transactions finish.
void	gc() Says environment to quicken background database garbage collector activity.
@NotNull java.util.List<java.lang.String>	getAllStoreNames(@NotNull Transaction txn)
long	getCipherBasicIV() Returns cipher basic IV (initialization vector) to use for database encryption.
@Nullable byte[]	getCipherKey() Returns cipher key to use for database encryption, or null if the environment is not configured to be encrypted.
@Nullable StreamCipherProvider	getCipherProvider() Returns instance of StreamCipherProvider if the environment is configured to be encrypted, or null.
long	getCreated() Returns the value of System.currentTimeMillis() when this environment was created.
@NotNull EnvironmentConfig	getEnvironmentConfig() Returns EnvironmentConfig instance used during creation of the environment.
@NotNull java.lang.String	getLocation() Returns location of database files on storage device.
@NotNull Statistics	getStatistics()
boolean	isOpen()
@NotNull Store	openStore(@NotNull java.lang.String name, @NotNull StoreConfig config, @NotNull Transaction transaction) Opens existing or creates new store with specified name and config inside a transaction.
@Nullable Store	openStore(@NotNull java.lang.String name, @NotNull StoreConfig config, @NotNull Transaction transaction, boolean creationRequired) Opens existing or creates new store with specified name and config inside a transaction.
void	removeStore(@NotNull java.lang.String storeName, @NotNull Transaction txn) Removes store with specified name.
void	resumeGC() Resumes earlier suspended database garbage collector activity.
boolean	storeExists(@NotNull java.lang.String storeName, @NotNull Transaction txn)
void	suspendGC() Suspends database garbage collector activity unless resumeGC() is called.
void	truncateStore(@NotNull java.lang.String storeName, @NotNull Transaction txn) Truncates store with specified name.

Methods inherited from interface jetbrains.exodus.backup.Backupable

getBackupStrategy

Method Detail

getCreated

long getCreated()

Returns the value of System.currentTimeMillis() when this environment was created. If your application works constantly with a single environment and closes it on exit, the environment's creation time can be used to get the applications' up-time.

Returns:

the time when this Environment instance was created.

getLocation

@NotNull
@NotNull java.lang.String getLocation()

Returns location of database files on storage device. Can be used as unique key for environment instance.

Returns:

location of database files

openStore

@NotNull
@NotNull Store openStore(@NotNull
                                   @NotNull java.lang.String name,
                                   @NotNull
                                   @NotNull StoreConfig config,
                                   @NotNull
                                   @NotNull Transaction transaction)

Opens existing or creates new store with specified name and config inside a transaction. StoreConfig provides meta-information used to create store. If it is known that the store with specified name exists, then StoreConfig.USE_EXISTING can be used.

Parameters:

name - name of store

config - StoreConfig used to create store

transaction - Transaction used to create store

Returns:

Store instance

openStore

@Nullable
@Nullable Store openStore(@NotNull
                                     @NotNull java.lang.String name,
                                     @NotNull
                                     @NotNull StoreConfig config,
                                     @NotNull
                                     @NotNull Transaction transaction,
                                     boolean creationRequired)

Opens existing or creates new store with specified name and config inside a transaction. StoreConfig provides meta-information used to create the store. If it is known that the store with specified name exists, then StoreConfig.USE_EXISTING can be used.

Pass true as creationRequired if creating new store is required or allowed. In that case, the method will do the same as openStore(String, StoreConfig, Transaction). If you pass false the method will return null for non-existing store.

Parameters:

name - name of store

config - StoreConfig used to create store

transaction - Transaction used to create store

creationRequired - pass false if you wish to get null for non-existing store rather than create it

Returns:

Store instance

executeTransactionSafeTask

void executeTransactionSafeTask(@NotNull
                                @NotNull java.lang.Runnable task)

Executes a task after all currently started transactions finish.

Parameters:

task - task to execute

clear

void clear()

Clears all the data in the environment. It is safe to clear environment with lots of parallel transactions, though it can't proceed if there is a Transaction (even read-only) started in current thread.

Throws:

ExodusException - if there is a Transaction in current thread

See Also:

Transaction

close

void close()

Closes environment instance. Make sure there are no unfinished transactions, otherwise the method fails with ExodusException. This behaviour can be changed by calling EnvironmentConfig.setEnvCloseForcedly(boolean) with true. After environment is closed another instance of Environment by the same location can be created.

Specified by:

close in interface java.lang.AutoCloseable

Specified by:

close in interface java.io.Closeable

Throws:

ExodusException - if there are unfinished transactions

EnvironmentClosedException - if environment is already closed

isOpen

boolean isOpen()

Returns:

false is the instance is closed

getAllStoreNames

@NotNull
@NotNull java.util.List<java.lang.String> getAllStoreNames(@NotNull
                                                                     @NotNull Transaction txn)

Parameters:

txn - transaction instance

Returns:

the list of names of all stores created in the environment.

storeExists

boolean storeExists(@NotNull
                    @NotNull java.lang.String storeName,
                    @NotNull
                    @NotNull Transaction txn)

Parameters:

storeName - name of store

txn - transaction instance

Returns:

true if store with specified name exists

truncateStore

void truncateStore(@NotNull
                   @NotNull java.lang.String storeName,
                   @NotNull
                   @NotNull Transaction txn)

Truncates store with specified name. The store becomes empty. All earlier opened Store instances should be invalidated and re-opened.

Parameters:

storeName - name of store

txn - transaction instance

removeStore

void removeStore(@NotNull
                 @NotNull java.lang.String storeName,
                 @NotNull
                 @NotNull Transaction txn)

Removes store with specified name. All earlier opened Store instances become unusable.

Parameters:

storeName - name of store

txn - transaction instance

gc

void gc()

Says environment to quicken background database garbage collector activity. Invocation of this method doesn't have immediate consequences like freeing disk space, deleting particular files, etc.

suspendGC

void suspendGC()

Suspends database garbage collector activity unless resumeGC() is called. Has no effect if it is already suspended. Environment instance can created with disabled GC.

See Also:

EnvironmentConfig.setGcEnabled(boolean)

resumeGC

void resumeGC()

Resumes earlier suspended database garbage collector activity. Has no effect if it si not suspended.

beginTransaction

@NotNull
@NotNull Transaction beginTransaction()

Starts new transaction which can be used to read and write data.

Returns:

new transaction instance

See Also:

Transaction

beginTransaction

@NotNull
@NotNull Transaction beginTransaction(java.lang.Runnable beginHook)

Starts new transaction which can be used to read and write data. Specified beginHook is called each time when the transaction holds the new database snapshot. First time it is called during beginTransaction() execution, then during each call to Transaction.flush() or Transaction.revert().

Parameters:

beginHook - begin hook

Returns:

new transaction instance

See Also:

Transaction

beginExclusiveTransaction

@NotNull
@NotNull Transaction beginExclusiveTransaction()

Starts new exclusive transaction which can be used to read and write data. For given exclusive transaction, it is guaranteed that no other transaction (except read-only ones) can be started on the environment before the given one finishes.

Returns:

new transaction instance

See Also:

Transaction, Transaction.isExclusive()

beginExclusiveTransaction

@NotNull
@NotNull Transaction beginExclusiveTransaction(java.lang.Runnable beginHook)

Starts new exclusive transaction which can be used to read and write data. For given exclusive transaction, it is guaranteed that no other transaction (except read-only ones) can be started on the environment before the given one finishes. Specified beginHook is called each time when the transaction holds the new database snapshot. First time it is called during beginTransaction() execution, then during each call to Transaction.flush() or Transaction.revert().

Parameters:

beginHook - begin hook

Returns:

new transaction instance

See Also:

Transaction

beginReadonlyTransaction

@NotNull
@NotNull Transaction beginReadonlyTransaction()

Starts new transaction which can be used to only read data.

Returns:

new transaction instance

See Also:

Transaction, Transaction.isReadonly()

beginReadonlyTransaction

@NotNull
@NotNull Transaction beginReadonlyTransaction(java.lang.Runnable beginHook)

Starts new transaction which can be used to only read data. Specified beginHook is called each time when the transaction holds the new database snapshot. First time it is called during beginTransaction() execution, then during each call to Transaction.revert().

Parameters:

beginHook - begin hook

Returns:

new transaction instance

See Also:

Transaction, Transaction.isReadonly()

executeInTransaction

void executeInTransaction(@NotNull
                          @NotNull TransactionalExecutable executable)

Executes specified executable in a new transaction. If transaction cannot be flushed after TransactionalExecutable.execute(Transaction) is called, the executable is executed once more until the transaction is finally flushed.

Parameters:

executable - transactional executable

See Also:

TransactionalExecutable

executeInExclusiveTransaction

void executeInExclusiveTransaction(@NotNull
                                   @NotNull TransactionalExecutable executable)

Executes specified executable in a new exclusive transaction. TransactionalExecutable.execute(Transaction) is called once since the transaction is exclusive, and its flush should always succeed.

Parameters:

executable - transactional executable

See Also:

TransactionalExecutable

executeInReadonlyTransaction

void executeInReadonlyTransaction(@NotNull
                                  @NotNull TransactionalExecutable executable)

Executes specified executable in a new read-only transaction. TransactionalExecutable.execute(Transaction) is called once since the transaction is read-only, and it is never flushed.

Parameters:

executable - transactional executable

See Also:

TransactionalExecutable, Transaction.isReadonly()

computeInTransaction

<T> T computeInTransaction(@NotNull
                           @NotNull TransactionalComputable<T> computable)

Computes and returns a value by calling specified computable in a new transaction. If transaction cannot be flushed afterTransactionalComputable.compute(Transaction) is called, the computable is computed once more until the transaction is finally flushed.

Parameters:

computable - transactional computable

See Also:

TransactionalComputable

computeInExclusiveTransaction

<T> T computeInExclusiveTransaction(@NotNull
                                    @NotNull TransactionalComputable<T> computable)

Computes and returns a value by calling specified computable in a new exclusive transaction. TransactionalComputable.compute(Transaction) is called once since the transaction is exclusive, and its flush should always succeed.

Parameters:

computable - transactional computable

See Also:

TransactionalComputable

computeInReadonlyTransaction

<T> T computeInReadonlyTransaction(@NotNull
                                   @NotNull TransactionalComputable<T> computable)

Computes and returns a value by calling specified computable in a new read-only transaction. TransactionalComputable.compute(Transaction) is called once since the transaction is read-only, and it is never flushed.

Parameters:

computable - transactional computable

See Also:

TransactionalComputable, Transaction.isReadonly()

getEnvironmentConfig

@NotNull
@NotNull EnvironmentConfig getEnvironmentConfig()

Returns EnvironmentConfig instance used during creation of the environment. If no config was specified and no setting was mutated, then returned config has the same settings as EnvironmentConfig.DEFAULT.

Returns:

EnvironmentConfig instance

getStatistics

@NotNull
@NotNull Statistics getStatistics()

Returns:

statistics of this Environment instance

getCipherProvider

@Nullable
@Nullable StreamCipherProvider getCipherProvider()

Returns instance of StreamCipherProvider if the environment is configured to be encrypted, or null.

Returns:

instance of StreamCipherProvider if the environment is configured to be encrypted, or null

See Also:

StreamCipherProvider, EnvironmentConfig.getCipherId()

getCipherKey

@Nullable
@Nullable byte[] getCipherKey()

Returns cipher key to use for database encryption, or null if the environment is not configured to be encrypted.

Returns:

cipher key to use for database encryption, or null if the environment is not configured to be encrypted

See Also:

StreamCipher.init(byte[], long), EnvironmentConfig.getCipherKey()

getCipherBasicIV

long getCipherBasicIV()

Returns cipher basic IV (initialization vector) to use for database encryption.

Returns:

cipher basic IV (initialization vector) to use for database encryption to be encrypted

See Also:

StreamCipher.init(byte[], long), EnvironmentConfig.getCipherBasicIV()