com.sun.jini.outrigger

Class Txn

java.lang.Object

com.sun.jini.outrigger.Txn

All Implemented Interfaces:

StorableObject, TransactableConstants, TransactableMgr, TransactionConstants

 class Txn
extends Object
implements TransactableMgr, TransactionConstants, StorableObject

This class represents a space's state in a single transaction. Object of this class represent Jini transactions within outrigger. These transactions hold "Transactables" -- things that represent the actions that have been taken under this transaction. For example, if this transaction were to be cancelled, the Transactables are examined and serve as the list of things to roll back in order to restore the state of the Space status quo ante. This is achieved by having the transactables notified of state changes to this transaction such as preparing, commit, etc. The transactables themselves are responsible for "doing the right thing." NB: some--but not all--of the actions one can take with a transaction are managed internally by these objects. That is, all of the important methods objects of these types are synchronized. Therefore, two simultaneous calls to abort() and commit() are arbitrated properly. However, care must be taken when add()ing a transactable. Even though the add() method is synchronized if you check the state of the transaction to ensure that is active and then call add() the transaction could have left the active state between the check and the add() call unless the call obtains the appropriate locks. This is even more likely if other work needs to be done in addition to calling add() (e.g. persisting state, obtaining locks, etc.). The caller of add() should lock the associated transaction object and ensure that the transaction is still considered ACTIVE, do whatever work is necessary to complete while the transaction is in the ACTIVE state (including calling call add()) and then release the lock. This can be done by :

• holding the lock on this object while checking the state and carrying out the operation (including calling add()), or
• calling ensureActive() to check the state and obtain a non-exclusive lock, carrying out the operation (including calling add()), and then calling allowStateChange() to release the lock.

The pair of ensureActive() and allowStateChange() allows for more concurrency if the operation is expected to take a long time, in that it will allow for other operations to be performed under the same transaction and let aborts prevent other operations from being started.

Author:

Sun Microsystems, Inc.

Field Summary

Fields

Modifier and Type	Field and Description
private long	id The internal id Outrigger as assigned to the transaction
private static Logger	logger Logger for logging transaction related information
private TxnMonitorTask	monitorTask The task responsible for monitoring to see if this transaction has been aborted with us being told, or null if no such task as been allocated.
private int	state What state we think the transaction is in
private boolean	stateChangeWaiting true if there is a blocked state change.
private int	stateReaders Count of number of threads holding a read lock on state
private ServerTransaction	tr Cached ServerTransaction object for the transaction this object is fronting for.
private long	trId The id the transaction manager assigned to this transaction
private StorableReference	trm The transaction manager associated with the transaction this object is fronting for.
private List	txnables The list of Transactable participating in this transaction.

Fields inherited from interface com.sun.jini.outrigger.TransactableConstants

READ, stateNames, TAKE, WRITE

Fields inherited from interface net.jini.core.transaction.server.TransactionConstants

ABORTED, ACTIVE, COMMITTED, NOTCHANGED, PREPARED, VOTING

Constructor Summary

Constructors

Constructor and Description
Txn(long id) Used in recovery
Txn(ServerTransaction tr, long id) Create a new Txn that represents our state in the given ServerTransaction.

Method Summary

Methods

Modifier and Type	Method and Description
(package private) void	abort(OutriggerServerImpl space) Abort the transaction.
Transactable	add(Transactable t) Caution: see locking discussion at the class level.
(package private) void	allowStateChange() Release the read lock created by an ensureActive call.
private void	cleanup() Clean up any state when the transaction is finished.
(package private) void	commit(OutriggerServerImpl space) Having prepared, roll the changes forward.
(package private) void	ensureActive() Atomically checks that this transaction is in the active state and locks the transaction in the active state.
(package private) Long	getId() Get the id for this txn.
(package private) TransactionManager	getManager() Return the manager associated with this transaction.
(package private) int	getState() Return our local view of the current state.
ServerTransaction	getTransaction(ProxyPreparer preparer) Return the ServerTransaction which this manager handles.
(package private) long	getTransactionId() We keep the transaction ID around because we may need it to identify a broken transaction after recovery.
(package private) void	makeInactive() Prevents new operations from being started under this transaction and blocks until in process operations are completed.
(package private) TxnMonitorTask	monitorTask() Return the monitor task for this object.
(package private) void	monitorTask(TxnMonitorTask task) Set the monitor task for this object.
(package private) int	prepare(OutriggerServerImpl space) Prepare for transaction commit.
void	restore(ObjectInputStream in) Restore the persistent fields
void	store(ObjectOutputStream out) Store the persistent fields

Methods inherited from class java.lang.Object

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

Field Detail

id

private final long id

