Transaction
Date: 2016-02-29

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

    Constructors
    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.

  - ### Method Summary

    Methods
    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> 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)`