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

Class TransactionCoordinator

java.lang.Object
org.apache.jena.dboe.transaction.txn.TransactionCoordinator
public final class TransactionCoordinator extends Object
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

    • add

      public TransactionCoordinator add(TransactionalComponent elt)
      Add a TransactionalComponent. Safe to call at any time 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:

    • 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!

    • 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 Location getLocation()

    • detach

      public TransactionCoordinatorState detach(Transaction txn)

    • attach

      public void attach(TransactionCoordinatorState coordinatorState)

    • shutdown

      public void shutdown()

    • shutdown

      public void shutdown(boolean silent)

    • 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.

    • 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.

    • 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.

      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().

    • execExclusive

      public void execExclusive(Runnable action)
      Execute an action in exclusive mode. This method can block. Equivalent to: 
        startExclusiveMode();
  try { action.run(); }
  finally { finishExclusiveMode(); }
      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(TxnType txnType)
      Start a transaction. This may block.

    • begin

      public Transaction begin(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()