jetbrains.exodus.env

Interface Transaction

public interface Transaction

Transaction is required for any access to data in database. Any transaction holds a database snapshot (version of the database), thus providing snapshot isolation.

All changes made in a transaction are atomic and consistent if they are successfully flushed or committed. Along with snapshot isolation and configurable durability, transaction are fully ACID-compliant. By default, transaction durability is turned off since it significantly slows down flush()and commit(). To turn it on, pass true to EnvironmentConfig.setLogDurableWrite(boolean).

Transactions can be read-only or not, exclusive or not. Read-only transactions are used to only read data. Exclusive transactions are used to have successive access to database. If you have an exclusive transaction, no other transaction (except read-only) can be started against the same Environment unless you finish (commit or abort) your exclusive one.

Given you have an instance of Environment you can start new transaction:

 final Transaction txn = environment.beginTransaction();
 

Starting read-only transaction:

 final Transaction txn = environment.beginReadonlyTransaction();
 

Starting exclusive transaction:

 final Transaction txn = environment.beginExclusiveTransaction();
 

See Also:

Environment, Environment.beginTransaction(), Environment.beginReadonlyTransaction(), Environment.beginExclusiveTransaction(), EnvironmentConfig.setLogDurableWrite(boolean)

Method Summary

Modifier and Type	Method and Description
void	abort() Drops all changes and finishes the transaction.
boolean	commit() Tries to flush all changes accumulated to the moment in the transaction and finish the transaction.
boolean	flush() Tries to flush all changes accumulated to the moment in the transaction.
@NotNull Environment	getEnvironment()
long	getHighAddress()
Transaction	getReadonlySnapshot() Creates new read-only transaction holding the same database snapshot as this one holds.
Transaction	getSnapshot() Creates new transaction holding the same database snapshot as this one holds.
Transaction	getSnapshot(@Nullable java.lang.Runnable beginHook) Creates new transaction with specified begin hook holding the same database snapshot as this one holds.
long	getStartTime() Time when the transaction acquired its database snapshot, i.e.
@Nullable java.lang.Object	getUserObject(@NotNull java.lang.Object key) Returns an user object identified by the specified key and bound to the transaction, or null if no object is bound to the transaction by the specified key.
boolean	isExclusive()
boolean	isFinished()
boolean	isIdempotent() Idempotent transaction changes nothing in database.
boolean	isReadonly()
void	revert() Drops all changes without finishing the transaction and holds the newest database snapshot.
void	setCommitHook(@Nullable java.lang.Runnable hook) Provides transaction with commit hook.
void	setUserObject(@NotNull java.lang.Object key, @NotNull java.lang.Object value) Bind an user object (value) identified by a key to the transaction.

Method Detail

isIdempotent

boolean isIdempotent()

Idempotent transaction changes nothing in database. It doesn't matter whether you flush it or revert, commit or abort. Result will be the same - nothing will be added, modified or deleted. Flushing idempotent transaction is trivial, flush() just does nothing and returns true. Each newly created transaction is idempotent.

Returns:

true if transaction is idempotent

See Also:

flush(), commit()

abort

void abort()

Drops all changes and finishes the transaction.

See Also:

commit(), flush(), revert(), isFinished()

commit

boolean commit()

Tries to flush all changes accumulated to the moment in the transaction and finish the transaction. If it returns true all changes are flushed and transaction is finished, otherwise nothing is flushed and transaction is not finished.

Returns:

true if transaction is committed

See Also:

flush(), abort(), revert(), isFinished()

flush

boolean flush()

Tries to flush all changes accumulated to the moment in the transaction. Returns true if flush succeeded. In that case, transaction remains unfinished and holds the newest database snapshot.

Returns:

true if transaction is flushed

See Also:

commit(), abort(), revert(), isFinished()

revert

void revert()

Drops all changes without finishing the transaction and holds the newest database snapshot.

See Also:

commit(), abort(), flush(), isFinished()

getSnapshot

Transaction getSnapshot()

Creates new transaction holding the same database snapshot as this one holds.

Returns:

new transaction holding the same database snapshot

See Also:

Environment.beginTransaction()

getSnapshot

Transaction getSnapshot(@Nullable
                        @Nullable java.lang.Runnable beginHook)

Creates new transaction with specified begin hook holding the same database snapshot as this one holds.

Parameters:

beginHook - begin hook

Returns:

new transaction holding the same database snapshot

See Also:

Environment.beginTransaction(Runnable)

getReadonlySnapshot

Transaction getReadonlySnapshot()

Creates new read-only transaction holding the same database snapshot as this one holds.

Returns:

new read-only transaction holding the same database snapshot

See Also:

Environment.beginReadonlyTransaction()

getEnvironment

@NotNull
@NotNull Environment getEnvironment()

Returns:

Environment instance against which the transaction was created.

setCommitHook

void setCommitHook(@Nullable
                   @Nullable java.lang.Runnable hook)

Provides transaction with commit hook. Commit hook is called if and only if the transaction is going to be successfully flushed or committed. That is, hook.run() is called when you call flush() or commit(), and any of these methods will definitely succeed and return true.

Parameters:

hook - commit hook

See Also:

flush(), commit()

getStartTime

long getStartTime()

Time when the transaction acquired its database snapshot, i.e. time when it was started, reverted or successfully flushed (committed).

Returns:

the difference (in milliseconds) between current time and midnight, January 1, 1970 UTC.

getHighAddress

long getHighAddress()

Returns:

the value of Log.getHighAddress() that was actual when the transaction was started.

isReadonly

boolean isReadonly()

Returns:

true if the transaction is read-only.

isExclusive

boolean isExclusive()

Returns:

true if the transaction was started as exclusive one

See Also:

Environment.beginExclusiveTransaction()

isFinished

boolean isFinished()

Returns:

true if the transaction is finished, committed or aborted

See Also:

commit(), abort()

getUserObject

@Nullable
@Nullable java.lang.Object getUserObject(@NotNull
                                                   @NotNull java.lang.Object key)

Returns an user object identified by the specified key and bound to the transaction, or null if no object is bound to the transaction by the specified key.

Parameters:

key - a key identifying the user object

Returns:

an user object identified by the specified key and bound to the transaction

setUserObject

void setUserObject(@NotNull
                   @NotNull java.lang.Object key,
                   @NotNull
                   @NotNull java.lang.Object value)

Bind an user object (value) identified by a key to the transaction.

Parameters:

key - a key identifying the user object

value - user object bound to the transaction