Mercurial > projects > dwt2

annotate org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/IObservable.d @ 97:c86eb8b3098e

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