|
78
|
1 /*******************************************************************************
|
|
|
2 * Copyright (c) 2005, 2008 IBM Corporation and others.
|
|
|
3 * All rights reserved. This program and the accompanying materials
|
|
|
4 * are made available under the terms of the Eclipse Public License v1.0
|
|
|
5 * which accompanies this distribution, and is available at
|
|
|
6 * http://www.eclipse.org/legal/epl-v10.html
|
|
|
7 *
|
|
|
8 * Contributors:
|
|
|
9 * IBM Corporation - initial API and implementation
|
|
|
10 *******************************************************************************/
|
|
|
11 module org.eclipse.core.databinding.observable.IObservable;
|
|
81
|
12 import org.eclipse.core.databinding.observable.IChangeListener;
|
|
|
13 import org.eclipse.core.databinding.observable.Realm;
|
|
|
14 import org.eclipse.core.databinding.observable.IStaleListener;
|
|
78
|
15
|
|
|
16 import java.lang.all;
|
|
|
17
|
|
|
18 /**
|
|
|
19 * An object with state that allows to listen for state changes.
|
|
|
20 *
|
|
|
21 * <p>
|
|
|
22 * Implementations must not manage listeners themselves, listener management
|
|
|
23 * must be delegated to a private instance of type {@link ChangeSupport} if it
|
|
|
24 * is not inherited from {@link AbstractObservable}.
|
|
|
25 * </p>
|
|
|
26 *
|
|
|
27 * @noextend This interface is not intended to be extended by clients.
|
|
|
28 * @noimplement This interface is not intended to be implemented by clients.
|
|
|
29 * Clients should instead subclass one of the classes in the
|
|
|
30 * framework that implement this interface. Note that direct
|
|
|
31 * implementers of this interface outside of the framework will be
|
|
|
32 * broken in future releases when methods are added to this
|
|
|
33 * interface.
|
|
|
34 *
|
|
|
35 * @since 1.0
|
|
|
36 *
|
|
|
37 */
|
|
|
38 public interface IObservable {
|
|
|
39
|
|
|
40 /**
|
|
|
41 * Returns the realm for this observable. Unless otherwise specified,
|
|
|
42 * getters and setters must be accessed from within this realm. Listeners
|
|
|
43 * will be within this realm when they receive events from this observable.
|
|
|
44 * <p>
|
|
|
45 * Because observables can only be accessed from within one realm, and they
|
|
|
46 * always fire events on that realm, their state can be observed in an
|
|
|
47 * incremental way. It is always safe to call getters of an observable from
|
|
|
48 * within a change listener attached to that observable.
|
|
|
49 * </p>
|
|
|
50 *
|
|
|
51 * @return the realm
|
|
|
52 */
|
|
|
53 public Realm getRealm();
|
|
|
54
|
|
|
55 /**
|
|
|
56 * Adds the given change listener to the list of change listeners. Change
|
|
|
57 * listeners are notified about changes of the state of this observable in a
|
|
|
58 * generic way, without specifying the change that happened. To get the
|
|
|
59 * changed state, a change listener needs to query for the current state of
|
|
|
60 * this observable.
|
|
|
61 *
|
|
|
62 * @param listener
|
|
|
63 */
|
|
|
64 public void addChangeListener(IChangeListener listener);
|
|
|
65
|
|
|
66 /**
|
|
|
67 * Removes the given change listener from the list of change listeners. Has
|
|
|
68 * no effect if the given listener is not registered as a change listener.
|
|
|
69 *
|
|
|
70 * @param listener
|
|
|
71 */
|
|
|
72 public void removeChangeListener(IChangeListener listener);
|
|
|
73
|
|
|
74 /**
|
|
|
75 * Adds the given stale listener to the list of stale listeners. Stale
|
|
|
76 * listeners are notified when an observable object becomes stale, not when
|
|
|
77 * is becomes non-stale.
|
|
|
78 *
|
|
|
79 * @param listener
|
|
|
80 *
|
|
|
81 * @see #isStale()
|
|
|
82 */
|
|
|
83 public void addStaleListener(IStaleListener listener);
|
|
|
84
|
|
|
85 /**
|
|
|
86 * Removes the given stale listener from the list of stale listeners. Has no
|
|
|
87 * effect if the given listener is not registered as a stale listener.
|
|
|
88 *
|
|
|
89 * @param listener
|
|
|
90 */
|
|
|
91 public void removeStaleListener(IStaleListener listener);
|
|
|
92
|
|
|
93 /**
|
|
|
94 * Returns whether the state of this observable is stale and is expected to
|
|
|
95 * change soon. A non-stale observable that becomes stale will notify its
|
|
|
96 * stale listeners. A stale object that becomes non-stale does so by
|
|
|
97 * changing its state and notifying its change listeners, it does <b>not</b>
|
|
|
98 * notify its stale listeners about becoming non-stale. Clients that do not
|
|
|
99 * expect asynchronous changes may ignore staleness of observable objects.
|
|
|
100 *
|
|
|
101 * @return true if this observable's state is stale and will change soon.
|
|
|
102 *
|
|
|
103 * @TrackedGetter - implementers must call
|
|
|
104 * {@link ObservableTracker#getterCalledcast(IObservable)}.
|
|
|
105 */
|
|
|
106 public bool isStale();
|
|
|
107
|
|
|
108 /**
|
|
|
109 * Disposes of this observable object, removing all listeners registered
|
|
|
110 * with this object, and all listeners this object might have registered on
|
|
|
111 * other objects.
|
|
|
112 */
|
|
|
113 public void dispose();
|
|
|
114 }
|
