com.ibm.tspaces
Class Transaction

java.lang.Object
  |
  +--com.ibm.tspaces.Transaction

public class Transaction
extends java.lang.Object

This is the client portion of the TSpaces Transaction support.

 It allows the user to do the following:
   create a transaction
   add a tuplespace to the transaction
   begin, commit and abort transactions
It also contains a number of utility rtns related to Transaction processing

Author:
Thomas Baby

Constructor Summary
Transaction()
          Each transaction starts with only a little bit of state
 
Method Summary
 void abortTrans()
          Signifies that any operation performed by this transaction have to be undone at the T Spaces server
 void addTupleSpace(TupleSpace space_)
          Adds a TupleSpace object to this Transaction object so that any operation on an added space will be treated as part of this Transaction object if enclosed between a beginTrans() and commitTrans()/abortTrans() operations
 void beginTrans()
          Denotes the start of a transaction.
 void commitTrans()
          This function must be called if a transaction is to be commutted.
static java.lang.String generateUniqueID()
          This static class method returns a unique identifier for this transaction.
 int getTransState()
          Returns the state of this transaction object
 java.lang.String getUniqueID()
          This function returns the unique identifier for this transaction.
 int seqNumber()
          Returns a unique number associated with this Transaction instance.
 void setTransState(int transState_)
          This is used by TupleSpace object to set the state of the transaction object to _RUNNING_STATE once a command has been sent.
 void setUniqueID(java.lang.String transactionID_)
          This function is called after the first command for this Transaction object has been sent to set the unique id for this transaction.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Transaction

public Transaction()
Each transaction starts with only a little bit of state
Method Detail

addTupleSpace

public void addTupleSpace(TupleSpace space_)
                   throws TupleSpaceCommunicationException,
                          TupleSpaceClientException,
                          TupleSpaceServerException
Adds a TupleSpace object to this Transaction object so that any operation on an added space will be treated as part of this Transaction object if enclosed between a beginTrans() and commitTrans()/abortTrans() operations
Parameters:
space_ - TupleSpace object to be added to this Transaction object

beginTrans

public void beginTrans()
Denotes the start of a transaction. Any operation performed on a TupleSpace object that is enclosed within this Transaction object will be treated as part of this transaction if the operation is performed after the completion of this function NOTE: Thing to remember: It is very very important to abort or commit a transaction by explicitly calling the abortTrans or commitTrans methods of the Transaction object. If this is not done, there cannot be any guarantees. I tried to help a forgetful programmer by sending an abortTrans message for a transaction that has not sent a commit or abort by making use of the finalize method. But if there is a server crash, an IOException is thrown back at the user. Not a neat solution. I did not have time to fix this. But it is a nice feature.

commitTrans

public void commitTrans()
                 throws TupleSpaceException
This function must be called if a transaction is to be commutted. i.e., if the operations performed by this transaction have to be permanently recorded in the database
Throws:
TupleSpaceCommunicationException - communication problem to server
TupleSpaceServerException - problem at the T Spaces server
TupleSpaceClientException - problem at the client side

abortTrans

public void abortTrans()
                throws TupleSpaceException
Signifies that any operation performed by this transaction have to be undone at the T Spaces server
Throws:
TupleSpaceCommunicationException - communication problem to server
TupleSpaceServerException - problem at the T Spaces server
TupleSpaceClientException - problem at the client side

setTransState

public void setTransState(int transState_)
This is used by TupleSpace object to set the state of the transaction object to _RUNNING_STATE once a command has been sent.
Parameters:
transState_ - the new state of the transaction object

getTransState

public int getTransState()
Returns the state of this transaction object

setUniqueID

public void setUniqueID(java.lang.String transactionID_)
This function is called after the first command for this Transaction object has been sent to set the unique id for this transaction.
Parameters:
transactionID_ - unique ID for this transaction object
See Also:
TupleSpace.talkToAServer

getUniqueID

public java.lang.String getUniqueID()
This function returns the unique identifier for this transaction. The unique identifier is attached to every comand sent to the T Spaces server. If the caller gets back a null value, it should generate a unique id and call the setUniqueID to get a unique id.
Returns:
unique ID for this transaction object
See Also:
TupleSpace.talkToAServer

generateUniqueID

public static java.lang.String generateUniqueID()
This static class method returns a unique identifier for this transaction. The unique identifier is attached to every comand sent to the T Spaces server.
Parameters:
id - is a string that will be appended to the generated timebased id.
Returns:
unique ID for this transaction object
See Also:
TupleSpace.talkToAServer

seqNumber

public int seqNumber()
Returns a unique number associated with this Transaction instance. This number is part of the unique ID of this transaction object.
See Also:
TupleSpace.talkToAServer