AbstractTransaction
Date: 2016-02-29

de.zib.scalaris

## Class AbstractTransaction<ReqL extends RequestList,ResL extends ResultList>

- java.lang.Object
- - de.zib.scalaris.AbstractTransaction<ReqL,ResL>

- Type Parameters:
    `ReqL` - `RequestList` type
    `ResL` - `ResultList` type
  Direct Known Subclasses:
    Transaction, TransactionSingleOp

      public abstract class AbstractTransaction<ReqL extends RequestList,ResL extends ResultList>
      extends Object

  Generic base class for `Transaction` and `TransactionSingleOp`.
  Since:
    3.14
  Version:
    3.18
  Author:
    Nico Kruber, kruber@zib.de

- - ### Constructor Summary

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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` | `closeConnection()` Closes the transaction's connection to a scalaris node.
    `boolean` | `isCompressed()` Checks whether the transfer of values is compressed or not.
    `ErlangValue` | `read(OtpErlangString key)` Gets the value stored under the given `key`.
    `ErlangValue` | `read(String key)` Gets the value stored under the given `key`.
    `abstract ResL` | `req_list(ReqL req)` Executes all requests in `req`.
    `void` | `setCompressed(boolean compressed)` Sets whether to compress the transfer of values or not.
    `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 java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### AbstractTransaction

          public AbstractTransaction()
                              throws ConnectionException

      Constructor, uses the default connection returned by `ConnectionFactory.createConnection()`.
      Throws:
        `ConnectionException` - if the connection fails

    - #### AbstractTransaction

          public AbstractTransaction(Connection conn)

      Constructor, uses the given connection to an erlang node.
      Parameters:
        `conn` - connection to use for the transaction

  - ### Method Detail

    - #### req_list

          public abstract ResL req_list(ReqL 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.

      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 a commit failed (if there was one)
        `UnknownException` - if any other error occurs

    - #### read

          public ErlangValue read(OtpErlangString key)
                           throws ConnectionException,
                                  NotFoundException,
                                  UnknownException

      Gets the value stored under the given `key`.
      Parameters:
        `key` - the key to look up
      Returns:
        the value stored under the given `key`
      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
        `UnknownException` - if any other error occurs
      Since:
        2.9

    - #### read

          public ErlangValue read(String key)
                           throws ConnectionException,
                                  NotFoundException,
                                  UnknownException

      Gets the value stored under the given `key`.
      Parameters:
        `key` - the key to look up
      Returns:
        the value stored under the given `key`
      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
        `UnknownException` - if any other error occurs
      Since:
        2.9
      See Also:
        `read(OtpErlangString)`

    - #### write

          public void write(OtpErlangString key,
                   OtpErlangObject value)
                     throws ConnectionException,
                            AbortException,
                            UnknownException

      Stores the given `key`/`value` pair.
      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
        `AbortException` - if the commit failed (if there was one)
        `UnknownException` - if any other error occurs
      Since:
        2.9

    - #### write

          public <T> void write(String key,
                       T value)
                     throws ConnectionException,
                            AbortException,
                            UnknownException

      Stores the given `key`/`value` pair.
      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
        `AbortException` - if the commit failed (if there was one)
        `UnknownException` - if any other error occurs
      Since:
        2.9
      See Also:
        `write(OtpErlangString, OtpErlangObject)`

    - #### addDelOnList

          public void addDelOnList(OtpErlangString key,
                          OtpErlangList toAdd,
                          OtpErlangList toRemove)
                            throws ConnectionException,
                                   NotAListException,
                                   AbortException,
                                   UnknownException

      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`.
      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
        `AbortException` - if the commit failed (if there was one)
        `UnknownException` - if any other error occurs
      Since:
        3.9

    - #### addDelOnList

          public <T> void addDelOnList(String key,
                              List<T> toAdd,
                              List<T> toRemove)
                            throws ConnectionException,
                                   NotAListException,
                                   AbortException,
                                   UnknownException

      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`.
      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
        `AbortException` - if the commit failed (if there was one)
        `UnknownException` - if any other error occurs
      Since:
        3.9
      See Also:
        `addDelOnList(OtpErlangString, OtpErlangList, OtpErlangList)`

    - #### addOnNr

          public void addOnNr(OtpErlangString key,
                     OtpErlangLong toAdd)
                       throws ConnectionException,
                              NotANumberException,
                              AbortException,
                              UnknownException

      Changes the number stored at the given key, i.e. adds some value. Assumes `0` if no value exists at `key`.
      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
        `AbortException` - if the commit failed (if there was one)
        `UnknownException` - if any other error occurs
      Since:
        3.9
      See Also:
        `addOnNr_(AddOnNrOp)`

    - #### addOnNr

          public void addOnNr(OtpErlangString key,
                     OtpErlangDouble toAdd)
                       throws ConnectionException,
                              NotANumberException,
                              AbortException,
                              UnknownException

      Changes the number stored at the given key, i.e. adds some value. Assumes `0` if no value exists at `key`.
      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
        `AbortException` - if the commit failed (if there was one)
        `UnknownException` - if any other error occurs
      Since:
        3.9
      See Also:
        `addOnNr_(AddOnNrOp)`

    - #### addOnNr

          public <T> void addOnNr(String key,
                         T toAdd)
                       throws ConnectionException,
                              NotANumberException,
                              AbortException,
                              UnknownException

      Changes the number stored at the given key, i.e. adds some value. Assumes `0` if no value exists at `key`.
      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
        `AbortException` - if the commit failed (if there was one)
        `UnknownException` - if any other error occurs
      Since:
        3.9
      See Also:
        `addOnNr(OtpErlangString, OtpErlangLong)`, `addOnNr(OtpErlangString, OtpErlangDouble)`

    - #### testAndSet

          public void testAndSet(OtpErlangString key,
                        OtpErlangObject oldValue,
                        OtpErlangObject newValue)
                          throws ConnectionException,
                                 NotFoundException,
                                 KeyChangedException,
                                 AbortException,
                                 UnknownException

      Stores the given `key`/`new_value` pair if the old value at `key` is `old_value` (atomic test_and_set).
      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`
        `AbortException` - if the commit failed (if there was one)
        `UnknownException` - if any other error occurs
      Since:
        3.9

    - #### testAndSet

          public <OldT,NewT> void testAndSet(String key,
                                    OldT oldValue,
                                    NewT newValue)
                          throws ConnectionException,
                                 NotFoundException,
                                 KeyChangedException,
                                 AbortException,
                                 UnknownException

      Stores the given `key`/`new_value` pair if the old value at `key` is `old_value` (atomic test_and_set).
      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`
        `AbortException` - if the commit failed (if there was one)
        `UnknownException` - if any other error occurs
      Since:
        3.9
      See Also:
        `testAndSet(OtpErlangString, OtpErlangObject, OtpErlangObject)`

    - #### closeConnection

          public void closeConnection()

      Closes the transaction's connection to a scalaris node. Note: Subsequent calls to the other methods will throw `ConnectionException`s!

    - #### isCompressed

          public boolean isCompressed()

      Checks whether the transfer of values is compressed or not.
      Returns:
        `true` if compressed, otherwise `false`
      Since:
        3.14

    - #### setCompressed

          public void setCompressed(boolean compressed)

      Sets whether to compress the transfer of values or not.
      Parameters:
        `compressed` - `true` if compressed, otherwise `false`
      Since:
        3.14