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

Interface TransactionalComponent

All Known Implementing Classes:
TransactionalComponentBase, TransactionalComponentByLock, 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:

  • begin(org.apache.jena.dboe.transaction.txn.Transaction)
  • commitPrepare(org.apache.jena.dboe.transaction.txn.Transaction)
  • commit(org.apache.jena.dboe.transaction.txn.Transaction) or abort(org.apache.jena.dboe.transaction.txn.Transaction)
  • commitEnd(org.apache.jena.dboe.transaction.txn.Transaction)
  • complete(org.apache.jena.dboe.transaction.txn.Transaction) including abort
    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.