Module org.cojen.tupl
Package org.cojen.tupl.ext

Interface PrepareHandler

All Superinterfaces:
Handler
public interface PrepareHandler extends Handler
Handler for prepared transactions. Instances which are passed to the prepareHandlers method support recovery, and companion instances for creating prepared transactions are provided by the Database.prepareWriter method.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    prepare(Transaction txn, byte[] message)
    Called to prepare a transaction or to recover one.
    void
    prepareCommit(Transaction txn, byte[] message)
    A prepare variant intended to be called by a two-phase commit coordinator after all participants have prepared their transactions.

    Methods inherited from interface org.cojen.tupl.ext.Handler

    init

  • Method Details

    • prepare

      void prepare(Transaction txn, byte[] message) throws IOException
      Called to prepare a transaction or to recover one. Exclusive locks acquired by the transaction are always recovered, whether they were acquired explicitly or automatically. Shared and upgradable locks aren't recovered.

      When a transaction is initially prepared, non-exclusive locks are released, and the application should attempt to drive the transaction to completion. If the application crashes before this, or if leadership is lost, the recovery handler instance takes over. It will be invoked on the group member which has become the new leader.

      When an UnmodifiableReplicaException is thrown from a commit or rollback operation, this signals that a recovery handler must take over. This exception can also be thrown within recovery, which signals that a replacement recovery will take over. To ensure that the handoff occurs, the reset method must be called on transaction which threw the exception. Failing to do this might require that the application be restarted to unstick the prepared transaction.

      If an UnmodifiableReplicaException is thrown from the recovery handler, the necessary reset is performed automatically. Any other exception is propagated as an uncaught exception, and the prepared transaction might remain in a stuck state.

      Parameters:
      txn - transaction the prepare applies to, which can be modified
      message - optional message
      Throws:
      NullPointerException - if transaction or message is null
      IOException

    • prepareCommit

      void prepareCommit(Transaction txn, byte[] message) throws IOException
      A prepare variant intended to be called by a two-phase commit coordinator after all participants have prepared their transactions. All changes made up to the prepare are effectively committed, their locks are released, and the changes cannot be rolled back. This permits the changes to be observed outside the transaction.

      To fully complete the prepared transaction, a commit operation must still be called to finish it, but only after all participants have committed their transactions. If not finished, the recovery handler will be invoked after each failover. A rollback operation can also finish the prepared transaction, although it will not roll back any changes made before the prepare.

      Strictly speaking, this variant isn't required. The benefit is that a coordinator can perform the second phase of a two-phase commit without its own transaction getting "stuck" while waiting for participants to commit. Another benefit is that no special state needs to encoded in the prepare message to inform the recovery handler that it should act as a coordinator. Being invoked by this method alone is all that's needed.

      Parameters:
      txn - transaction the prepare applies to, which can be modified
      message - optional message
      Throws:
      NullPointerException - if transaction or message is null
      IOException