com.bigdata.journal

Class Tx

java.lang.Object

com.bigdata.journal.Tx

All Implemented Interfaces:

ITx, ITxState, ITxState0

public class Tx
extends Object
implements ITx

A transaction.

A transaction is a context in which the application can access and perform operations on fully named indices. Writes on the named indices accessed by the transaction are accumulated in a IsolatedFusedViews. In order to commit, the write set of the transaction must be validated against the then current state of the corresponding unisolated indices and then merge down onto those indices, applying the specified revisionTime. The transaction MUST have an exclusive lock on the named indices on which it will write from the that it begins validation until after the commit or abort of the transaction. This is necessary in order to ensure that concurrent writers can not invalidate the conditions under which validation is performed.

The write set of a transaction is written onto a TemporaryRawStore. Therefore the size limit on the transaction write set is currently 2G, but the transaction will be buffered in memory until the store exceeds its write cache size and creates a backing file on the disk. The store is closed and any backing file is deleted as soon as the transaction completes.

Each IsolatedFusedView is local to a transaction and is backed by the temporary store for that transaction. This means that concurrent transactions can execute without synchronization (real concurrency) up to the point where they #prepare(). We do not need a read-lock on the indices isolated by the transaction since they are historical states that will not receive concurrent updates.

Author:

Bryan Thompson

Field Summary

Fields

Modifier and Type	Field and Description
protected static String	IS_COMPLETE
ReentrantLock	lock This Lock is used to obtain exclusive access during certain operations, including creating the temporary store and isolating a view of a named index.
protected static String	NOT_ACTIVE
protected static String	NOT_COMMITTED
protected static String	NOT_PREPARED

Fields inherited from interface com.bigdata.journal.ITx

READ_COMMITTED, UNISOLATED

Constructor Summary

Constructors

Constructor and Description
Tx(AbstractLocalTransactionManager localTransactionManager, IResourceManager resourceManager, long startTime, long readsOnCommitTime) Create a transaction reading from the most recent committed state not later than the specified startTime.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	equals(ITx o) True iff they are the same object or have the same start timestamp.
String[]	getDirtyResource() Return an array of the resource(s) (the named indices) on which the transaction has written (the isolated index(s) that absorbed the writes for the transaction).
ILocalBTreeView	getIndex(String name) Return a named index.
long	getReadsOnCommitTime() The timestamp of the commit point against which this transaction is reading.
long	getRevisionTime() The revisionTime assigned to the transaction when it was validated and merged down onto the global state.
long	getStartTimestamp() The start time for the transaction as assigned by a centralized transaction manager service.
int	hashCode() The hash code is based on the getStartTimestamp().
boolean	isAborted() A transaction is "aborted" iff it has successfully aborted.
boolean	isActive() A transaction is "active" when it is created and remains active until it prepares or aborts.
boolean	isCommitted() A transaction is "committed" iff it has successfully committed.
boolean	isComplete() A transaction is "complete" once has either committed or aborted.
boolean	isEmptyWriteSet() When true, the transaction has an empty write set.
boolean	isPrepared() A transaction is "prepared" once it has been successfully validated and has fulfilled its pre-commit contract for a multi-stage commit protocol.
boolean	isReadOnly() Return true iff this is a read-only transaction.
protected void	mergeOntoGlobalState(long revisionTime) Invoked during commit processing to merge down the write set from each index isolated by this transactions onto the corresponding unisolated index on the database.
void	prepare(long revisionTime) Validate the write set of the named indices isolated transaction and merge down that write set onto the corresponding unisolated indices but DOES NOT commit the data.
protected void	releaseResources() This method must be invoked any time a transaction completes in order to release resources held by that transaction.
void	setRunState(RunState newval) Change the RunState.
String	toString() Returns a string representation of the transaction start time.
boolean	validateWriteSets() Invoked when a writable transaction prepares in order to validate its write sets (one per isolated index).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

