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:

• Transaction
• TransactionalComponent
• TransactionalSystem

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	TransactionCoordinator.ShutdownHook

Constructor Summary

Constructors

Constructor	Description
TransactionCoordinator(Journal journal)	Create a TransactionCoordinator, initially with no associated TransactionalComponents.
TransactionCoordinator(Journal journal, 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	addExternal(TransactionalComponent elt)	Add a TransactionalComponent for an external sub-system (e.g.jena-text).
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()
static TransactionCoordinator	create(Location location)	Create a TransactionCoordinator, initially with no associated TransactionalComponents
TransactionCoordinatorState	detach(Transaction txn)
void	enableWriters()	Allow writers.
void	execAsWriter(Runnable action)	Execute an action in as if a Write but no write transaction started.
void	execExclusive(Runnable action)	Execute an action in exclusive mode.
void	finishExclusiveMode()	Return to normal (release waiting transactions, allow new transactions).
void	finishNonExclusiveMode()	End non-exclusive mode.
void	finishReadOnlyDatabase()	Release any waiting potential writers.
Journal	getJournal()
Location	getLocation()
List<TransactionalComponent>	listExternals()	Return a list of external TransactionalComponent, registered via addExternal(org.apache.jena.dboe.transaction.txn.TransactionalComponent).
void	modifyConfig(Runnable action)	Perform modification of this TransactionCoordiator after it has been started.
void	modifyConfigDirect(Runnable action)	Perform modification of this TransactionCoordiator.
TransactionCoordinator	remove(TransactionalComponent elt)	Remove a TransactionalComponent.
void	remove(TransactionCoordinator.ShutdownHook hook)	Remove a shutdown hook
TransactionCoordinator	removeExternal(TransactionalComponent elt)	Remove an external TransactionalComponent registered via addExternal(org.apache.jena.dboe.transaction.txn.TransactionalComponent).
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.
void	startNonExclusiveMode()	Enter non-exclusive mode; block if necessary.
void	startReadOnlyDatabase()	Block write activity - let active potential writers finish while blocking new potential writers.
void	takeOverFrom(TransactionCoordinator other)	Internal operation only.
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.
boolean	tryNonExclusiveMode(boolean canBlock)	Try to enter non-exclusive mode; return true if successful.

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.apache.jena.dboe.transaction.txn.TransactionalSystemControl

execReadOnlyDatabase, tryNonExclusiveMode

Constructor Details

TransactionCoordinator

public TransactionCoordinator(Journal journal)

Create a TransactionCoordinator, initially with no associated TransactionalComponents.

TransactionCoordinator

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

Create a TransactionCoordinator, initially with TransactionalComponents in the ComponentGroup

Method Details

create

public static TransactionCoordinator create(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:

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

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

detach

public TransactionCoordinatorState detach(Transaction txn)

attach

public void attach(TransactionCoordinatorState coordinatorState)

shutdown

public void shutdown()

shutdown

public void shutdown(boolean silent)

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