Package org.multiverse.api

## Interface TxnObject

- All Known Subinterfaces:
    `TxnBoolean`, `TxnDouble`, `TxnInteger`, `TxnLong`, `TxnRef<E>`
  All Known Implementing Classes:
    `GammaTxnBoolean`, `GammaTxnDouble`, `GammaTxnInteger`, `GammaTxnLong`, `GammaTxnRef`

      public interface TxnObject

  The interface each transactional object needs to implement.

  A TxnObject is an object where all reads/writes are managed through a `Txn` (unless an atomic method is used).

  Each TxnObject belongs to 1 `Stm` instance.

  All methods are threadsafe.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `String` | `atomicToString()` | Returns a String representation of the object using the provided transaction without looking at a `TxnThreadLocal`.
    `void` | `ensure()` | Does an ensure.
    `void` | `ensure​(Txn self)` | Does an ensure.
    `Lock` | `getLock()` | Gets the `Lock` that belongs to this TxnObject.
    `Stm` | `getStm()` | Returns the `Stm` this TxnObject is part of.
    `long` | `getVersion()` | Returns the current version of the transactional object.
    `String` | `toDebugString()` | Returns a debug representation of the TxnObject.
    `String` | `toString()` | Returns a String representation of the Object using the `Txn` on the `TxnThreadLocal`.
    `String` | `toString​(Txn txn)` | Returns a String representation of the object using the provided `Txn`.

- - ### Method Detail

    - #### getStm

          Stm getStm()

      Returns the `Stm` this TxnObject is part of. Once a TxnObject is created using some Stm, it will never become part of another Stm.
      Returns:
        the Stm this TxnObject is part of. Returned value will never be null.

    - #### getLock

          Lock getLock()

      Gets the `Lock` that belongs to this TxnObject. This call doesn't cause any locking, it only provides access to the object that is able to lock. The returned value will never be null.

      This call also doesn't rely on a `Txn`.

      Returns:
        the Lock
      Throws:
        `UnsupportedOperationException` - if this operation is not supported.

    - #### getVersion

          long getVersion()

      Returns the current version of the transactional object. Each time an update happens, the value is increased. It depends on the stm implementation if the version over references has any meaning. With the MVCC there is a relation, but with the SkySTM isn't.

      This method doesn't look at the `TxnThreadLocal`.

      Returns:
        the current version.

    - #### ensure

          void ensure()

      Does an ensure. What is means is that at the end of the transaction (so deferred), the transaction checks if no other transaction has made an update, if this TxnObject only is read. The ensure is a way to prevent to writeskew problem on the ref level (see `IsolationLevel` for more detail about the writeskew problem}

      This can safely be called on an TxnObject that already is locked, although it doesn't provide much value since with a locked TxnObject, since the writeskew problem can't occur anymore because it can't be changed.

      Unlike the `Lock.acquire(LockMode)` which is pessimistic, ensure is optimistic. This means that a conflict can be detected once the transaction commits.

      This method has no effect if the `Txn` is readonly, because a writeskew is not possible with a readonly transaction.

      This call lifts on the `Txn` stored in the `TxnThreadLocal`.

      Throws:
        `TxnExecutionException`
        `ControlFlowError`
      See Also:
        `ensure(Txn)`

    - #### ensure

          void ensure​(Txn self)

      Does an ensure. What is means is that at the end of the transaction (so deferred), the transaction checks if no other transaction has made an update, if this TxnObject only is read. The ensure is a way to prevent to writeskew problem on the ref level (see `IsolationLevel` for more detail about the writeskew problem}

      This can safely be called on an TxnObject that already is locked, although it doesn't provide much value since with a locked TxnObject, since the writeskew problem can't occur anymore because it can't be changed.

      Unlike the `Lock.acquire(LockMode)` which is pessimistic, ensure is optimistic. This means that a conflict can be detected once the transaction commits.

      This method has no effect if the `Txn` is readonly, because a writeskew is not possible with a readonly transaction.

      Parameters:
        `self` - the Txn this call lifts on.
      Throws:
        `NullPointerException` - if self is null.
        `TxnExecutionException`
        `ControlFlowError`
      See Also:
        `ensure()`

    - #### toDebugString

          String toDebugString()

      Returns a debug representation of the TxnObject. The data used doesn't have to be consistent, it is a best effort. This method doesn't rely on a running transaction.
      Returns:
        the debug representation of the TxnObject.

    - #### toString

          String toString()

      Returns a String representation of the Object using the `Txn` on the `TxnThreadLocal`.
      Overrides:
        `toString` in class `Object`
      Returns:
        the toString representation
      Throws:
        `TxnExecutionException`
        `ControlFlowError`

    - #### toString

          String toString​(Txn txn)

      Returns a String representation of the object using the provided `Txn`.
      Parameters:
        `txn` - the Txn used.
      Returns:
        the String representation of the object.
      Throws:
        `NullPointerException` - if tx is null.
        `ControlFlowError`

    - #### atomicToString

          String atomicToString()

      Returns a String representation of the object using the provided transaction without looking at a `TxnThreadLocal`. The outputted value doesn't need to be consistent from some point in time, only a best effort is made.
      Returns:
        the String representation.