Module org.firebirdsql.jaybird
Package org.firebirdsql.gds.ng

# Interface FbTransaction

All Superinterfaces:
  `ExceptionListenable`

All Known Subinterfaces:
  `FbWireTransaction`

All Known Implementing Classes:
  `AbstractFbTransaction`, `V10Transaction`

public interface FbTransaction extends ExceptionListenable
Handle for a transaction.

All methods defined in this interface are required to notify all `SQLException` thrown from the methods defined in this interface.

Since:
  3.0
Author:
  Mark Rotteveel

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addTransactionListener(TransactionListener listener)`
  Adds a `TransactionListener` to the list of strongly referenced listeners.
  `void`
  `addWeakTransactionListener(TransactionListener listener)`
  Adds a `TransactionListener` to the list of weakly referenced listeners.
  `void`
  `commit()`
  Commit the transaction
  `int`
  `getHandle()`
  `TransactionState`
  `getState()`
  `long`
  `getTransactionId()`
  Retrieves the transaction id.
  `byte[]`
  `getTransactionInfo(byte[] requestItems, int maxBufferLength)`
  Performs a transaction info request.
  `<T> T`
  `getTransactionInfo(byte[] requestItems, int bufferLength, InfoProcessor<T> infoProcessor)`
  Request transaction info.
  `void`
  `prepare(byte[] recoveryInformation)`
  Prepare the transaction for two-phase commit/rollback.
  `void`
  `removeTransactionListener(TransactionListener listener)`
  Removes the `TransactionListener` from the list of listeners.
  `void`
  `rollback()`
  Roll back the transaction

  ### Methods inherited from interface org.firebirdsql.gds.ng.listeners.ExceptionListenable

  `addExceptionListener, removeExceptionListener`

- ## Method Details

  - ### getState

    TransactionState getState()
    Returns:
      Current transaction state

  - ### getHandle

    int getHandle()
    Returns:
      The Firebird transaction handle identifier

  - ### addTransactionListener

    void addTransactionListener(TransactionListener listener)
    Adds a `TransactionListener` to the list of strongly referenced listeners.
    Parameters:
      `listener` - TransactionListener to register

  - ### addWeakTransactionListener

    void addWeakTransactionListener(TransactionListener listener)
    Adds a `TransactionListener` to the list of weakly referenced listeners.

    If the listener is already strongly referenced, this call will be ignored

    Parameters:
      `listener` - TransactionListener to register

  - ### removeTransactionListener

    void removeTransactionListener(TransactionListener listener)
    Removes the `TransactionListener` from the list of listeners.
    Parameters:
      `listener` - TransactionListener to remove

  - ### commit

    void commit() throws SQLException
    Commit the transaction
    Throws:
      `SQLException`

  - ### rollback

    void rollback() throws SQLException
    Roll back the transaction
    Throws:
      `SQLException`

  - ### prepare

    void prepare(byte[] recoveryInformation) throws SQLException
    Prepare the transaction for two-phase commit/rollback.
    Parameters:
      `recoveryInformation` - Transaction recovery information (stored in RDB$TRANSACTION_DESCRIPTION of RDB$TRANSACTIONS), or `null` to prepare without recovery information.
    Throws:
      `SQLException`

  - ### getTransactionInfo

    <T> T getTransactionInfo(byte[] requestItems, int bufferLength, InfoProcessor<T> infoProcessor) throws SQLException
    Request transaction info.
    Parameters:
      `requestItems` - Array of info items to request
      `bufferLength` - Response buffer length to use
      `infoProcessor` - Implementation of `InfoProcessor` to transform the info response
    Returns:
      Transformed info response of type T
    Throws:
      `SQLException` - For errors retrieving or transforming the response.

  - ### getTransactionInfo

    byte[] getTransactionInfo(byte[] requestItems, int maxBufferLength) throws SQLException
    Performs a transaction info request.
    Parameters:
      `requestItems` - Information items to request
      `maxBufferLength` - Maximum response buffer length to use
    Returns:
      The response buffer (note: length is the actual length of the response, not `maxBufferLength`
    Throws:
      `SQLException` - For errors retrieving the information.

  - ### getTransactionId

    long getTransactionId() throws SQLException
    Retrieves the transaction id.

    The transaction id is the database transaction id, not to be confused with the attachment level transaction handle provided by `getHandle()`.

    Returns:
      Database transaction id.
    Throws:
      `SQLException`