TransactionalComponent (Apache Jena - DBOE Transactions 3.16.0)

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:
- startRecovery()
- recover(java.nio.ByteBuffer) for each commited/durable transaction (redo actions)
- finishRecovery(), discarding any other transactions (undo actions).
Lifecycle of a read transaction:
- begin(org.apache.jena.dboe.transaction.txn.Transaction)
- complete(org.apache.jena.dboe.transaction.txn.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:: Transaction, TransactionCoordinator

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and 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 Detail
  - 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.

Interface TransactionalComponent

Method Summary

Method Detail

getComponentId

startRecovery

recover

finishRecovery

cleanStart

begin

promote

commitPrepare

commit

commitEnd

abort

complete

detach

attach

shutdown