1 /*
2 * Copyright (c) 2010, 2018, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javafx.beans.value;
27
28 import javafx.beans.InvalidationListener;
29 import javafx.beans.Observable;
30
31 /**
32 * An {@code ObservableValue} is an entity that wraps a value and allows to
33 * observe the value for changes. In general this interface should not be
34 * implemented directly but one of its sub-interfaces
35 * ({@code ObservableBooleanValue} etc.).
36 * <p>
37 * The value of the {@code ObservableValue} can be requested with
38 * {@link #getValue()}.
39 * <p>
40 * An implementation of {@code ObservableValue} may support lazy evaluation,
41 * which means that the value is not immediately recomputed after changes, but
42 * lazily the next time the value is requested. All bindings and properties in
43 * this library support lazy evaluation.
44 * <p>
45 * An {@code ObservableValue} generates two types of events: change events and
46 * invalidation events. A change event indicates that the value has changed. An
47 * invalidation event is generated if the current value is not valid anymore.
48 * This distinction becomes important if the {@code ObservableValue} supports
49 * lazy evaluation, because for a lazily evaluated value one does not know if an
50 * invalid value really has changed until it is recomputed. For this reason,
51 * generating change events requires eager evaluation while invalidation events
52 * can be generated for eager and lazy implementations.
53 * <p>
54 * Implementations of this class should strive to generate as few events as
55 * possible to avoid wasting too much time in event handlers. Implementations in
56 * this library mark themselves as invalid when the first invalidation event
57 * occurs. They do not generate anymore invalidation events until their value is
58 * recomputed and valid again.
59 * <p>
60 * Two types of listeners can be attached to an {@code ObservableValue}:
61 * {@link InvalidationListener} to listen to invalidation events and
62 * {@link ChangeListener} to listen to change events.
63 * <p>
64 * Important note: attaching a {@code ChangeListener} enforces eager computation
65 * even if the implementation of the {@code ObservableValue} supports lazy
66 * evaluation.
67 *
68 * @param <T>
69 * The type of the wrapped value.
70 *
71 * @see ObservableBooleanValue
72 * @see ObservableDoubleValue
73 * @see ObservableFloatValue
74 * @see ObservableIntegerValue
75 * @see ObservableLongValue
76 * @see ObservableNumberValue
77 * @see ObservableObjectValue
78 * @see ObservableStringValue
79 *
80 *
81 * @since JavaFX 2.0
82 */
83 public interface ObservableValue<T> extends Observable {
84
85 /**
86 * Adds a {@link ChangeListener} which will be notified whenever the value
87 * of the {@code ObservableValue} changes. If the same listener is added
88 * more than once, then it will be notified more than once. That is, no
89 * check is made to ensure uniqueness.
90 * <p>
91 * Note that the same actual {@code ChangeListener} instance may be safely
92 * registered for different {@code ObservableValues}.
93 * <p>
94 * The {@code ObservableValue} stores a strong reference to the listener
95 * which will prevent the listener from being garbage collected and may
96 * result in a memory leak. It is recommended to either unregister a
97 * listener by calling {@link #removeListener(ChangeListener)
98 * removeListener} after use or to use an instance of
99 * {@link WeakChangeListener} avoid this situation.
100 *
101 * @see #removeListener(ChangeListener)
102 *
103 * @param listener
104 * The listener to register
105 * @throws NullPointerException
106 * if the listener is null
107 */
108 void addListener(ChangeListener<? super T> listener);
109
110 /**
111 * Removes the given listener from the list of listeners that are notified
112 * whenever the value of the {@code ObservableValue} changes.
113 * <p>
114 * If the given listener has not been previously registered (i.e. it was
115 * never added) then this method call is a no-op. If it had been previously
116 * added then it will be removed. If it had been added more than once, then
117 * only the first occurrence will be removed.
118 *
119 * @see #addListener(ChangeListener)
120 *
121 * @param listener
122 * The listener to remove
123 * @throws NullPointerException
124 * if the listener is null
125 */
126 void removeListener(ChangeListener<? super T> listener);
127
128 /**
129 * Returns the current value of this {@code ObservableValue}
130 *
131 * @return The current value
132 */
133 T getValue();
134 }