de.zib.scalaris
Class Transaction

java.lang.Object
  extended by de.zib.scalaris.AbstractTransaction<Transaction.RequestList,Transaction.ResultList>
      extended by de.zib.scalaris.Transaction

public class Transaction
extends AbstractTransaction<Transaction.RequestList,Transaction.ResultList>

Provides means to realise a transaction with the scalaris ring using Java.

Instances of this class can be generated using a given connection to a scalaris node using Transaction(Connection) or without a connection (Transaction()) in which case a new connection is created using ConnectionFactory.createConnection().

There are two paradigms for reading and writing values:

Example:

 
   OtpErlangString otpKey;
   OtpErlangString otpValue;
   OtpErlangObject otpResult;

   String key;
   String value;
   String result;

   Transaction t1 = new Transaction();  // Transaction()

   t1.write(key, value);                // write(String, Object)
   t1.write(otpKey, otpValue);          // write(OtpErlangString, OtpErlangObject)

   result = t1.read(key).stringValue(); //AbstractTransaction.read(String)
   otpResult = t1.read(otpKey).value(); //AbstractTransaction.read(OtpErlangString)

   transaction.commit(); // commit()
 
 

For more examples, have a look at TransactionReadExample, TransactionWriteExample and TransactionReadWriteExample.

Connection errors

Errors when setting up connections or trying to send/receive RPCs will be handed to the ConnectionPolicy that has been set when the connection was created. By default, ConnectionFactory uses DefaultConnectionPolicy which implements automatic connection-retries by classifying nodes as good or bad depending on their previous state. The number of automatic retries is adjustable (default: 3).

Since:
2.0
Version:
3.18
Author:
Nico Kruber, kruber@zib.de

Nested Class Summary
static class Transaction.RequestList
          Encapsulates requests that can be used for transactions in req_list(RequestList).
static class Transaction.ResultList
          Encapsulates a list of results as returned by req_list(RequestList).
 
Constructor Summary
Transaction()
          Constructor, uses the default connection returned by ConnectionFactory.createConnection().
Transaction(Connection conn)
          Constructor, uses the given connection to an erlang node.
 
Method Summary
 void abort()
          Cancels the current transaction.
 void addDelOnList(OtpErlangString key, OtpErlangList toAdd, OtpErlangList toRemove)
          Changes the list stored at the given key, i.e.
<T> void
addDelOnList(String key, List<T> toAdd, List<T> toRemove)
          Changes the list stored at the given key, i.e.
 void addOnNr(OtpErlangString key, OtpErlangDouble toAdd)
          Changes the number stored at the given key, i.e.
 void addOnNr(OtpErlangString key, OtpErlangLong toAdd)
          Changes the number stored at the given key, i.e.
<T> void
addOnNr(String key, T toAdd)
          Changes the number stored at the given key, i.e.
 void commit()
          Commits the current transaction.
 Transaction.ResultList req_list(Transaction.RequestList req)
          Executes all requests in req.
 Transaction.ResultList req_list(TransactionOperation op)
          Executes the given operation.
 void testAndSet(OtpErlangString key, OtpErlangObject oldValue, OtpErlangObject newValue)
          Stores the given key/new_value pair if the old value at key is old_value (atomic test_and_set).
<OldT,NewT>
void
testAndSet(String key, OldT oldValue, NewT newValue)
          Stores the given key/new_value pair if the old value at key is old_value (atomic test_and_set).
 void write(OtpErlangString key, OtpErlangObject value)
          Stores the given key/value pair.
<T> void
write(String key, T value)
          Stores the given key/value pair.
 
Methods inherited from class de.zib.scalaris.AbstractTransaction
closeConnection, isCompressed, read, read, setCompressed
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Transaction

public Transaction()
            throws ConnectionException
Constructor, uses the default connection returned by ConnectionFactory.createConnection().

Throws:
ConnectionException - if the connection fails

Transaction

public Transaction(Connection conn)
Constructor, uses the given connection to an erlang node.

Parameters:
conn - connection to use for the transaction
Method Detail

req_list

public Transaction.ResultList req_list(TransactionOperation op)
                                throws ConnectionException,
                                       AbortException,
                                       UnknownException
Executes the given operation.

Parameters:
op - the operation to execute
Returns:
results list containing a single result of the given operation
Throws:
ConnectionException - if the connection is not active or a communication error occurs or an exit signal was received or the remote node sends a message containing an invalid cookie
AbortException - if a commit failed (if there was one)
UnknownException - if any other error occurs
Since:
3.18
See Also:
req_list(RequestList)

