com.bigdata.journal
Interface ITx

All Known Implementing Classes:

Tx

public interface ITx

Interface for transaction state on the client.

Version:

$Id: ITx.java 2265 2009-10-26 12:51:06Z thompsonbry $

Author:

Bryan Thompson

Field Summary

static long	READ_COMMITTED A constant that SHOULD used as the timestamp for read-committed (non-transactional dirty reads) operations.
static long	UNISOLATED The constant that SHOULD used as the timestamp for an unisolated read-write operation.

Method Summary

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 an isolated view onto a named index.
long	getStartTimestamp() The start time for the transaction as assigned by a centralized transaction manager service.
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.

Field Detail

UNISOLATED

static final long UNISOLATED

The constant that SHOULD used as the timestamp for an unisolated read-write operation. The value of this constant is ZERO (0L) -- this value corresponds to Wed Dec 31 19:00:00 EST 1969 when interpreted as a Date.

See Also:

Constant Field Values

READ_COMMITTED

static final long READ_COMMITTED

A constant that SHOULD used as the timestamp for read-committed (non-transactional dirty reads) operations. The value of this constant is MINUS ONE (-1L) -- this value corresponds to Wed Dec 31 18:59:59 EST 1969 when interpreted as a Date.

If you want a scale-out index to be read consistent over multiple operations, then use IIndexStore.getLastCommitTime() when you specify the timestamp for the view. The index will be as of the specified commit time and more recent commit points will not become visible.

AbstractTasks that run with read-committed isolation provide a read-only view onto the most recently committed state of the indices on which they read. However, when a process runs a series of AbstractTasks with read-committed isolation the view of the index in each distinct task will change if concurrenct processes commit writes on the index (some constructs, such as the scale-out iterators, provide read-consistent views for the last commit time). Further, an index itself can appear or disappear if concurrent processes drop or register that index.

A read-committed transaction imposes fewer constraints on when old resources (historical journals and index segments) may be released. For this reason, a read-committed transaction is a good choice when a very-long running read must be performed on the database. Since a read-committed transaction does not allow writes, the commit and abort protocols are identical.

However, split/join/move operations can cause locators to become invalid for read-committed (and unisolated) operations. For this reason, it is often better to specify "read-consistent" semantics by giving the lastCommitTime for the IIndexStore.

See Also:

Constant Field Values

Method Detail

getStartTimestamp

long getStartTimestamp()

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.

Returns:

The transaction start time.

TODO:

rename since the sign indicates read-only vs read-write?

isEmptyWriteSet

boolean isEmptyWriteSet()

When true, the transaction has an empty write set.

isActive

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.

Returns:

True iff the transaction is active.

isPrepared

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.

Returns:

True iff the transaction is prepared to commit.

isComplete

boolean isComplete()

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

Returns:

True iff the transaction is completed.

isCommitted

boolean isCommitted()

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

Returns:

True iff the transaction is committed.

isAborted

boolean isAborted()

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

Returns:

True iff the transaction is aborted.

getIndex

ILocalBTreeView getIndex(String name)

Return an isolated view onto 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. Writes on the returned index will be isolated in an IsolatedFusedView. Reads that miss on the IsolatedFusedView will read through named index as of the ground state of this transaction. If the transaction is read-only then the index will not permit writes.

During #prepare(long), the write set of each IsolatedFusedView will be validated against the then current commited state of the named index.

During #mergeDown(), the validated write sets will be merged down onto the then current committed state of the named index.

Parameters:

name - The index name.

Returns:

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

Throws:

IllegalArgumentException - if name is null

IllegalStateException - if the transaction is not active.

getDirtyResource

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).