Package: ChangeBroker

ChangeBroker

Coverage

1: /*******************************************************************************
2: * Copyright (c) 2011-2015 EclipseSource Muenchen GmbH and others.
3: *
4: * All rights reserved. This program and the accompanying materials
5: * are made available under the terms of the Eclipse Public License 2.0
6: * which accompanies this distribution, and is available at
7: * https://www.eclipse.org/legal/epl-2.0/
8: *
9: * SPDX-License-Identifier: EPL-2.0
10: *
11: * Contributors:
12: * Jonas - initial API and implementation
13: * Johannes Faltermeier - initial API and implementation
14: ******************************************************************************/
15: package org.eclipse.emf.ecp.changebroker.spi;
16:
17: import org.eclipse.emf.ecore.EClass;
18: import org.eclipse.emf.ecore.EStructuralFeature;
19:
20: /**
21: * <p>
22: * A Change Broker maintains sets of {@link ChangeObserver observers}. Based on incoming notifications it forwards the
23: * notification to the observers based on strategies.
24: * </p>
25: * <p>
26: * There are two kinds of observers: regular {@link ChangeObserver EMFObservers} and {@link ReadOnlyChangeObserver
27: * ReadOnlyEMFObservers}.
28: * </p>
29: * <p>
30: * EMFObservers may change the EMF model and therefore trigger further notifications. To prevent circular updates
31: * between EMFObservers, notifications that arrive while the
32: * {@link ChangeObserver#handleNotification(org.eclipse.emf.common.notify.Notification) handleNotification} method is
33: * called, will not be forwarded to non ReadOnlyEMFObservers.
34: * </p>
35: * <p>
36: * ReadOnlyEMFObservers are not allowed to change the EMF model. They will receive all notifications at any time.
37: * </p>
38: *
39: * @author Jonas
40: * @author jfaltermeier
41: *
42: */
43: public interface ChangeBroker {
44:
45:         /**
46:          * Adds an {@link ChangeObserver} that will receive all notifications. Does nothing if already registered.
47:          *
48:          * @param observer the observer
49:          * @since 1.7
50:          */
51:         void subscribe(EMFObserver observer);
52:
53:         /**
54:          * Adds an {@link ChangeObserver} that will receive notifications of notifiers with the given EClass. Does nothing
55:          * if
56:          * already registered.
57:          *
58:          * @param observer the observer
59:          * @param eClass the required EClass of the notifier
60:          * @since 1.7
61:          */
62:         void subscribeToEClass(ChangeObserver observer, EClass eClass);
63:
64:         /**
65:          * Adds an {@link ChangeObserver} that will receive notifications of notifiers with the given EClass or which are
66:          * contained (either direct or indirect) in an EObject of the given EClass. Does nothing if
67:          * already registered.
68:          *
69:          * @param observer the observer
70:          * @param eClass the required EClass of the notifier or of one of its parents
71:          */
72:         void subscribeToTree(ChangeObserver observer, EClass eClass);
73:
74:         /**
75:          * Adds an {@link ChangeObserver} that will receive notifications when the given EStructuralFeautre is effected.
76:          * Does
77:          * nothing if
78:          * already registered.
79:          *
80:          * @param observer the observer
81:          * @param feature the feature to receive changes for
82:          * @since 1.7
83:          */
84:         void subscribeToFeature(ChangeObserver observer, EStructuralFeature feature);
85:
86:         /**
87:          * Removes an observer. Does nothing if receiver is not registered.
88:          *
89:          * @param observer the receiver
90:          * @since 1.7
91:          */
92:         void unsubsribe(EMFObserver observer);
93:
94:         /**
95:          * Stops notifying all {@link ChangeObserver ChangeObserver}. {@link ReadOnlyChangeObserver ReadOnlyEMFObservers}
96:          * will
97:          * still
98:          * be notified.
99:          */
100:         void stopNotification();
101:
102:         /**
103:          * Notifying the {@link ChangeObserver ChangeObserver} is started again if {@link #stopNotification()} was called
104:          * beforehand. Has no effect if the notification process has been {@link #stopNotification(Object) blocked} or if
105:          * {@link #stopNotification()} wasn't called before.
106:          */
107:         void continueNotification();
108:
109:         /**
110:          * Stops notifying all {@link ChangeObserver ChangeObserver}. {@link ReadOnlyChangeObserver ReadOnlyEMFObservers}
111:          * will
112:          * still
113:          * be notified. The notifications will we blocked until {@link #continueNotification(Object)} has been called with
114:          * <b>all</b> blocking elements. Using the same blocker multiple times has no effect.
115:          *
116:          * @param blocker the key object used to block all notifications
117:          *
118:          */
119:         void stopNotification(Object blocker);
120:
121:         /**
122:          * Removes a {@link #stopNotification(Object) blocker}. When <b>all</b> blockers have been removed the
123:          * notification process will continue. This method calls {@link #continueNotification()} internally in all cases,
124:          * even if the given blocker object was not used as a blocker beforehand.
125:          *
126:          * @param blocker the blocker object to remove.
127:          */
128:         void continueNotification(Object blocker);
129:
130: }