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

Class TransactionCoordinator

java.lang.Object

org.apache.jena.dboe.transaction.txn.TransactionCoordinator

public final class TransactionCoordinator
extends java.lang.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:

Transaction, TransactionalComponent, TransactionalSystem

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	TransactionCoordinator.ShutdownHook

Constructor Summary

Constructors

Constructor	Description
TransactionCoordinator(Location location)	Create a TransactionCoordinator, initially with no associated TransactionalComponents
TransactionCoordinator(Journal journal)	Create a TransactionCoordinator, initially with no associated TransactionalComponents.
TransactionCoordinator(Journal journal, java.util.List<TransactionalComponent> components)	Create a TransactionCoordinator, initially with TransactionalComponents in the ComponentGroup

Method Summary

Modifier and Type	Method	Description
TransactionCoordinator	add(TransactionalComponent elt)	Add a TransactionalComponent.
void	add(TransactionCoordinator.ShutdownHook hook)	Add a shutdown hook.
TransactionCoordinator	addListener(TransactionListener listener)
void	attach(TransactionCoordinatorState coordinatorState)
Transaction	begin(TxnType txnType)	Start a transaction.
Transaction	begin(TxnType txnType, boolean canBlock)	Start a transaction.
void	blockWriters()	Block until no writers are active.
long	countActive()
long	countActiveReaders()
long	countActiveWriter()
long	countBegin()
long	countBeginRead()
long	countBeginWrite()
long	countFinished()
TransactionCoordinatorState	detach(Transaction txn)
void	enableWriters()	Allow writers.
void	execAsWriter(java.lang.Runnable action)	Execute an action in as if a Write but no write transaction started.
void	execExclusive(java.lang.Runnable action)	Execute an action in exclusive mode.
void	finishExclusiveMode()	Return to normal (release waiting transactions, allow new transactions).
Journal	getJournal()
Location	getLocation()
void	modifyConfig(java.lang.Runnable action)	Perform modification of this TransactionCoordiator after it has been started.
TransactionCoordinator	remove(TransactionalComponent elt)	Remove a TransactionalComponent.
void	remove(TransactionCoordinator.ShutdownHook hook)	Remove a shutdown hook
TransactionCoordinator	removeListener(TransactionListener listener)
void	setQuorumGenerator(QuorumGenerator qGen)
void	setTxnIdGenerator(TxnIdGenerator generator)
void	shutdown()
void	shutdown(boolean silent)
void	start()
void	startExclusiveMode()	Enter exclusive mode; block if necessary.
boolean	tryBlockWriters()	Try to block all writers, or return if can't at the moment.
boolean	tryBlockWriters(boolean canBlock)	Block until no writers are active, optionally blocking or returning if can't at the moment.
boolean	tryExclusiveMode()	Try to enter exclusive mode.
boolean	tryExclusiveMode(boolean canBlock)	Try to enter exclusive mode.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TransactionCoordinator

public TransactionCoordinator(Location location)

Create a TransactionCoordinator, initially with no associated TransactionalComponents

TransactionCoordinator

public TransactionCoordinator(Journal journal)

Create a TransactionCoordinator, initially with no associated TransactionalComponents.

TransactionCoordinator

public TransactionCoordinator(Journal journal,
                              java.util.List<TransactionalComponent> components)

Create a TransactionCoordinator, initially with TransactionalComponents in the ComponentGroup

Method Detail

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:

add(org.apache.jena.dboe.transaction.txn.TransactionalComponent)

addListener

public TransactionCoordinator addListener(TransactionListener listener)

removeListener

public TransactionCoordinator removeListener(TransactionListener listener)

modifyConfig

public void modifyConfig(java.lang.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(java.lang.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(), enableWriters()

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:

blockWriters(), enableWriters()

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:

blockWriters(), tryBlockWriters()

execAsWriter

public void execAsWriter(java.lang.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()