| /******************************************************************************* |
| * Copyright (c) 2009, 2018 SAP AG and others. |
| * All rights reserved. This program and the accompanying materials |
| * are made available under the terms of the Eclipse Public License v2.0 |
| * which accompanies this distribution, and is available at |
| * http://www.eclipse.org/legal/epl-v20.html |
| * |
| * Contributors: |
| * SAP AG - initial API and implementation |
| ******************************************************************************/ |
| package org.eclipse.ocl.examples.eventmanager; |
| |
| import org.eclipse.emf.common.notify.Adapter; |
| import org.eclipse.emf.common.notify.Notification; |
| import org.eclipse.emf.ecore.resource.ResourceSet; |
| import org.eclipse.ocl.examples.eventmanager.filters.AbstractEventFilter; |
| |
| |
| /** |
| * Common interface for all Implementations of an EMF EventManager |
| * |
| * @author Philipp Berger, Axel Uhl |
| * |
| */ |
| public interface EventManager { |
| /** |
| * Register an {@link Adapter} on the {@link EventManager} which will be notified for any {@link Notification} which matches |
| * the given filter. If an equal or the same <code>caller</code> registers multiple times using equal <code>filter</code>s, |
| * the <code>caller</code> will get notified as many times as it subscribed. |
| * |
| * @param filter |
| * the {@link AbstractEventFilter} which is used to filter events for the given {@link 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 {@link IllegalArgumentException} to be thrown. |
| * @param 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 {@link #unsubscribe(Adapter)} the listener is required as well. |
| */ |
| void subscribe(EventFilter filter, Adapter listener); |
| |
| /** |
| * Removes the given {@link Adapter} from the {@link EventManager} and the linked {@link AbstractEventFilter}, so that the given |
| * {@link Adapter} will not be notified anymore |
| * |
| * @param listener |
| * the {@link Adapter} to unsubscribe |
| * @return <code>true</code> if the adapter was registered |
| */ |
| boolean unsubscribe(Adapter listener); |
| |
| /** |
| * Initialize the filtering process for a given {@link Notification}, all {@link 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 {@link ResourceSet} |
| * for which the event manager has been obtained (see {@link EventManagerFactory#getEventManagerFor(ResourceSet)}). |
| * However, for testing purposes and in case clients want to explicitly send events that have not emerged |
| * from the {@link ResourceSet} to registered clients, they may use this method. |
| * |
| * @param notification |
| * {@link Notification} to send to clients whose event filter matches the notification |
| */ |
| void handleEMFEvent(Notification notification); |
| |
| /** |
| * Adds <code>resourceSet</code> 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 <code>resourceSet</code> it is not registered a second time. In |
| * particular, it won't receive the same notifications multiple times. |
| * |
| * @see #removeFromObservedResourceSets(ResourceSet) |
| */ |
| void addToObservedResourceSets(ResourceSet resourceSet); |
| |
| /** |
| * Stops receiving and dispatching notifications coming from <code>resourceSet</code>. |
| * |
| * @see #addToObservedResourceSets(ResourceSet) |
| */ |
| void removeFromObservedResourceSets(ResourceSet resourceSet); |
| |
| /** |
| * 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 {@link 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 |
| * {@link Adapter}s subscribed with this event manager.<p> |
| * |
| * Calling this method with <code>active==false</code> will stop this event manager from forwarding events to |
| * the {@link Adapter}s subscribed. Calling it with <code>active==true</code> again will forward events received |
| * after the call again. Events that arrived in between are <em>not</em> forwarded and therefore "lost" for the |
| * subscribers to this event manager.<p> |
| * |
| * By default, an event manager starts in the "active" state. |
| */ |
| void setActive(boolean active); |
| } // EventManager |