Package: ECPObserverBus

ECPObserverBus

Coverage

1: /*******************************************************************************
2: * Copyright (c) 2011-2013 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: * Eugen Neufeld - initial API and implementation
13: *******************************************************************************/
14: package org.eclipse.emf.ecp.core.util.observer;
15:
16: /**
17: * Bus for application wide notifications on events of various types. Check the type hierarchy of {@link ECPObserver} to
18: * discover possible types.<br/>
19: * This is a universal observer bus. This class follows the publish/subscribe pattern, it is a central dispatcher for
20: * observers and makes use of generics in order to allow type safety. It can be used as singleton or be injected through
21: * DI.
22: * Observers have to implement the {@link ECPObserver} interface, which is only used as a marker. Future use of
23: * Annotations is possible.
24: * by using {@link #notify(Class)} (e.g. <code>bus.notify(MyObserver.class).myObserverMethod()</code>) all registered
25: * Observers are notified.
26: * This is implemented by using the java {@link java.lang.reflect.Proxy Proxy} class. By calling {@link #notify(Class)}
27: * a proxy is returned,
28: * which then calls all registered observers.
29: * The proxy can also be casted into {@link org.eclipse.emf.ecp.internal.core.util.observer.ECPObserverCall
30: * ECPObserverCall}, which allows to access all results by the different
31: * observers.
32: *
33: * <br/>
34: * Example code:
35: *
36: * <pre>
37: * // A is ECPObserver
38: * A a = new A() {
39: *
40: *         public void foo() {
41: *                 System.out.println("A says: go!");
42: *         }
43: * };
44: *
45: * // B extends A and is ECPObserver
46: * B b = new B() {
47: *
48: *         public void say(String ja) {
49: *                 System.out.println("B says: " + ja);
50: *         }
51: *
52: *         public void foo() {
53: *                 System.out.println("B says: h??");
54: *         }
55: * };
56: *
57: * // B is registered first
58: * ECPObserverBus.register(b);
59: * ECPObserverBus.register(a);
60: *
61: * ECPObserverBus.notify(A.class).foo();
62: *
63: * ECPObserverBus.notify(B.class).say("w00t");
64: *
65: * // Output:
66: *
67: * // B says: h??
68: * // A says: go!
69: * //
70: * // B says: w00t
71: *
72: * </pre>
73: *
74: * @author wesendon
75: * @author Eugen Neufeld
76: *
77: */
78: public interface ECPObserverBus {
79:         /**
80:          * Registers an observer for all observer interfaces implemented by the object or its super classes.
81:          *
82:          * @param observer observer object
83:          */
84:         void register(ECPObserver observer);
85:
86:         /**
87:          * Unregisters an observer for all observer interfaces implemented by the object or its super classes.
88:          *
89:          * @param observer observer object
90:          */
91:         void unregister(ECPObserver observer);
92:
93:         /**
94:          * This method allows you to notify all observers of type <T>.
95:          * It returns a proxy object of type T which allows you to call the specific methods of your observer. Calling any
96:          * method will be delegated to all registered observers of the given type <T>.
97:          *
98:          * @param <T> type of observer
99:          * @param clazz class of observer
100:          * @return call object of type T
101:          */
102:         <T extends ECPObserver> T notify(Class<T> clazz);
103: }