Module org.apache.jena.dboe.transaction
Package org.apache.jena.dboe.transaction.txn

Interface TransactionalComponent

All Known Implementing Classes:
TransactionalComponentBase, TransactionalComponentByLock, TransactionalComponentExternal, TransactionalComponentLifecycle, TransactionalComponentWrapper, TransInteger, TransLogger, TransMonitor
public interface TransactionalComponent
Interface that for components of a transaction system.


The TransactionCoordinator manages a number of components which provide the TransactionalComponent interface.


When a new coordinator starts, typically being when the in-process system starts, there is a recovery phase when work from a previous coordinator is recovered. Transactions were either were properly committed by the previous coordinator, and hence redo actions (finalization) should be done, or they were not, in which case undo actions may be needed. Transctions to discard are not notified, only fully committed transaction are notified during recovery. The component may need to keepit's own record of undo actions needed across restarts.


Lifecycle of startup:


Lifecycle of a read transaction:


A read transaction may also include commit or abort lifecycles. commitPrepare(org.apache.jena.dboe.transaction.txn.Transaction) and commitEnd(org.apache.jena.dboe.transaction.txn.Transaction) are not called.


Lifecycle of a write transaction:


or if the application aborts the transaction:

complete(org.apache.jena.dboe.transaction.txn.Transaction) may be called out of sequence and it forces an abort if before commitPrepare(org.apache.jena.dboe.transaction.txn.Transaction). Once commitPrepare(org.apache.jena.dboe.transaction.txn.Transaction) has been called, the component can not decide whether to commit finally or to cause a system abort; it must wait for the coordinator. After commitEnd(org.apache.jena.dboe.transaction.txn.Transaction), the coordinator has definitely commited the overall transaction and local prepared state can be released, and changes made to the permanent state of the component.

See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    abort(Transaction transaction)
    Abort a transaction (undo the effect of a transaction)
    void
    attach(SysTransState systemState)
    Set the current thread to be in the transaction.
    void
    begin(Transaction transaction)
    Start a transaction; return an identifier for this components use.
    void
    cleanStart()
    Indicate that no recovery is being done (the journal thinks everything was completed last time)
    void
    commit(Transaction transaction)
    Commit a transaction (make durable).
    void
    commitEnd(Transaction transaction)
    Signal all commits on all components are done and replay from the journal will not happen.
    ByteBuffer
    commitPrepare(Transaction transaction)
    Prepare for a commit.
    void
    complete(Transaction transaction)
    Finalization - the coordinator will not mention the transaction again.
    SysTransState
    detach()
    Detach this component from the transaction of the current thread and return some internal state that can be used in a future call of attach(SysTransState)
    void
    finishRecovery()
    End of the recovery phase
    ComponentId
    getComponentId()
    Every component instance must supplied a unique number.
    boolean
    promote(Transaction transaction)
    Promote a component in a transaction.
    void
    recover(ByteBuffer ref)
    Notification that ref was really committed and is being recovered.
    void
    shutdown()
    Shutdown component, aborting any in-progress transactions.
    void
    startRecovery()
     

  • Method Details

    • getComponentId

      ComponentId getComponentId()
      Every component instance must supplied a unique number. It is used to route journal entries to subsystems, including across restarts/recovery. Uniqueness scope is within the same TransactionCoordinator, and the same across restarts.

      If a component imposes the rule of one-per-TransactionCoordinator, the same number can be used (if different from all other component type instances).

      If a component can have multiple instances per TransactionCoordinator, for example indexes, each must have a unique instance id.

    • startRecovery

      void startRecovery()

    • recover

      void recover(ByteBuffer ref)
      Notification that ref was really committed and is being recovered.
      Parameters:
      ref - Same bytes as were written during prepare originally.

    • finishRecovery

      void finishRecovery()
      End of the recovery phase

    • cleanStart

      void cleanStart()
      Indicate that no recovery is being done (the journal thinks everything was completed last time)

    • begin

      void begin(Transaction transaction)
      Start a transaction; return an identifier for this components use.

    • promote

      boolean promote(Transaction transaction)
      Promote a component in a transaction.

      May return "false" for "can't do that" if the transaction can not be promoted.

      May throw UnsupportedOperationException if promotion is not supported.

    • commitPrepare

      ByteBuffer commitPrepare(Transaction transaction)
      Prepare for a commit. Returns some bytes that will be written to the journal. The journal remains valid until commitEnd(org.apache.jena.dboe.transaction.txn.Transaction) is called.

    • commit

      void commit(Transaction transaction)
      Commit a transaction (make durable). The transaction will commit and not abort. Other components may not have committed yet and recovery may occur still causing replay of the commit step.

    • commitEnd

      void commitEnd(Transaction transaction)
      Signal all commits on all components are done and replay from the journal will not happen. The component can clear up now.

    • abort

      void abort(Transaction transaction)
      Abort a transaction (undo the effect of a transaction)

    • complete

      void complete(Transaction transaction)
      Finalization - the coordinator will not mention the transaction again.

    • detach

      SysTransState detach()
      Detach this component from the transaction of the current thread and return some internal state that can be used in a future call of attach(SysTransState)

      After this call, the component is not in a transaction but the existing transaction still exists. The thread may start a new transaction; that transaction is completely independent of the detached transaction.

      Returns null if the current thread not in a transaction. The component may return null to indicate it has no state. The return system state should be used in a call to attach(SysTransState) and the transaction ended in the usual way.

    • attach

      void attach(SysTransState systemState)
      Set the current thread to be in the transaction. The systemState must be obtained from a call of detach(). This method can only be called once per systemState.

    • shutdown

      void shutdown()
      Shutdown component, aborting any in-progress transactions. This operation is not guaranteed to be called.