Package de.zib.scalaris

Class Transaction

java.lang.Object

de.zib.scalaris.AbstractTransaction<Transaction.RequestList,Transaction.ResultList>

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:

• using arbitrary erlang objects extending OtpErlangObject: AbstractTransaction.read(OtpErlangString), write(OtpErlangString, OtpErlangObject)
• using (supported) Java objects: AbstractTransaction.read(String), write(String, Object)

  These types can be accessed from any Scalaris API and translate to each language's native types, e.g. String and OtpErlangString. A list of supported types can be found in the ErlangValue class which will perform the conversion.

  Additional (custom) types can be used by providing a class that extends the ErlangValue class. The user can specify custom behaviour but the correct handling of these values is at the user's hand.

  An example using erlang objects to improve performance for inserting strings is provided by ErlangValueFastString and can be tested by FastStringBenchmark.

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

Nested Classes

Modifier and Type	Class	Description
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

Constructors

Constructor	Description
Transaction()	Constructor, uses the default connection returned by ConnectionFactory.createConnection().
Transaction(Connection conn)	Constructor, uses the given connection to an erlang node.

Method Summary

Modifier and Type	Method	Description
void	abort()	Cancels the current transaction.
void	addDelOnList(com.ericsson.otp.erlang.OtpErlangString key, com.ericsson.otp.erlang.OtpErlangList toAdd, com.ericsson.otp.erlang.OtpErlangList toRemove)	Changes the list stored at the given key, i.e.
<T> void	addDelOnList(java.lang.String key, java.util.List<T> toAdd, java.util.List<T> toRemove)	Changes the list stored at the given key, i.e.
void	addOnNr(com.ericsson.otp.erlang.OtpErlangString key, com.ericsson.otp.erlang.OtpErlangDouble toAdd)	Changes the number stored at the given key, i.e.
void	addOnNr(com.ericsson.otp.erlang.OtpErlangString key, com.ericsson.otp.erlang.OtpErlangLong toAdd)	Changes the number stored at the given key, i.e.
<T> void	addOnNr(java.lang.String key, T toAdd)	Changes the number stored at the given key, i.e.
void	commit()	Commits the current transaction.
Transaction.ResultList	req_list(TransactionOperation op)	Executes the given operation.
Transaction.ResultList	req_list(Transaction.RequestList req)	Executes all requests in req.
void	testAndSet(com.ericsson.otp.erlang.OtpErlangString key, com.ericsson.otp.erlang.OtpErlangObject oldValue, com.ericsson.otp.erlang.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(java.lang.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(com.ericsson.otp.erlang.OtpErlangString key, com.ericsson.otp.erlang.OtpErlangObject value)	Stores the given key/value pair.
<T> void	write(java.lang.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(com.ericsson.otp.erlang.OtpErlangString key,
                  com.ericsson.otp.erlang.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(java.lang.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(com.ericsson.otp.erlang.OtpErlangString key,
                         com.ericsson.otp.erlang.OtpErlangList toAdd,
                         com.ericsson.otp.erlang.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(java.lang.String key,
                             java.util.List<T> toAdd,
                             java.util.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(com.ericsson.otp.erlang.OtpErlangString key,
                    com.ericsson.otp.erlang.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(com.ericsson.otp.erlang.OtpErlangString key,
                    com.ericsson.otp.erlang.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(java.lang.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(com.ericsson.otp.erlang.OtpErlangString key,
                       com.ericsson.otp.erlang.OtpErlangObject oldValue,
                       com.ericsson.otp.erlang.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(java.lang.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)