org.neo4j.graphdb.event

Interface TransactionEventHandler<T>

Type Parameters:

T - The type of a state object that the transaction handler can use to pass information from the beforeCommit(TransactionData) event dispatch method to the afterCommit(TransactionData, Object) or afterRollback(TransactionData, Object) method, depending on whether the transaction succeeded or failed.

All Known Implementing Classes:

TransactionEventHandler.Adapter

public interface TransactionEventHandler<T>

An event handler interface for Neo4j Transaction events. Once it has been registered at a GraphDatabaseService instance it will receive events about what has happened in each transaction which is about to be committed and has any data that is accessible via TransactionData. Handlers won't get notified about transactions which hasn't performed any write operation or won't be committed (either if Transaction.success() hasn't been called or the transaction has been marked as failed, Transaction.failure().

Right before a transaction is about to be committed the beforeCommit(TransactionData) method is called with the entire diff of modifications made in the transaction. At this point the transaction is still running so changes can still be made. However there's no guarantee that other handlers will see such changes since the order in which handlers are executed is undefined. This method can also throw an exception and will, in such a case, prevent the transaction from being committed.

If beforeCommit(TransactionData) is successfully executed the transaction will be committed and the afterCommit(TransactionData, Object) method will be called with the same transaction data as well as the object returned from beforeCommit(TransactionData). This assumes that all other handlers (if more were registered) also executed beforeCommit(TransactionData) successfully.

If beforeCommit(TransactionData) isn't executed successfully, but instead throws an exception the transaction won't be committed and a TransactionFailureException will (eventually) be thrown from Transaction.close(). All handlers which at this point have had its beforeCommit(TransactionData) method executed successfully will receive a call to afterRollback(TransactionData, Object).

Author:

Tobias Ivarsson, Mattias Persson

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	TransactionEventHandler.Adapter<T> Adapter for a TransactionEventHandler

Method Summary

Modifier and Type	Method and Description
void	afterCommit(TransactionData data, T state) Invoked after the transaction has been committed successfully.
void	afterRollback(TransactionData data, T state) Invoked after the transaction has been rolled back if committing the transaction failed for some reason.
T	beforeCommit(TransactionData data) Invoked when a transaction that has changes accessible via TransactionData is about to be committed.

Method Detail

beforeCommit

T beforeCommit(TransactionData data)
        throws Exception

Invoked when a transaction that has changes accessible via TransactionData is about to be committed. If this method throws an exception the transaction will be rolled back and a TransactionFailureException will be thrown from Transaction.close(). The transaction is still open when this method is invoked, making it possible to perform mutating operations in this method. This is however highly discouraged since changes made in this method are not guaranteed to be visible by this or other TransactionEventHandlers.

Parameters:

data - the changes that will be committed in this transaction.

Returns:

a state object (or null) that will be passed on to afterCommit(TransactionData, Object) or afterRollback(TransactionData, Object) of this object.

Throws:

Exception - to indicate that the transaction should be rolled back.

afterCommit

void afterCommit(TransactionData data,
                 T state)

Invoked after the transaction has been committed successfully. Any TransactionData being passed in to this method is guaranteed to first have been called with beforeCommit(TransactionData). At the point of calling this method the transaction have been closed and so accessing data outside that of what the TransactionData can provide will require a new transaction to be opened.

Parameters:

data - the changes that were committed in this transaction.

state - the object returned by beforeCommit(TransactionData).

afterRollback

void afterRollback(TransactionData data,
                   T state)

Invoked after the transaction has been rolled back if committing the transaction failed for some reason. Any TransactionData being passed in to this method is guaranteed to first have been called with beforeCommit(TransactionData). At the point of calling this method the transaction have been closed and so accessing data outside that of what the TransactionData can provide will require a new transaction to be opened.

Parameters:

data - the changes that were attempted to be committed in this transaction.

state - the object returned by beforeCommit(TransactionData). If this handler failed when executing beforeCommit(TransactionData) this state will be null.