req_list

public Transaction.ResultList req_list(Transaction.RequestList req)
                                throws ConnectionException,
                                       AbortException,
                                       UnknownException
Executes all requests in req.

The transaction's log is reset if a commit in the request list was successful, otherwise it still retains in the transaction which must be successfully committed, aborted or reset in order to be (re-)used for another request.

Specified by:
req_list in class AbstractTransaction<Transaction.RequestList,Transaction.ResultList>
Parameters:
req - the requests to issue
Returns:
results of all requests in the same order as they appear in req
Throws:
ConnectionException - if the connection is not active or a communication error occurs or an exit signal was received or the remote node sends a message containing an invalid cookie
AbortException - if the commit failed
UnknownException - if any other error occurs

commit

public void commit()
            throws ConnectionException,
                   AbortException,
                   UnknownException
Commits the current transaction.

The transaction's log is reset if the commit was successful, otherwise it still retains in the transaction which must be successfully committed, aborted or reset in order to be (re-)used for another request.

Throws:
ConnectionException - if the connection is not active or a communication error occurs or an exit signal was received or the remote node sends a message containing an invalid cookie
AbortException - if the commit failed
UnknownException - If the commit fails or the returned value from erlang is of an unknown type/structure, this exception is thrown. Neither the transaction log nor the local operations buffer is emptied, so that the commit can be tried again.
See Also:
abort()

abort

public void abort()
Cancels the current transaction.

For a transaction to be cancelled, only the transLog needs to be reset. Nothing else needs to be done since the data was not modified until the transaction was committed.

See Also:
commit()

write

public void write(OtpErlangString key,
                  OtpErlangObject value)
           throws ConnectionException,
                  UnknownException
Description copied from class: AbstractTransaction
Stores the given key/value pair.

Overrides:
write in class AbstractTransaction<Transaction.RequestList,Transaction.ResultList>
Parameters:
key - the key to store the value for
value - the value to store
Throws:
ConnectionException - if the connection is not active or a communication error occurs or an exit signal was received or the remote node sends a message containing an invalid cookie
UnknownException - if any other error occurs

write

public <T> void write(String key,
                      T value)
           throws ConnectionException,
                  UnknownException
Description copied from class: AbstractTransaction
Stores the given key/value pair.

Overrides:
write in class AbstractTransaction<Transaction.RequestList,Transaction.ResultList>
Type Parameters:
T - the type of the value
Parameters:
key - the key to store the value for
value - the value to store
Throws:
ConnectionException - if the connection is not active or a communication error occurs or an exit signal was received or the remote node sends a message containing an invalid cookie
UnknownException - if any other error occurs
See Also:
AbstractTransaction.write(OtpErlangString, OtpErlangObject)

addDelOnList

public void addDelOnList(OtpErlangString key,
                         OtpErlangList toAdd,
                         OtpErlangList toRemove)
                  throws ConnectionException,
                         NotAListException,
                         UnknownException
Description copied from class: AbstractTransaction
Changes the list stored at the given key, i.e. first adds all items in toAdd then removes all items in toRemove. Assumes en empty list if no value exists at key.

Overrides:
addDelOnList in class AbstractTransaction<Transaction.RequestList,Transaction.ResultList>
Parameters:
key - the key to write the value to
toAdd - a list of values to add to a list
toRemove - a list of values to remove from a list
Throws:
ConnectionException - if the connection is not active or a communication error occurs or an exit signal was received or the remote node sends a message containing an invalid cookie
NotAListException - if the previously stored value was no list
UnknownException - if any other error occurs

addDelOnList

public <T> void addDelOnList(String key,
                             List<T> toAdd,
                             List<T> toRemove)
                  throws ConnectionException,
                         NotAListException,
                         UnknownException
Description copied from class: AbstractTransaction
Changes the list stored at the given key, i.e. first adds all items in toAdd then removes all items in toRemove. Assumes en empty list if no value exists at key.

Overrides:
addDelOnList in class AbstractTransaction<Transaction.RequestList,Transaction.ResultList>
Parameters:
key - the key to write the value to
toAdd - a list of values to add to a list
toRemove - a list of values to remove from a list
Throws:
ConnectionException - if the connection is not active or a communication error occurs or an exit signal was received or the remote node sends a message containing an invalid cookie
NotAListException - if the previously stored value was no list
UnknownException - if any other error occurs
See Also:
AbstractTransaction.addDelOnList(OtpErlangString, OtpErlangList, OtpErlangList)

