public class Transaction extends AbstractTransaction<Transaction.RequestList,Transaction.ResultList>
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:
AbstractTransaction.read(OtpErlangString)
,
write(OtpErlangString, OtpErlangObject)
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
.
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
.
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).Modifier and Type | Class and 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 and Description |
---|
Transaction()
Constructor, uses the default connection returned by
ConnectionFactory.createConnection() . |
Transaction(Connection conn)
Constructor, uses the given connection to an erlang node.
|
Modifier and Type | Method and Description |
---|---|
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> |
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. |
closeConnection, isCompressed, read, read, setCompressed
public Transaction() throws ConnectionException
ConnectionFactory.createConnection()
.ConnectionException
- if the connection failspublic Transaction(Connection conn)
conn
- connection to use for the transactionpublic Transaction.ResultList req_list(TransactionOperation op) throws ConnectionException, AbortException, UnknownException
op
- the operation to executeConnectionException
- 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 cookieAbortException
- if a commit failed (if there was one)UnknownException
- if any other error occursreq_list(RequestList)
public Transaction.ResultList req_list(Transaction.RequestList req) throws ConnectionException, AbortException, UnknownException
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.
req_list
in class AbstractTransaction<Transaction.RequestList,Transaction.ResultList>
req
- the requests to issuereq
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 cookieAbortException
- if the commit failedUnknownException
- if any other error occurspublic void commit() throws ConnectionException, AbortException, UnknownException
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.
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 cookieAbortException
- if the commit failedUnknownException
- 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.abort()
public void abort()
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.
commit()
public void write(OtpErlangString key, OtpErlangObject value) throws ConnectionException, UnknownException
AbstractTransaction
key
/value
pair.write
in class AbstractTransaction<Transaction.RequestList,Transaction.ResultList>
key
- the key to store the value forvalue
- the value to storeConnectionException
- 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 cookieUnknownException
- if any other error occurspublic <T> void write(String key, T value) throws ConnectionException, UnknownException
AbstractTransaction
key
/value
pair.write
in class AbstractTransaction<Transaction.RequestList,Transaction.ResultList>
T
- the type of the valuekey
- the key to store the value forvalue
- the value to storeConnectionException
- 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 cookieUnknownException
- if any other error occursAbstractTransaction.write(OtpErlangString, OtpErlangObject)
public void addDelOnList(OtpErlangString key, OtpErlangList toAdd, OtpErlangList toRemove) throws ConnectionException, NotAListException, UnknownException
AbstractTransaction
addDelOnList
in class AbstractTransaction<Transaction.RequestList,Transaction.ResultList>
key
- the key to write the value totoAdd
- a list of values to add to a listtoRemove
- a list of values to remove from a listConnectionException
- 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 cookieNotAListException
- if the previously stored value was no listUnknownException
- if any other error occurspublic <T> void addDelOnList(String key, List<T> toAdd, List<T> toRemove) throws ConnectionException, NotAListException, UnknownException
AbstractTransaction
addDelOnList
in class AbstractTransaction<Transaction.RequestList,Transaction.ResultList>
key
- the key to write the value totoAdd
- a list of values to add to a listtoRemove
- a list of values to remove from a listConnectionException
- 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 cookieNotAListException
- if the previously stored value was no listUnknownException
- if any other error occursAbstractTransaction.addDelOnList(OtpErlangString, OtpErlangList, OtpErlangList)
public void addOnNr(OtpErlangString key, OtpErlangLong toAdd) throws ConnectionException, NotANumberException, UnknownException
AbstractTransaction
addOnNr
in class AbstractTransaction<Transaction.RequestList,Transaction.ResultList>
key
- the key to write the value totoAdd
- the number to add to the number stored at key (may also be
negative)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 cookieNotANumberException
- if the previously stored value was no numberUnknownException
- if any other error occursAbstractTransaction.addOnNr_(AddOnNrOp)
public void addOnNr(OtpErlangString key, OtpErlangDouble toAdd) throws ConnectionException, NotANumberException, UnknownException
AbstractTransaction
addOnNr
in class AbstractTransaction<Transaction.RequestList,Transaction.ResultList>
key
- the key to write the value totoAdd
- the number to add to the number stored at key (may also be
negative)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 cookieNotANumberException
- if the previously stored value was no numberUnknownException
- if any other error occursAbstractTransaction.addOnNr_(AddOnNrOp)
public <T> void addOnNr(String key, T toAdd) throws ConnectionException, NotANumberException, UnknownException
AbstractTransaction
addOnNr
in class AbstractTransaction<Transaction.RequestList,Transaction.ResultList>
key
- the key to write the value totoAdd
- the number to add to the number stored at key (may also be
negative)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 cookieNotANumberException
- if the previously stored value was no numberUnknownException
- if any other error occursAbstractTransaction.addOnNr(OtpErlangString, OtpErlangLong)
,
AbstractTransaction.addOnNr(OtpErlangString, OtpErlangDouble)
public void testAndSet(OtpErlangString key, OtpErlangObject oldValue, OtpErlangObject newValue) throws ConnectionException, NotFoundException, KeyChangedException, UnknownException
AbstractTransaction
testAndSet
in class AbstractTransaction<Transaction.RequestList,Transaction.ResultList>
key
- the key to store the value foroldValue
- the old value to checknewValue
- the value to storeConnectionException
- 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 cookieNotFoundException
- if the requested key does not existKeyChangedException
- if the key did not match old_valueUnknownException
- if any other error occurspublic <OldT,NewT> void testAndSet(String key, OldT oldValue, NewT newValue) throws ConnectionException, NotFoundException, KeyChangedException, UnknownException
AbstractTransaction
testAndSet
in class AbstractTransaction<Transaction.RequestList,Transaction.ResultList>
key
- the key to store the value foroldValue
- the old value to checknewValue
- the value to storeConnectionException
- 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 cookieNotFoundException
- if the requested key does not existKeyChangedException
- if the key did not match old_valueUnknownException
- if any other error occursAbstractTransaction.testAndSet(OtpErlangString, OtpErlangObject, OtpErlangObject)