KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > core > databinding > observable > IObservable


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