org.eclipse.emf.transaction
Interface ResourceSetListener

All Superinterfaces:

EventListener

All Known Implementing Classes:

DemultiplexingListener, ResourceSetListenerImpl, TriggerListener

public interface ResourceSetListener
extends EventListener

Listener interface for batched notification of changes to a resource set. Unlike EMF Adapters, resource-set listeners receive notifications at the close of a transaction and, in the case of the post-commit call-back, only in the case that the transaction committed (did not roll back).

This interface is intended to be implemented by clients. For convenience, clients can extend the ResourceSetListenerImpl class if they need no other superclass.

See Also:

ResourceSetListenerImpl, ResourceSetChangeEvent, NotificationFilter, TransactionalEditingDomain.addResourceSetListener(ResourceSetListener)

Method Summary

NotificationFilter	getFilter() Provides a filter to select which notifications should be sent to this listener.
boolean	isAggregatePrecommitListener() Queries whether I should be invoked only for pre-commit of the root transaction, with all of the notifications from that transaction and any nested transactions.
boolean	isPostcommitOnly() Queries whether I am interested only in the post-commit (resourceSetChanged(ResourceSetChangeEvent)) call-back.
boolean	isPrecommitOnly() Queries whether I am interested only in the pre-commit (transactionAboutToCommit(ResourceSetChangeEvent)) call-back.
void	resourceSetChanged(ResourceSetChangeEvent event) Informs the listener that changes have been committed to the model.
Command	transactionAboutToCommit(ResourceSetChangeEvent event) Informs the listener that the execution of a command (which may be implicit) is about to complete.

Method Detail

getFilter

NotificationFilter getFilter()

Provides a filter to select which notifications should be sent to this listener. If none is provided, the default is the NotificationFilter.NOT_TOUCH filter.

Note that, if a listener's filter does not match any of the notifications that were received during a transaction, then it is not invoked at all. Thus, the notification lists received in the ResourceSetChangeEvents will never be empty.

Note also that a listener's filter must not change over time, or unpredictable behaviour will occur. In particular, the editing domain is free to obtain the filter from the listener only once when the listener is added and never request it thereafter. Also, it is not expected the the same filter object's condition can change over time.

Returns:

the filter used to select notifications, or null to obtain the default

transactionAboutToCommit

Command transactionAboutToCommit(ResourceSetChangeEvent event)
                                 throws RollbackException

Informs the listener that the execution of a command (which may be implicit) is about to complete. More precisely, that a read/write transaction is about to commit.

Listeners implement this method in order to provide "trigger commands", akin to database triggers in RDBMSes. To follow-up changes that occurred in the model, to proactively maintain model integrity, the listener can return a command that makes additional changes.

Trigger commands are executed after all listeners have been invoked, in the same transaction context as the original events (and therefore validated together with them). Moreover, because these triggers perform model changes, they cause another round of invocation of these very same resource set listeners.

The command returned by a trigger, if any, should be careful to implement its Command.canExecute() method appropriately. In particular, it is important to check that the conditions observed by the listener still apply, as other trigger commands may be executed before it that can make inconsistent changes.

Finally, a pre-commit listener has the opportunity to force the current transaction to roll back instead of completing the commit. This helps in the implementation of certain kinds of live validation checks that cannot be implemented using the EMF validation framework.

Note that the listener is invoked in a read-only transaction context. It is safe to read the model, but direct changes are not permitted (return a command instead).

Parameters:

event - the event object describing the changes that occurred in the resource set

Returns:

an optional command to perform additional changes. Can be null if no changes are required

Throws:

RollbackException - to force a roll-back of the current transaction

resourceSetChanged

void resourceSetChanged(ResourceSetChangeEvent event)

Informs the listener that changes have been committed to the model. Unlike the transactionAboutToCommit(ResourceSetChangeEvent) call-back, this method has no opportunity to make subsequent changes via triggers or to roll back the transaction. It has already committed. This has the advantage, however, of guaranteeing that it is safe to update the user interface or other dependent components or systems because the changes are committed. This call-back is not invoked if the transaction rolls back, as all of its pending changes are reverted.

Note that the listener is invoked in a read-only transaction context. It is safe to read the model, but changes are not permitted.

Parameters:

event - the event object describing the changes that occurred in the resource set

isAggregatePrecommitListener

boolean isAggregatePrecommitListener()

Queries whether I should be invoked only for pre-commit of the root transaction, with all of the notifications from that transaction and any nested transactions. Otherwise, I will be invoked for each transaction individually and only with its own notifications.

Returns:

true if I should be invoked only for pre-commit of the root transaction; false, otherwise

isPrecommitOnly

boolean isPrecommitOnly()

Queries whether I am interested only in the pre-commit (transactionAboutToCommit(ResourceSetChangeEvent)) call-back. This helps the editing domain to optimize the distribution of events.

Note that this method is queried only once when the listener is added to the editing domain, so the result should not change over time.

Returns:

true if I only am interested in pre-commit events; false, otherwise

isPostcommitOnly

boolean isPostcommitOnly()

Queries whether I am interested only in the post-commit (resourceSetChanged(ResourceSetChangeEvent)) call-back. This helps the editing domain to optimize the distribution of events.

Note that this method is queried only once when the listener is added to the editing domain, so the result should not change over time.

Returns:

true if I only am interested in post-commit events; false, otherwise