The internal id Outrigger as assigned to the transaction

state

private int state

What state we think the transaction is in

trm

private StorableReference trm

The transaction manager associated with the transaction this object is fronting for.

tr

private ServerTransaction tr

Cached ServerTransaction object for the transaction this object is fronting for.

trId

private long trId

The id the transaction manager assigned to this transaction

txnables

private final List txnables

The list of Transactable participating in this transaction.

monitorTask

private TxnMonitorTask monitorTask

The task responsible for monitoring to see if this transaction has been aborted with us being told, or null if no such task as been allocated.

stateReaders

private int stateReaders

Count of number of threads holding a read lock on state

stateChangeWaiting

private boolean stateChangeWaiting

true if there is a blocked state change. Used to give writers priority.

logger

private static final Logger logger

Logger for logging transaction related information

Constructor Detail

Txn

Txn(ServerTransaction tr,
   long id)

Create a new Txn that represents our state in the given ServerTransaction.

Txn

Txn(long id)

Used in recovery

Method Detail

getId

Long getId()

Get the id for this txn. Note that this id is NOT the same as the ID of the transaction. Since that ID is not unique (it must be qualified with the ServerTransaction object) we create our own internal id to make txns unique. This is needed since we may not have the Transaction unmarshalled.

getTransactionId

long getTransactionId()

We keep the transaction ID around because we may need it to identify a broken transaction after recovery.

getState

int getState()

Return our local view of the current state. Need to be holding the lock on this object or have called ensureActive to get the current value.

ensureActive

void ensureActive()
            throws CannotJoinException

Atomically checks that this transaction is in the active state and locks the transaction in the active state. The lock can be released by calling allowStateChange. Each call to this method should be paired with a call to allowStateChange in a finally block.

Throws:

CannotJoinException - if the transaction is not active or a state change is pending.

allowStateChange

void allowStateChange()

Release the read lock created by an ensureActive call. Does nothing if the transaction is not active or there is a state change pending and thus is safe to call even if the corresponding ensureActive call threw CannotJoinException.

makeInactive

void makeInactive()

Prevents new operations from being started under this transaction and blocks until in process operations are completed.

prepare

int prepare(OutriggerServerImpl space)

Prepare for transaction commit. makeInactive must have been called on this transaction first.

abort

void abort(OutriggerServerImpl space)

Abort the transaction. This must be callable from prepare because if a Transactable votes ABORT, this method is called to make that happen. makeInactive must have been called on this transaction first.

commit

void commit(OutriggerServerImpl space)

Having prepared, roll the changes forward. makeInactive must have been called on this transaction first.

add

public Transactable add(Transactable t)

Caution: see locking discussion at the class level.

Specified by:

add in interface TransactableMgr

getTransaction

public ServerTransaction getTransaction(ProxyPreparer preparer)
                                 throws IOException,
                                        ClassNotFoundException

Description copied from interface: TransactableMgr

Return the ServerTransaction which this manager handles. If necessary deserialize the manager and optionally prepare it. Will only deserialize the manager if it has not already been deserialized. Will only prepare the manager if preparer is non-null and no previous call to getTransaction has succeeded. If this method throws an exception, preparation has not succeeded. If a previous call to this method has succeed, all future calls will succeed and return the same object as the first successful call.

Specified by:

getTransaction in interface TransactableMgr

Parameters:

preparer - the ProxyPreparer to be used to prepare the reference. May be null.

Returns:

the ServerTransaction which this manager handles.

Throws:

IOException - if the unmarshalling fails. Will also throw RemoteException if preparer.prepareProxy does.

ClassNotFoundException - if unmarshalling fails with one.

getManager

TransactionManager getManager()

Return the manager associated with this transaction.

Returns:

the manager associated with this transaction.

Throws:

IllegalStateException - if this Txn is still broken.

monitorTask

TxnMonitorTask monitorTask()

Return the monitor task for this object. Note, this method is unsynchronized because it (and monitorTask(TxnMonitorTask) are both called from the same thread.

monitorTask

void monitorTask(TxnMonitorTask task)

Set the monitor task for this object. Note, this method is unsynchronized because it (and monitorTask() are both called from the same thread.

cleanup

private void cleanup()

Clean up any state when the transaction is finished.

store

public void store(ObjectOutputStream out)
           throws IOException

Description copied from interface: StorableObject

Store the persistent fields

Specified by:

store in interface StorableObject

Throws:

IOException

restore

public void restore(ObjectInputStream in)
             throws IOException,
                    ClassNotFoundException

Description copied from interface: StorableObject

Restore the persistent fields

Specified by:

restore in interface StorableObject

Throws:

IOException

ClassNotFoundException