NOT_ACTIVE

protected static final String NOT_ACTIVE

See Also:

Constant Field Values

NOT_PREPARED

protected static final String NOT_PREPARED

See Also:

Constant Field Values

NOT_COMMITTED

protected static final String NOT_COMMITTED

See Also:

Constant Field Values

IS_COMPLETE

protected static final String IS_COMPLETE

See Also:

Constant Field Values

lock

public final ReentrantLock lock

This Lock is used to obtain exclusive access during certain operations, including creating the temporary store and isolating a view of a named index. Exclusive access is required since multiple concurrent operations MAY execute for the same transaction.

Note: This is exposed to the DataService.

Constructor Detail

Tx

public Tx(AbstractLocalTransactionManager localTransactionManager,
  IResourceManager resourceManager,
  long startTime,
  long readsOnCommitTime)

Create a transaction reading from the most recent committed state not later than the specified startTime.

Note: For an IBigdataFederation, a transaction does not start execution on all IDataServices at the same moment. Instead, the transaction startTime is assigned by the ITransactionService and then provided each time an ITx must be created for isolatation of resources accessible on a IDataService.

Parameters:

transactionManager - The local (client-side) transaction manager.

resourceManager - Provides access to named indices that are isolated by the transaction.

startTime - The transaction identifier

readsOnCommitTime - The timestamp of the commit point against which this transaction is reading.

See Also:

Refactor native long tx id to thin object, Add cache for access to historical index views on the Journal by name and commitTime.

Method Detail

getRevisionTime

public long getRevisionTime()

The revisionTime assigned to the transaction when it was validated and merged down onto the global state.

See Also:

mergeOntoGlobalState(long)

getReadsOnCommitTime

public long getReadsOnCommitTime()

Description copied from interface: ITxState0

The timestamp of the commit point against which this transaction is reading.

Note: This is not currently available on a cluster. In that context, we wind up with the same timestamp for #startTime and #readsOnCommitTime which causes cache pollution for things which cache based on #readsOnCommitTime.

Specified by:

getReadsOnCommitTime in interface ITxState0

See Also:

Refactor native long tx id to thin object, Add cache for access to historical index views on the Journal by name and commitTime.

isReadOnly

public boolean isReadOnly()

Description copied from interface: ITxState

Return true iff this is a read-only transaction.

Specified by:

isReadOnly in interface ITxState

setRunState

public void setRunState(RunState newval)

Change the RunState.

Parameters:

newval - The new RunState.

Throws:

IllegalArgumentException - if the argument is null.

IllegalStateException - if the state transition is not allowed.

See Also:

RunState.isTransitionAllowed(RunState)

hashCode

public final int hashCode()

The hash code is based on the getStartTimestamp().

Overrides:

hashCode in class Object

equals

public final boolean equals(ITx o)

True iff they are the same object or have the same start timestamp.

Parameters:

o - Another transaction object.

getStartTimestamp

public final long getStartTimestamp()

Description copied from interface: ITxState0

The start time for the transaction as assigned by a centralized transaction manager service. Transaction start times are unique and also serve as transaction identifiers. Note that this is NOT the time at which a transaction begins executing on a specific journal as the same transaction may start at different moments on different journals and typically will only start on some journals rather than all.

Specified by:

getStartTimestamp in interface ITxState0

Returns:

The transaction start time.

See Also:

TODO Rename since the sign indicates read-only vs read-write and hence it can not be directly interpreted as a commitTime? (e.g., getTxId()).

toString

public final String toString()

Returns a string representation of the transaction start time.

Overrides:

toString in class Object

isActive

public final boolean isActive()

A transaction is "active" when it is created and remains active until it prepares or aborts. An active transaction accepts READ, WRITE, DELETE, PREPARE and ABORT requests.

Note: The value is valid as of the instant that the run state is inspected. The caller must hold a lock if they want to act based on non-final run states.

Specified by:

isActive in interface ITxState

