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