addOnNr

public void addOnNr(OtpErlangString key,
                    OtpErlangLong toAdd)
             throws ConnectionException,
                    NotANumberException,
                    UnknownException
Description copied from class: AbstractTransaction
Changes the number stored at the given key, i.e. adds some value. Assumes 0 if no value exists at key.

Overrides:
addOnNr in class AbstractTransaction<Transaction.RequestList,Transaction.ResultList>
Parameters:
key - the key to write the value to
toAdd - the number to add to the number stored at key (may also be negative)
Throws:
ConnectionException - if the connection is not active or a communication error occurs or an exit signal was received or the remote node sends a message containing an invalid cookie
NotANumberException - if the previously stored value was no number
UnknownException - if any other error occurs
See Also:
AbstractTransaction.addOnNr_(AddOnNrOp)

addOnNr

public void addOnNr(OtpErlangString key,
                    OtpErlangDouble toAdd)
             throws ConnectionException,
                    NotANumberException,
                    UnknownException
Description copied from class: AbstractTransaction
Changes the number stored at the given key, i.e. adds some value. Assumes 0 if no value exists at key.

Overrides:
addOnNr in class AbstractTransaction<Transaction.RequestList,Transaction.ResultList>
Parameters:
key - the key to write the value to
toAdd - the number to add to the number stored at key (may also be negative)
Throws:
ConnectionException - if the connection is not active or a communication error occurs or an exit signal was received or the remote node sends a message containing an invalid cookie
NotANumberException - if the previously stored value was no number
UnknownException - if any other error occurs
See Also:
AbstractTransaction.addOnNr_(AddOnNrOp)

addOnNr

public <T> void addOnNr(String key,
                        T toAdd)
             throws ConnectionException,
                    NotANumberException,
                    UnknownException
Description copied from class: AbstractTransaction
Changes the number stored at the given key, i.e. adds some value. Assumes 0 if no value exists at key.

Overrides:
addOnNr in class AbstractTransaction<Transaction.RequestList,Transaction.ResultList>
Parameters:
key - the key to write the value to
toAdd - the number to add to the number stored at key (may also be negative)
Throws:
ConnectionException - if the connection is not active or a communication error occurs or an exit signal was received or the remote node sends a message containing an invalid cookie
NotANumberException - if the previously stored value was no number
UnknownException - if any other error occurs
See Also:
AbstractTransaction.addOnNr(OtpErlangString, OtpErlangLong), AbstractTransaction.addOnNr(OtpErlangString, OtpErlangDouble)

testAndSet

public void testAndSet(OtpErlangString key,
                       OtpErlangObject oldValue,
                       OtpErlangObject newValue)
                throws ConnectionException,
                       NotFoundException,
                       KeyChangedException,
                       UnknownException
Description copied from class: AbstractTransaction
Stores the given key/new_value pair if the old value at key is old_value (atomic test_and_set).

Overrides:
testAndSet in class AbstractTransaction<Transaction.RequestList,Transaction.ResultList>
Parameters:
key - the key to store the value for
oldValue - the old value to check
newValue - the value to store
Throws:
ConnectionException - if the connection is not active or a communication error occurs or an exit signal was received or the remote node sends a message containing an invalid cookie
NotFoundException - if the requested key does not exist
KeyChangedException - if the key did not match old_value
UnknownException - if any other error occurs

testAndSet

public <OldT,NewT> void testAndSet(String key,
                                   OldT oldValue,
                                   NewT newValue)
                throws ConnectionException,
                       NotFoundException,
                       KeyChangedException,
                       UnknownException
Description copied from class: AbstractTransaction
Stores the given key/new_value pair if the old value at key is old_value (atomic test_and_set).

Overrides:
testAndSet in class AbstractTransaction<Transaction.RequestList,Transaction.ResultList>
Parameters:
key - the key to store the value for
oldValue - the old value to check
newValue - the value to store
Throws:
ConnectionException - if the connection is not active or a communication error occurs or an exit signal was received or the remote node sends a message containing an invalid cookie
NotFoundException - if the requested key does not exist
KeyChangedException - if the key did not match old_value
UnknownException - if any other error occurs
See Also:
AbstractTransaction.testAndSet(OtpErlangString, OtpErlangObject, OtpErlangObject)