org.hypergraphdb.transaction

Class HGTransactionManager

java.lang.Object

org.hypergraphdb.transaction.HGTransactionManager

public class HGTransactionManager
extends Object

The HGTransactionManager handles transactional activity for a single HyperGraph instance. You can obtain the transaction manager for a HyperGraph by calling its getTransactionManager method.

Author:

Borislav Iordanov

Constructor Summary

Constructors

Constructor and Description
HGTransactionManager(HGTransactionFactory factory) Construct a new transaction manager with the given storage transaction factory.

Method Summary

Methods

Modifier and Type	Method and Description
void	abort() Abort the current transaction by calling endTransaction(false).
void	beginTransaction() Begin a new transaction in the current transaction context.
void	beginTransaction(HGTransactionConfig config) Begin a new transaction in the current transaction context.
void	commit() Commit the current transaction by calling endTransaction(true).
void	disable() Disable transactions - equivalent to setEnabled(false)
void	enable() Enable transactions - equivalent to setEnabled(true).
void	endTransaction(boolean success) Terminate the currently active transaction.
<V> V	ensureTransaction(Callable<V> transaction) Equivalent to ensureTransaction(transaction, HGTransactionConfig.DEFAULT).
<V> V	ensureTransaction(Callable<V> transaction, HGTransactionConfig config) Perform a unit of work encapsulated as a transaction and return the result.
HGTransactionContext	getContext() Return the HGTransactionContext instance associated with the current thread.
HyperGraph	getHyperGraph() Return the HyperGraph instance associated with this HGTransactionManager.
boolean	isEnabled() Return true if the transaction are enabled and false otherwise.
void	setEnabled(boolean enabled) Enable or disable transactions.
void	setHyperGraph(HyperGraph graph) Set the HyperGraph instance associated with this HGTransactionManager.
void	threadAttach(HGTransactionContext tContext) Attach the given transaction context to the current thread.
void	threadDetach() Detach the transaction context bound to the current thread.
<V> V	transact(Callable<V> transaction) Equivalent to transact(transaction, HGTransactionConfig.DEFAULT).
<V> V	transact(Callable<V> transaction, HGTransactionConfig config) Perform a unit of work encapsulated as a transaction and return the result.

Methods inherited from class java.lang.Object

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

Constructor Detail

HGTransactionManager

public HGTransactionManager(HGTransactionFactory factory)

Construct a new transaction manager with the given storage transaction factory. This method is normally called only internally. To obtain the transaction manager bound to a HyperGraph, use HyperGraph.getTransactionManager.

Parameters:

factory - The HGTransactionFactory responsible for fabricating new transactions.

Method Detail

isEnabled

public boolean isEnabled()

Return true if the transaction are enabled and false otherwise.

setEnabled

public void setEnabled(boolean enabled)

Enable or disable transactions. Note that all current transactions will be silently aborted so make sure any pending transactions are completed before calling this method.

Parameters:

enabled - true if transaction must be henceforth enabled and false otherwise.

enable

public void enable()

Enable transactions - equivalent to setEnabled(true).

disable

public void disable()

Disable transactions - equivalent to setEnabled(false)

getContext

public HGTransactionContext getContext()

Return the HGTransactionContext instance associated with the current thread.

setHyperGraph

public void setHyperGraph(HyperGraph graph)

Set the HyperGraph instance associated with this HGTransactionManager. Do not call - used internally during initialization.

getHyperGraph

public HyperGraph getHyperGraph()

Return the HyperGraph instance associated with this HGTransactionManager.

threadAttach

public void threadAttach(HGTransactionContext tContext)

Attach the given transaction context to the current thread. This method is normally called in a server environment. By default, a transaction context will be created and bound to a thread if need be, every time a new transaction is requested. So when HyperGraph is embedded in a client application, there is no need to explicitly attach/detach contexts to threads. However, in an environment using thread pooling such as is common in servers where a single transaction can span multiple requests, use the threadAttach and threadDetach methods to switch transactions contexts bound to clients.

Parameters:

tContext -

threadDetach

public void threadDetach()

Detach the transaction context bound to the current thread. This method is normally called in a server environment. By default, a transaction context will be created and bound to a thread if need be, every time a new transaction is requested. So when HyperGraph is embedded in a client application, there is no need to explicitly attach/detach contexts to threads.

IMPORTANT NOTE: when managing transaction contexts explicitly, you are responsible for closing all pending transactions in the context before disposing of it. This is done by invoking the HGTransactionContext.endAll method.

Parameters:

tContext -

beginTransaction

public void beginTransaction()

Begin a new transaction in the current transaction context. If there's no transaction context bound to the active thread, one will be created.

beginTransaction

public void beginTransaction(HGTransactionConfig config)

Begin a new transaction in the current transaction context. If there's no transaction context bound to the active thread, one will be created.

Parameters:

config - A HGTransactionConfig instance holding configuration parameters for the newly created transaction.

endTransaction

public void endTransaction(boolean success)
                    throws HGTransactionException

Terminate the currently active transaction. The transaction will be aborted or committed based on the success flag (abort when false and commit when true).

You are graced with a HGException if there's no currently active transaction.

Parameters:

success -

Throws:

HGTransactionException

commit

public void commit()

Commit the current transaction by calling endTransaction(true). Wrap the possible HGTransactionException in a HGException.

abort

public void abort()

Abort the current transaction by calling endTransaction(false). Wrap the possible HGTransactionException in a HGException.

ensureTransaction

public <V> V ensureTransaction(Callable<V> transaction)

Equivalent to ensureTransaction(transaction, HGTransactionConfig.DEFAULT).

ensureTransaction

public <V> V ensureTransaction(Callable<V> transaction,
                      HGTransactionConfig config)

Perform a unit of work encapsulated as a transaction and return the result. This method will reuse the currently active transaction if there is one or create a new transaction otherwise.

Type Parameters:

V - The type of the return value.

Parameters:

transaction - The transaction process encapsulated as a Callable instance.

config - The configuration of this transaction - note that if there's a current transaction in effect, this configuration parameter will be ignored as no new transaction will be created.

Returns:

The result of transaction.call().

Throws:

The - method will (re)throw any exception that does not result from a deadlock.

transact

public <V> V transact(Callable<V> transaction)

Equivalent to transact(transaction, HGTransactionConfig.DEFAULT).

transact

public <V> V transact(Callable<V> transaction,
             HGTransactionConfig config)

Perform a unit of work encapsulated as a transaction and return the result. This method explicitly allows deadlock (or write conflicts) to occur and it will re-attempt the transaction in such a case indefinitely. In order for the transaction to eventually complete, the underlying transactional system must be configured to be fair or to prioritize transaction randomly (which is the default behavior).

If the transaction.call() returns without an exception, but the underlying database transaction has already been committed or aborted, this method return without doing anything further. Otherwise, upon a normal return from transaction.call() it will try to commit and re-try indefinitely if the commit fails.

It is important that the transaction.call() doesn't leave any open nested transactions on the transaction stack.

Type Parameters:

V - The type of the return value.

Parameters:

transaction - The transaction process encapsulated as a Callable instance.

config - The transaction configuration parameters.

Returns:

The result of transaction.call() or null if the transaction was aborted by the application by throwing a HGUserAbortException.

Throws:

The - method will (re)throw any exception that does not result from a deadlock.