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

Class TransactionCoordinator

java.lang.Object
org.apache.jena.dboe.transaction.txn.TransactionCoordinator
All Implemented Interfaces:
TransactionalSystemControl
public final class TransactionCoordinator extends Object implements TransactionalSystemControl
One TransactionCoordinator per group of TransactionalComponents. TransactionalComponents can not be shared across TransactionCoordinators.

This is a general engine although tested and most used for multiple-reader and single-writer (MR+SW). TransactionalComponentLifecycle provides the per-thread style.

Contrast to MRSW: multiple-reader or single-writer.

Block writers

Block until no writers are active. When this returns, this guarantees that the database is not changing and the journal is flushed to disk.

See blockWriters(), enableWriters(), execAsWriter(Runnable)

Exclusive mode

Exclusive mode is when the current thread is the only active code : no readers, no writers.

See startExclusiveMode()/tryExclusiveMode() finishExclusiveMode(), execExclusive(Runnable)

See Also:

  • Constructor Details

  • Method Details

    • create

      public static TransactionCoordinator create(org.apache.jena.dboe.base.file.Location location)
      Create a TransactionCoordinator, initially with no associated TransactionalComponents

    • takeOverFrom

      public void takeOverFrom(TransactionCoordinator other)
      Internal operation only. Call only when no write or potential writer transaction is active in either coordinator.

    • add

      public TransactionCoordinator add(TransactionalComponent elt)
      Add a TransactionalComponent. Safe to call at any time (via modifyConfig(java.lang.Runnable)) but it is good practice is to add all the components before any transactions start. Internally, the coordinator ensures the add will safely happen but it does not add the component to existing transactions. This must be setup before recovery is attempted.

    • remove

      public TransactionCoordinator remove(TransactionalComponent elt)
      Remove a TransactionalComponent.
      See Also:

    • addExternal

      public TransactionCoordinator addExternal(TransactionalComponent elt)
      Add a TransactionalComponent for an external sub-system (e.g.jena-text). The component will be transfered to any TransactionCoordinator created when switching (for example, by compaction). Use with modifyConfig(java.lang.Runnable).

    • removeExternal

      public TransactionCoordinator removeExternal(TransactionalComponent elt)
      Remove an external TransactionalComponent registered via addExternal(org.apache.jena.dboe.transaction.txn.TransactionalComponent).

    • listExternals

      public List<TransactionalComponent> listExternals()
      Return a list of external TransactionalComponent, registered via addExternal(org.apache.jena.dboe.transaction.txn.TransactionalComponent). Changing this list has no effect on the TrasnactionCooridnator.

    • addListener

      public TransactionCoordinator addListener(TransactionListener listener)

    • removeListener

      public TransactionCoordinator removeListener(TransactionListener listener)

    • modifyConfig

      public void modifyConfig(Runnable action)
      Perform modification of this TransactionCoordiator after it has been started.

      This operation enters exclusive mode, releases the configuration lock, then calls the action. On exit from the action, it resets the configuration lock, and exits exclusive mode.

      Do not call inside a transaction, it may cause a deadlock.

      Use with care!

    • modifyConfigDirect

      public void modifyConfigDirect(Runnable action)
      Perform modification of this TransactionCoordiator.

      The caller must use exclusive mode (e.g. #execExclusive(Runnable)).

      Do not call inside a transaction, it may cause a deadlock.

      Use with care!

    • add

      public void add(TransactionCoordinator.ShutdownHook hook)
      Add a shutdown hook. Shutdown is not guaranteed to be called and hence hooks may not get called.

    • remove

      public void remove(TransactionCoordinator.ShutdownHook hook)
      Remove a shutdown hook

    • setQuorumGenerator

      public void setQuorumGenerator(QuorumGenerator qGen)

    • start

      public void start()

    • setTxnIdGenerator

      public void setTxnIdGenerator(TxnIdGenerator generator)

    • getJournal

      public Journal getJournal()

    • getLocation

      public org.apache.jena.dboe.base.file.Location getLocation()

    • detach

      public TransactionCoordinatorState detach(Transaction txn)

    • attach

      public void attach(TransactionCoordinatorState coordinatorState)

    • shutdown

      public void shutdown()
      Shutdown the coordinator; this operation does not check the state of the transaction system.

      It expects the caller to decide when to shutdown; maybe waiting for all transactions to finish or maybe forcing the system to shutdown for some reason, causing later transaction exceptions.

      Use inside exclusive mode to be sure no active transaction are present.

    • shutdown

      public void shutdown(boolean silent)
      Shutdown the coordinator; this operation does not check the state of the transaction system.

      It expects the caller to decide when to shutdown; maybe waiting for all transactions to finish or maybe forcing the system to shutdown for some reason, causing later transaction exceptions.

      Use inside exclusive mode to be sure no active transaction are present.

    • startReadOnlyDatabase

      public void startReadOnlyDatabase()
      Description copied from interface: TransactionalSystemControl
      Block write activity - let active potential writers finish while blocking new potential writers. On exit, there are no active writers or promote transactions. (Promotes would otherwise become write mode in their lifetime.)
      Specified by:
      startReadOnlyDatabase in interface TransactionalSystemControl

    • finishReadOnlyDatabase

      public void finishReadOnlyDatabase()
      Description copied from interface: TransactionalSystemControl
      Release any waiting potential writers.
      Specified by:
      finishReadOnlyDatabase in interface TransactionalSystemControl

    • startNonExclusiveMode

      public void startNonExclusiveMode()
      Description copied from interface: TransactionalSystemControl
      Enter non-exclusive mode; block if necessary.
      Specified by:
      startNonExclusiveMode in interface TransactionalSystemControl

    • tryNonExclusiveMode

      public boolean tryNonExclusiveMode(boolean canBlock)
      Description copied from interface: TransactionalSystemControl
      Try to enter non-exclusive mode; return true if successful.
      Specified by:
      tryNonExclusiveMode in interface TransactionalSystemControl

    • finishNonExclusiveMode

      public void finishNonExclusiveMode()
      Description copied from interface: TransactionalSystemControl
      End non-exclusive mode.
      Specified by:
      finishNonExclusiveMode in interface TransactionalSystemControl

    • startExclusiveMode

      public void startExclusiveMode()
      Enter exclusive mode; block if necessary. There are no active transactions on return; new transactions will be held up in 'begin'. Return to normal (release waiting transactions, allow new transactions) with finishExclusiveMode().

      Do not call inside an existing transaction.

      Specified by:
      startExclusiveMode in interface TransactionalSystemControl

    • tryExclusiveMode

      public boolean tryExclusiveMode()
      Try to enter exclusive mode. If return is true, then there are no active transactions on return and new transactions will be held up in 'begin'. If false, there were in-progress transactions. Return to normal (release waiting transactions, allow new transactions) with finishExclusiveMode().

      Do not call inside an existing transaction.

      Specified by:
      tryExclusiveMode in interface TransactionalSystemControl

    • tryExclusiveMode

      public boolean tryExclusiveMode(boolean canBlock)
      Try to enter exclusive mode. If return is true, then there are no active transactions on return and new transactions will be held up in 'begin'. If false, there were in-progress transactions. Return to normal (release waiting transactions, allow new transactions) with finishExclusiveMode().

      Do not call inside an existing transaction.

      Specified by:
      tryExclusiveMode in interface TransactionalSystemControl
      Parameters:
      canBlock - Allow the operation block and wait for the exclusive mode lock.

    • finishExclusiveMode

      public void finishExclusiveMode()
      Return to normal (release waiting transactions, allow new transactions). Must be paired with an earlier startExclusiveMode().
      Specified by:
      finishExclusiveMode in interface TransactionalSystemControl

    • execExclusive

      public void execExclusive(Runnable action)
      Execute an action in exclusive mode. This method can block. Equivalent to: 
        startExclusiveMode();
  try { action.run(); }
  finally { finishExclusiveMode(); }
      Specified by:
      execExclusive in interface TransactionalSystemControl
      Parameters:
      action -

    • blockWriters

      public void blockWriters()
      Block until no writers are active. When this returns, this guarantees that the database is not changing and the journal is flushed to disk.

      The application must call enableWriters() later.

      This operation must not be nested (it will block).

      See Also:

    • tryBlockWriters

      public boolean tryBlockWriters()
      Try to block all writers, or return if can't at the moment.

      Unlike a write transaction, there is no associated transaction.

      If it returns true, the application must call enableWriters() later.

      Returns:
      true if the operation succeeded and writers are blocked
      See Also:

    • tryBlockWriters

      public boolean tryBlockWriters(boolean canBlock)
      Block until no writers are active, optionally blocking or returning if can't at the moment.

      Unlike a write transaction, there is no associated transaction.

      If it returns true, the application must call enableWriters() later.

      Parameters:
      canBlock -
      Returns:
      true if the operation succeeded and writers are blocked

    • enableWriters

      public void enableWriters()
      Allow writers. This must be used in conjunction with blockWriters() or tryBlockWriters()
      See Also:

    • execAsWriter

      public void execAsWriter(Runnable action)
      Execute an action in as if a Write but no write transaction started. This method can block.

      Equivalent to: 

        blockWriters();
  try { action.run(); }
  finally { enableWriters(); }
      Parameters:
      action -

    • begin

      public Transaction begin(org.apache.jena.query.TxnType txnType)
      Start a transaction. This may block.

    • begin

      public Transaction begin(org.apache.jena.query.TxnType txnType, boolean canBlock)
      Start a transaction. Returns null if this operation would block. Readers can start at any time. A single writer policy is currently imposed so a "begin(WRITE)" may block.

    • countActiveReaders

      public long countActiveReaders()

    • countActiveWriter

      public long countActiveWriter()

    • countActive

      public long countActive()

    • countBegin

      public long countBegin()

    • countBeginRead

      public long countBeginRead()

    • countBeginWrite

      public long countBeginWrite()

    • countFinished

      public long countFinished()