org.nuxeo.ecm.core.event
Interface EventService

All Superinterfaces:

EventProducer

All Known Implementing Classes:

EventServiceImpl

public interface EventService
extends EventProducer

The event service manages listener registries and notifies listeners about core events.

The service is able to run in a transactional mode where all events are recorded and fired after the transaction commits in one step as an event bundle.

To start a transaction, the framework calls the transactionStarted() method, and at transaction commit the framework calls transactionCommitted() to fire the event bundle. Upon rollback the framework callstransactionRolledback() to clean up recorded events.

Events are recorded in a thread variable so they are valid only in the current thread.

An event marked Event.isInline() is dispatched immediately, otherwise it is recorded in a thread-based bundle of current events. If no transaction was started, an event marked Event.isCommitEvent() is used to flush the event bundle to its listeners, otherwise the transaction commit does the flush.

Listeners are of two types: EventListener notified as the event is raised and PostCommitEventListener notified after the transaction was committed.

Method Summary

void	addEventListener(EventListenerDescriptor listener) Adds a new event listener.
void	addTransactionListener(EventTransactionListener listener) Adds an event transaction listener.
void	fireEvent(Event event) Fires an event.
void	fireEvent(String name, EventContext context) Fires an event given its name and a context.
void	fireEventBundle(EventBundle event) Fires all recorded events in a transaction.
void	fireEventBundleSync(EventBundle event) Fires an event bundle in synchronous mode.
List<EventListener>	getEventListeners() Gets the list of the registered event listeners.
List<PostCommitEventListener>	getPostCommitEventListeners() Get the list of the registered post commit event listeners.
boolean	isTransactionStarted() Tests whether or not a transaction was started.
void	removeEventListener(EventListenerDescriptor listener) Removes an event listener.
void	removeTransactionListener(EventTransactionListener listener) Removes the given event transaction listener.
void	transactionCommitted() Notifies that the transaction was committed.
void	transactionRolledback() Notifies that transaction was rolled back.
void	transactionStarted() Notifies that a transaction was started.
void	waitForAsyncCompletion() Waits until all asynchronous tasks are finished.
void	waitForAsyncCompletion(long timeout) Waits until all asynchronous tasks are finished, but waits no longer than the given number of milliseconds.

Method Detail

addEventListener

void addEventListener(EventListenerDescriptor listener)

Adds a new event listener. Used by the framework.

The event listener is described by a EventListenerDescriptor that may specify a priority. Both types of listeners (immediate and post-commit) are registered.

Parameters:

listener - the listener to add

removeEventListener

void removeEventListener(EventListenerDescriptor listener)

Removes an event listener. Used by the framework.

Parameters:

listener - the listener to remove

fireEvent

void fireEvent(String name,
               EventContext context)
               throws ClientException

Fires an event given its name and a context.

Parameters:

name - the event name

context - the event context

Throws:

ClientException

fireEvent

void fireEvent(Event event)
               throws ClientException

Fires an event.

If a transaction was started, the event is registered if needed to be sent after the transaction commit.

Specified by:

fireEvent in interface EventProducer

Parameters:

event - the event to fire

Throws:

ClientException

fireEventBundle

void fireEventBundle(EventBundle event)
                     throws ClientException

Fires all recorded events in a transaction. Used by the framework.

The events are fired to PostCommitEventListener listeners. Events are fired in the form of an event bundle.

Specified by:

fireEventBundle in interface EventProducer

Parameters:

event - the event bundle

Throws:

ClientException

fireEventBundleSync

void fireEventBundleSync(EventBundle event)
                         throws ClientException

Fires an event bundle in synchronous mode. Used by the framework.

This means that asynchronous listeners will be run synchronously.

Throws:

ClientException

getEventListeners

List<EventListener> getEventListeners()

Gets the list of the registered event listeners.

Modification on this list will not modify the internal lists in this EventService.

Returns:

the event listeners

getPostCommitEventListeners

List<PostCommitEventListener> getPostCommitEventListeners()

Get the list of the registered post commit event listeners.

Modification on this list will not modify the internal lists in this EventService.

Returns:

the post commit event listeners

transactionStarted

void transactionStarted()

Notifies that a transaction was started. Used by the framework.

Any fired events will be recorded until the transaction is terminated either by calling transactionRolledback() either transactionCommitted().

transactionCommitted

void transactionCommitted()
                          throws ClientException

Notifies that the transaction was committed. Used by the framework.

This will fire the events collected during the transaction in the form of a EventBundle. After this the recording will stop and recorded events discarded.

Throws:

ClientException

transactionRolledback

void transactionRolledback()

Notifies that transaction was rolled back. Used by the framework.

This will discard any recorded event.

isTransactionStarted

boolean isTransactionStarted()

Tests whether or not a transaction was started.

Returns:

true if a transaction was started, false otherwise

waitForAsyncCompletion

void waitForAsyncCompletion()

Waits until all asynchronous tasks are finished.

waitForAsyncCompletion

void waitForAsyncCompletion(long timeout)

Waits until all asynchronous tasks are finished, but waits no longer than the given number of milliseconds.

Parameters:

timeout - the maximum time to wait for, in milliseconds

addTransactionListener

void addTransactionListener(EventTransactionListener listener)

Adds an event transaction listener.

removeTransactionListener

void removeTransactionListener(EventTransactionListener listener)

Removes the given event transaction listener.