Returns:

True iff the transaction is active.

isPrepared

public final boolean isPrepared()

A transaction is "prepared" once it has been successfully validated and has fulfilled its pre-commit contract for a multi-stage commit protocol. An prepared transaction accepts COMMIT and ABORT requests.

Note: This is a transient state. Once the transaction has prepared it will transition to either COMMIT or ABORT and this method will no longer report true.

Note: The value is valid as of the instant that the run state is inspected. The caller must hold a lock if they want to act based on non-final run states.

Specified by:

isPrepared in interface ITxState

Returns:

True iff the transaction is prepared to commit.

isComplete

public final boolean isComplete()

A transaction is "complete" once has either committed or aborted. A completed transaction does not accept any requests.

Note: The value is valid as of the instant that the run state is inspected. The caller must hold a lock if they want to act based on non-final run states.

Specified by:

isComplete in interface ITxState

Returns:

True iff the transaction is completed.

isCommitted

public final boolean isCommitted()

A transaction is "committed" iff it has successfully committed. A committed transaction does not accept any requests.

Note: The value is valid as of the instant that the run state is inspected. The caller must hold a lock if they want to act based on non-final run states.

Specified by:

isCommitted in interface ITxState

Returns:

True iff the transaction is committed.

isAborted

public final boolean isAborted()

A transaction is "aborted" iff it has successfully aborted. An aborted transaction does not accept any requests.

Note: The value is valid as of the instant that the run state is inspected. The caller must hold a lock if they want to act based on non-final run states.

Specified by:

isAborted in interface ITxState

Returns:

True iff the transaction is aborted.

prepare

public void prepare(long revisionTime)

Validate the write set of the named indices isolated transaction and merge down that write set onto the corresponding unisolated indices but DOES NOT commit the data. The RunState is NOT changed by this method.

For a single-phase commit the caller MUST hold an exclusive lock on the unisolated indices on which this operation will write.

For a distributed transaction, the caller MUST hold a lock on the WriteExecutorService for each IDataService on which the transaction has written.

Parameters:

revisionTime - The revision time assigned by a centralized transaction manager service -or- ZERO (0L) IFF the transaction is read-only.

Throws:

IllegalStateException - if the transaction is not active.

ValidationError - If the transaction can not be validated.

IllegalMonitorStateException - unless the caller holds the lock.

UnsupportedOperationException - if the transaction is read-only.

releaseResources

protected void releaseResources()

This method must be invoked any time a transaction completes in order to release resources held by that transaction.

validateWriteSets

public boolean validateWriteSets()

Invoked when a writable transaction prepares in order to validate its write sets (one per isolated index).

Returns:

true iff the write sets were validated.

mergeOntoGlobalState

protected void mergeOntoGlobalState(long revisionTime)

Invoked during commit processing to merge down the write set from each index isolated by this transactions onto the corresponding unisolated index on the database. This method invoked iff a transaction has successfully prepared and hence is known to have validated successfully. The default implementation is a NOP.

Parameters:

revisionTime -

See Also:

Flush indices in parallel during checkpoint to reduce IO latency

getIndex

public ILocalBTreeView getIndex(String name)

Return a named index. The index will be isolated at the same level as this transaction. Changes on the index will be made restart-safe iff the transaction successfully commits.

Specified by:

getIndex in interface ITx

Parameters:

name - The name of the index.

Returns:

The named index or null if no index is registered under that name.

Throws:

IllegalStateException - if the transaction is not active.

isEmptyWriteSet

public final boolean isEmptyWriteSet()

Description copied from interface: ITx

When true, the transaction has an empty write set.

Specified by:

isEmptyWriteSet in interface ITx

getDirtyResource

public final String[] getDirtyResource()

Description copied from interface: ITx

Return an array of the resource(s) (the named indices) on which the transaction has written (the isolated index(s) that absorbed the writes for the transaction).

Specified by:

getDirtyResource in interface ITx