1 //----------------------------------------------------------------------
2 //
3 // PerfectJPattern: "Design patterns are good but components are better!"
4 // IObserver.java Copyright (c) 2009 Giovanni Azua Garcia
5 // bravegag@hotmail.com
6 //
7 // This program is free software; you can redistribute it and/or
8 // modify it under the terms of the GNU General Public License
9 // as published by the Free Software Foundation; either version 3
10 // of the License, or (at your option) any later version.
11 //
12 // This program is distributed in the hope that it will be useful,
13 // but WITHOUT ANY WARRANTY; without even the implied warranty of
14 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 // GNU General Public License for more details.
16 //
17 // You should have received a copy of the GNU General Public License
18 // along with this program; if not, see <http://www.gnu.org/licenses/>.
19 //
20 //----------------------------------------------------------------------
21 package org.perfectjpattern.core.api.behavioral.observer;
22
23 /**
24 * <b>Observer Design Pattern</b>: Define a one-to-many dependency between
25 * objects so that when one object changes state, all its dependents are
26 * notified and updated automatically. (Gamma et al, Design Patterns)<br/>
27 * <br/>
28 *
29 * <b>Responsibility</b>: Abstract generic definition of the "Observer".
30 * pattern role.<br/>
31 * <ul>
32 * <li>Defines an updating interface for objects that should be notified of
33 * changes in a subject.</li>
34 * </ul>
35 *
36 * <b>Notes</b>:
37 * Improves over the original GoF recipe and Java Observer implementation
38 * in that:<br/>
39 * <ul>
40 * <li>Push over Pull approach: <code>IObserver</code> instances are not
41 * coupled to the <code>ISubject</code> interface i.e. there is no need for the
42 * <code>IObserver</code> to query <code>ISubject</code>'s state. State
43 * change or Message content is pushed to the {@link #update} callback
44 * method.</li>
45 * <li>Strongly typed generic parameter eliminates the need for
46 * <code>IObserver</code> to downcast the parameter as is the case for
47 * e.g. <code>java.util.Observer</code> implementation.</li>
48 * </ul>
49 *
50 * <br/>
51 * Example usage:
52 * <pre><code>
53 * //
54 * // Create Observer Pattern elements
55 * //
56 * ISubject mySubject = new ConcreteSubject();
57 * IObserver myFirstObserver = new ConcreteObserver();
58 * IObserver mySecondObserver = new ConcreteObserver();
59 *
60 * //
61 * // Subscribe multiple Observer instances to the Subject
62 * //
63 * mySubject.attach(myFirstObserver, mySecondObserver);
64 *
65 * //
66 * // Notify all subscribed Observers, optionally pass some Event
67 * // data associated with the Event.
68 * //
69 * mySubject.notifyObservers(NullEventData.getInstance());
70 *
71 * //
72 * // Detach Observer instances
73 * //
74 * mySubject.detach(myFirstObserver);
75 * </code></pre>
76 *
77 * @param <E> Type of event data that this <code>IObserver</code> subscribes
78 * to.
79 *
80 * @author <a href="mailto:bravegag@hotmail.com">Giovanni Azua</a>
81 * @version $Revision: 1.0 $ $Date: Jun 11, 2007 6:16:01 AM $
82 */
83 public
84 interface IObserver<E>
85 {
86 //-------------------------------------------------------------------------
87 // public
88 //-------------------------------------------------------------------------
89 /**
90 * Notification from <code>ISubject</code> instance that a change
91 * has ocurred.
92 *
93 * @param anEventData Event data pushed to <code>IObserver</code>
94 * instances.
95 */
96 public void
97 update(E anEventData);
98 }