com.sun.jini.outrigger
Class Txn

java.lang.Object
  extended by 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 :

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
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
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
(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


Copyright 2007-2010, multiple authors.
Licensed under the Apache License, Version 2.0, see the NOTICE file for attributions.