org.eclipse.ocl.examples.eventmanager

Interface EventManager

All Known Implementing Classes:

EventManagerTableBased

public interface EventManager

Common interface for all Implementations of an EMF EventManager

Author:

Philipp Berger, Axel Uhl

Method Summary

Modifier and Type	Method and Description
void	addToObservedResourceSets(org.eclipse.emf.ecore.resource.ResourceSet resourceSet) Adds resourceSet to the resource sets from which this event manager receives notifications that it dispatches to adapters subscribed to this event manager.
void	handleEMFEvent(org.eclipse.emf.common.notify.Notification notification) Initialize the filtering process for a given Notification, all Adapter registered with a matching filter will be notified.
void	removeFromObservedResourceSets(org.eclipse.emf.ecore.resource.ResourceSet resourceSet) Stops receiving and dispatching notifications coming from resourceSet.
void	setActive(boolean active) Sometimes it can be convenient to temporarily stop the flow of events.
void	subscribe(EventFilter filter, org.eclipse.emf.common.notify.Adapter listener) Register an Adapter on the EventManager which will be notified for any Notification which matches the given filter.
boolean	unsubscribe(org.eclipse.emf.common.notify.Adapter listener) Removes the given Adapter from the EventManager and the linked AbstractEventFilter, so that the given Adapter will not be notified anymore

Method Detail

subscribe

void subscribe(EventFilter filter,
               org.eclipse.emf.common.notify.Adapter listener)

Register an Adapter on the EventManager which will be notified for any Notification which matches the given filter. If an equal or the same caller registers multiple times using equal filters, the caller will get notified as many times as it subscribed.

Parameters:

filter - the AbstractEventFilter which is used to filter events for the given Adapter. Currently, there are still a few limitations as to the filter trees permissible. It is considered an error if the filter, after conversion into disjunctive normal form, contains more than one filter of a kind in an "AND" clause. Such filters, passed to this method, cause an IllegalArgumentException to be thrown.

listener - the adapter which should receive event which matches the filter. This event manager will only maintain weak references to the listener which means that the client should hold a strong reference in order to make sure that notifications will be received. This is a good idea anyhow since for de-registration using unsubscribe(Adapter) the listener is required as well.

unsubscribe

boolean unsubscribe(org.eclipse.emf.common.notify.Adapter listener)

Removes the given Adapter from the EventManager and the linked AbstractEventFilter, so that the given Adapter will not be notified anymore

Parameters:

listener - the Adapter to unsubscribe

Returns:

true if the adapter was registered

handleEMFEvent

void handleEMFEvent(org.eclipse.emf.common.notify.Notification notification)

Initialize the filtering process for a given Notification, all Adapter registered with a matching filter will be notified. Normally, clients don't have to call this method explicitly. It will be called by the event manager automatically when an event has been received from any elements in the ResourceSet for which the event manager has been obtained (see EventManagerFactory.getEventManagerFor(ResourceSet)). However, for testing purposes and in case clients want to explicitly send events that have not emerged from the ResourceSet to registered clients, they may use this method.

Parameters:

notification - Notification to send to clients whose event filter matches the notification

addToObservedResourceSets

void addToObservedResourceSets(org.eclipse.emf.ecore.resource.ResourceSet resourceSet)

Adds resourceSet to the resource sets from which this event manager receives notifications that it dispatches to adapters subscribed to this event manager. If this event manager already does receive notifications from resourceSet it is not registered a second time. In particular, it won't receive the same notifications multiple times.

See Also:

removeFromObservedResourceSets(ResourceSet)

removeFromObservedResourceSets

void removeFromObservedResourceSets(org.eclipse.emf.ecore.resource.ResourceSet resourceSet)

Stops receiving and dispatching notifications coming from resourceSet.

See Also:

addToObservedResourceSets(ResourceSet)

setActive

void setActive(boolean active)

Sometimes it can be convenient to temporarily stop the flow of events. For example, if a particular event manager receives a particular set of events for a certain reason, and that reason temporarily doesn't apply, instead of completely removing the event manager from the underlying ResourceSet and thus removing the adapter from all objects in the resource set, it is more efficient to just block forwarding the events to the Adapters subscribed with this event manager.

Calling this method with active==false will stop this event manager from forwarding events to the Adapters subscribed. Calling it with active==true again will forward events received after the call again. Events that arrived in between are not forwarded and therefore "lost" for the subscribers to this event manager.

By default, an event manager starts in the "active" state.