com.bigdata.journal
Class Tx

java.lang.Object
  com.bigdata.journal.Tx

All Implemented Interfaces:

ITx

public class Tx
extends Object
implements ITx

A read-write 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.

Version:

$Id: Tx.java 2547 2010-03-24 20:44:07Z thompsonbry $

Author:

Bryan Thompson

TODO:

javadoc update for temporary stores (shared temporary journals) and concurrency limits (concurrent operations on the same transaction with a partial order imposed by locks on the isolated indices and concurrent operations on different transactions)., Track which IndexSegments and Journals are required to support the IsolatedFusedViews in use by a Tx. The easiest way to do this is to name these by appending the transaction identifier to the name of the index partition, e.g., name#partId#tx. At that point the StoreManager will automatically track the resources. This also simplifies access control (write locks) for the isolated indices as the same WriteExecutorService will serve. However, with this approach {split, move, join} operations will have to be either deferred or issued against the isolated index partitions as well as the unisolated index partitions.

Make writes on the tx thread-safe (Temporary mode Journal rather than TemporaryStore)., Modify the isolated indices use a delegation strategy so that I can trap attempts to access an isolated index once the transaction is no longer active? Define "active" as up to the point where a "commit" or "abort" is _requested_ for the tx. (Alternative, extend the close() model for an index to not permit the re-open of an isolated index after the tx commits and then just close the btree absorbing writes for the isolated index when we are releasing our various resources. The isolated index will thereafter be unusable, which is what we want.)

Field Summary

protected static boolean	INFO
protected static String	IS_COMPLETE
protected AbstractLocalTransactionManager	localTransactionManager Used for some handshaking in the commit protocol.
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 org.apache.log4j.Logger	log
protected static String	NOT_ACTIVE
protected static String	NOT_COMMITTED
protected static String	NOT_PREPARED
protected IResourceManager	resourceManager Used to locate the named indices that the transaction isolates.
protected long	startTime The start startTime assigned to this transaction.

Fields inherited from interface com.bigdata.journal.ITx

READ_COMMITTED, UNISOLATED

Constructor Summary

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

Method Summary

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

log

protected static final org.apache.log4j.Logger log

INFO

protected static final boolean INFO

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.

localTransactionManager

protected final AbstractLocalTransactionManager localTransactionManager

Used for some handshaking in the commit protocol.

resourceManager

protected final IResourceManager resourceManager

Used to locate the named indices that the transaction isolates.

startTime

protected final long startTime

The start startTime assigned to this transaction.

Note: Transaction startTime and revisionTimes are assigned by the ITransactionService.

Constructor Detail

Tx

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

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

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)

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: ITx

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 ITx

Returns:

The transaction start time.

toString

public final String toString()

Returns a string representation of the transaction start time.

Overrides:

toString in class Object

isActive

public final boolean isActive()

Description copied from interface: ITx

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.

Specified by:

isActive in interface ITx

Returns:

True iff the transaction is active.

isPrepared

public final boolean isPrepared()

Description copied from interface: ITx

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.

Specified by:

isPrepared in interface ITx

Returns:

True iff the transaction is prepared to commit.

isComplete

public final boolean isComplete()

Description copied from interface: ITx

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

Specified by:

isComplete in interface ITx

Returns:

True iff the transaction is completed.

isCommitted

public final boolean isCommitted()

Description copied from interface: ITx

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

Specified by:

isCommitted in interface ITx

Returns:

True iff the transaction is committed.

isAborted

public final boolean isAborted()

Description copied from interface: ITx

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

Specified by:

isAborted in interface ITx

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.

releaseResources

protected void releaseResources()

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

validateWriteSets

protected boolean validateWriteSets()

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

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 -

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