TransactionSingleOp
Date: 2016-02-29

de.zib.scalaris

## Class TransactionSingleOp

- java.lang.Object
- - de.zib.scalaris.AbstractTransaction<TransactionSingleOp.RequestList,TransactionSingleOp.ResultList>
  - - de.zib.scalaris.TransactionSingleOp

-     public class TransactionSingleOp
      extends AbstractTransaction<TransactionSingleOp.RequestList,TransactionSingleOp.ResultList>

  Provides methods to read and write key/value pairs to/from a scalaris ring.

  Each operation is a single transaction. If you are looking for more transactions, use the `Transaction` class instead.

  Instances of this class can be generated using a given connection to a scalaris node (`TransactionSingleOp(Connection)`) or without a connection (`TransactionSingleOp()`) 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)`, `AbstractTransaction.write(OtpErlangString, OtpErlangObject)`
  - using (supported) Java objects: `AbstractTransaction.read(String)`, `AbstractTransaction.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`.

  ### Reading values

         String key;
         OtpErlangString otpKey;

         TransactionSingleOp sc = new TransactionSingleOp();
         String value             = sc.read(key).stringValue(); // AbstractTransaction.read(String)
         OtpErlangObject optValue = sc.read(otpKey).value();    // AbstractTransaction.read(OtpErlangString)

  For the full example, see `TransactionSingleOpReadExample`

  ### Writing values

         String key;
         String value;
         OtpErlangString otpKey;
         OtpErlangString otpValue;

         TransactionSingleOp sc = new TransactionSingleOp();
         sc.write(key, value);             // AbstractTransaction.write(String, Object)
         sc.writeObject(otpKey, otpValue); // AbstractTransaction.write(OtpErlangString, OtpErlangObject)

  For the full example, see `TransactionSingleOpWriteExample`

  ### 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` | `TransactionSingleOp.RequestList` Encapsulates requests that can be used for transactions in `req_list(RequestList)`.
    `static class` | `TransactionSingleOp.ResultList` Encapsulates a list of results as returned by `req_list(RequestList)`.

  - ### Constructor Summary

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `TransactionSingleOp.ResultList` | `req_list(TransactionSingleOp.RequestList req)` Executes all requests in `req` and commits each one of them in a single transaction.
    `TransactionSingleOp.ResultList` | `req_list(TransactionSingleOpOperation op)` Executes the given operation.

    - ### Methods inherited from class de.zib.scalaris.AbstractTransaction

      `addDelOnList, addDelOnList, addOnNr, addOnNr, addOnNr, closeConnection, isCompressed, read, read, setCompressed, testAndSet, testAndSet, write, write`

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### TransactionSingleOp

          public TransactionSingleOp()
                              throws ConnectionException

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

    - #### TransactionSingleOp

          public TransactionSingleOp(Connection conn)

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

  - ### Method Detail

    - #### req_list

          public TransactionSingleOp.ResultList req_list(TransactionSingleOpOperation op)
                                                  throws ConnectionException,
                                                         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
        `UnknownException` - if any other error occurs
      Since:
        3.18
      See Also:
        `req_list(RequestList)`

    - #### req_list

          public TransactionSingleOp.ResultList req_list(TransactionSingleOp.RequestList req)
                                                  throws ConnectionException,
                                                         UnknownException

      Executes all requests in `req` and commits each one of them in a single transaction. NOTE: The execution order of multiple requests on the same key is undefined!
      Specified by:
        `req_list` in class `AbstractTransaction<TransactionSingleOp.RequestList,TransactionSingleOp.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
        `UnknownException` - if any other error occurs