Package dev.getelements.elements.sdk.dao

Interface Transaction

All Superinterfaces:
AutoCloseable
All Known Implementing Classes:
MorphiaGuiceTransaction
public interface Transaction extends AutoCloseable
Represents a transaction with the underlying datastore. This transaction object is used to acquire DAOs, perform operations and then commit or rollback the transaction. This transaction assumes a snapshot and retry model where transactions may fail due to transient conditions and can be retried safely. When a transaction fails due to a transient condition, the commit() method will throw a Transaction.RetryException. The caller should then rollback the transaction, wait for the recommended delay and then restart and re-execute the entire transaction. Specific implementations may provide additional guarantees, such as serializable isolation, or may not require rollback and retry semantics. Consult the documentation for the specific implementation for details. In such cases, the Transaction.RetryException may never be thrown and code relying on it should be aware that it may not be and handle that case appropriately. Typically this means that the operation will simply be executed once and the exception code is completely vestigial.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static class 
    Transaction.RetryException
    Indicates that a transaction failed due to a transient condition and can be retried safely.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    close()
    Closes and releases the transaction.
    void
    commit()
    Commits the transaction.
    <DaoT> DaoT
    getDao(Class<DaoT> daoT)
    Gets the requested Dao type, bound to this Transaction.
    boolean
    isActive()
    Returns true if this transaction is still active and open.
    default <T> T
    performAndClose(Function<Transaction,T> op)
    Performs the operation on this Transaction, processing the result and returning the result of the operation.
    default void
    performAndCloseV(Consumer<Transaction> op)
    Performs the operation on this Transaction, processing the result and returning the result of the operation.
    void
    rollback()
    Rolls back the transaction undoing any pending changes to the database.
    void
    start()
    Starts the transaction.
    default <T> Function<Transaction,T>
    wrap(Function<Transaction,T> op)
    Optionally, wraps the transaction operation in another Function to properly handle any retry exceptions specific to the transaction's implementation.

  • Method Details

    • getDao

      <DaoT> DaoT getDao(Class<DaoT> daoT)
      Gets the requested Dao type, bound to this Transaction. The returned DAO is only valid for the life of this Transaction object.
      Type Parameters:
      DaoT - the DAO Type
      Parameters:
      daoT - the Class<DaoT>
      Returns:
      the DAO Instance

    • commit

      void commit() throws Transaction.RetryException
      Commits the transaction. In the event the transaction fails due to a transient condition, a Transaction.RetryException is thrown. The caller should then rollback the transaction, wait for the recommended delay and then restart and re-execute the entire transaction.
      Throws:
      Transaction.RetryException - if the transaction failed due to a transient condition and can be retried safely.

    • start

      void start()
      Starts the transaction. Note, transactions are stared automatically when the Transaction object is created so this is only necessary if the transaction has been explicitly aborted via rollback operation.

    • rollback

      void rollback()
      Rolls back the transaction undoing any pending changes to the database.

    • close

      void close()
      Closes and releases the transaction. Once closed, the transaction is no longer active and any DAOs acquired will have undefined behavior if used.
      Specified by:
      close in interface AutoCloseable

    • isActive

      boolean isActive()
      Returns true if this transaction is still active and open.
      Returns:
      true if active, false if it has been committed or rolled back.

    • performAndClose

      default <T> T performAndClose(Function<Transaction,T> op)
      Performs the operation on this Transaction, processing the result and returning the result of the operation. For transactions requiring retry semantics, this method will automatically retry the operation until it succeeds, or fails with an exception other than Transaction.RetryException. The transaction is also closed automatically at the end of the operation regardless of success or failure. For implementations that do not require retry semantics, the operation is simply executed once and the transaction closed. Implementations that do not require retry semantics may provide a more succinct implementation of this default method.
      Type Parameters:
      T - the return type
      Parameters:
      op - the operation
      Returns:
      the result of the operation

    • wrap

      default <T> Function<Transaction,T> wrap(Function<Transaction,T> op)
      Optionally, wraps the transaction operation in another Function to properly handle any retry exceptions specific to the transaction's implementation. This ensures that any executed code will properly honor the semantics of Transaction.RetryException.
      Type Parameters:
      T - the return type
      Parameters:
      op - the operation
      Returns:
      the wrapped function, or the original function

    • performAndCloseV

      default void performAndCloseV(Consumer<Transaction> op)
      Performs the operation on this Transaction, processing the result and returning the result of the operation.
      Parameters:
      op - the operation