Interface DataConn

public interface DataConn
Represents a data connection participating in transaction lifecycles managed by a DataHub.

Implementations encapsulate connection state and operations for external resources such as relational databases, NoSQL stores, or web services. During a transaction, connections progress through pre-commit, commit, and post-commit phases, and support rollback and failure reporting when errors occur.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static final record 
    DataConn.FailToCommitDataConn
    Represents an error when one or more data connections fail during the commit phase.
    static final record 
    DataConn.FailToPostCommitDataConn
    Represents an error when one or more data connections fail during the post-commit phase.
    static final record 
    DataConn.FailToPreCommitDataConn
    Represents an error when one or more data connections fail during the pre-commit phase.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    close()
    Closes and disposes of this data connection, releasing any held resources.
    void
    commit(AsyncGroup ag)
    Commits changes made through this connection.
    boolean
    isCommitted()
    Checks whether this connection has been successfully committed.
    default void
    onTxnFailure(AsyncGroup ag, List<TxnFailureReport> reports)
    Notifies this connection of a transaction failure with detailed failure reports.
    default void
    postCommit(AsyncGroup ag)
    Performs post-commit operations after all connections in a transaction have successfully committed.
    default void
    preCommit(AsyncGroup ag)
    Prepares this connection for commit prior to the main commit phase.
    void
    rollback(AsyncGroup ag)
    Rolls back changes made through this connection.

  • Method Details

    • commit

      void commit(AsyncGroup ag) throws com.github.sttk.errs.Err
      Commits changes made through this connection.

      Async background tasks may be registered to the provided AsyncGroup during commit processing.

      Parameters:
      ag - the asynchronous group for registering background tasks
      Throws:
      com.github.sttk.errs.Err - if committing the transaction changes fails

    • preCommit

      default void preCommit(AsyncGroup ag) throws com.github.sttk.errs.Err
      Prepares this connection for commit prior to the main commit phase.

      The default implementation does nothing. Subclasses can override this method to perform pre-commit checks or flush pending writes.

      Parameters:
      ag - the asynchronous group for registering background tasks
      Throws:
      com.github.sttk.errs.Err - if pre-commit preparation or validation fails

    • postCommit

      default void postCommit(AsyncGroup ag) throws com.github.sttk.errs.Err
      Performs post-commit operations after all connections in a transaction have successfully committed.

      The default implementation does nothing. Subclasses can override this method to perform cleanup or trigger post-commit notifications.

      Parameters:
      ag - the asynchronous group for registering background tasks
      Throws:
      com.github.sttk.errs.Err - if post-commit processing fails

    • isCommitted

      boolean isCommitted()
      Checks whether this connection has been successfully committed.
      Returns:
      true if this connection was committed; false otherwise

    • rollback

      void rollback(AsyncGroup ag) throws com.github.sttk.errs.Err
      Rolls back changes made through this connection.

      This method is invoked when a transaction fails and must restore the connection or underlying storage to its pre-transaction state.

      Parameters:
      ag - the asynchronous group for registering background tasks
      Throws:
      com.github.sttk.errs.Err - if rolling back connection changes fails

    • onTxnFailure

      default void onTxnFailure(AsyncGroup ag, List<TxnFailureReport> reports)
      Notifies this connection of a transaction failure with detailed failure reports.

      The default implementation does nothing. Implementations can inspect failure reports to log diagnostics or take recovery actions.

      Parameters:
      ag - the asynchronous group for registering background tasks
      reports - the list of transaction failure reports

    • close

      void close()
      Closes and disposes of this data connection, releasing any held resources.