1 /*
2 * Copyright (c) 2010, 2013, 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.binding;
27
28 import javafx.beans.InvalidationListener;
29 import javafx.beans.Observable;
30 import javafx.beans.value.ChangeListener;
31 import javafx.collections.FXCollections;
32 import javafx.collections.ObservableList;
33
34 import com.sun.javafx.binding.BindingHelperObserver;
35 import com.sun.javafx.binding.ExpressionHelper;
36
37 /**
38 * Base class that provides most of the functionality needed to implement a
39 * {@link Binding} of a {@code double} value.
40 * <p>
41 * {@code DoubleBinding} provides a simple invalidation-scheme. An extending
42 * class can register dependencies by calling {@link #bind(Observable...)}.
43 * If One of the registered dependencies becomes invalid, this
44 * {@code DoubleBinding} is marked as invalid. With
45 * {@link #unbind(Observable...)} listening to dependencies can be stopped.
46 * <p>
47 * To provide a concrete implementation of this class, the method
48 * {@link #computeValue()} has to be implemented to calculate the value of this
49 * binding based on the current state of the dependencies. It is called when
50 * {@link #get()} is called for an invalid binding.
51 * <p>
52 * Below is a simple example of a {@code DoubleBinding} calculating the square-
53 * root of a {@link javafx.beans.value.ObservableNumberValue} {@code moo}.
54 *
55 * <pre>
56 * <code>
57 * final ObservableDoubleValue moo = ...;
58 *
59 * DoubleBinding foo = new DoubleBinding() {
60 *
61 * {
62 * super.bind(moo);
63 * }
64 *
65 * @Override
66 * protected double computeValue() {
67 * return Math.sqrt(moo.getValue());
68 * }
69 * };
70 * </code>
71 * </pre>
72 *
73 * Following is the same example with implementations for the optional methods
74 * {@link Binding#getDependencies()} and {@link Binding#dispose()}.
75 *
76 * <pre>
77 * <code>
78 * final ObservableDoubleValue moo = ...;
79 *
80 * DoubleBinding foo = new DoubleBinding() {
81 *
82 * {
83 * super.bind(moo);
84 * }
85 *
86 * @Override
87 * protected double computeValue() {
88 * return Math.sqrt(moo.getValue());
89 * }
90 *
91 * @Override
92 * public ObservableList<?> getDependencies() {
93 * return FXCollections.singletonObservableList(moo);
94 * }
95 *
96 * @Override
97 * public void dispose() {
98 * super.unbind(moo);
99 * }
100 * };
101 * </code>
102 * </pre>
103 *
104 * @see Binding
105 * @see NumberBinding
106 * @see javafx.beans.binding.DoubleExpression
107 *
108 *
109 * @since JavaFX 2.0
110 */
111 public abstract class DoubleBinding extends DoubleExpression implements
112 NumberBinding {
113
114 private double value;
115 private boolean valid;
116 private BindingHelperObserver observer;
117 private ExpressionHelper<Number> helper = null;
118
119 @Override
120 public void addListener(InvalidationListener listener) {
121 helper = ExpressionHelper.addListener(helper, this, listener);
122 }
123
124 @Override
125 public void removeListener(InvalidationListener listener) {
126 helper = ExpressionHelper.removeListener(helper, listener);
127 }
128
129 @Override
130 public void addListener(ChangeListener<? super Number> listener) {
131 helper = ExpressionHelper.addListener(helper, this, listener);
132 }
133
134 @Override
135 public void removeListener(ChangeListener<? super Number> listener) {
136 helper = ExpressionHelper.removeListener(helper, listener);
137 }
138
139 /**
140 * Start observing the dependencies for changes. If the value of one of the
141 * dependencies changes, the binding is marked as invalid.
142 *
143 * @param dependencies
144 * the dependencies to observe
145 */
146 protected final void bind(Observable... dependencies) {
147 if ((dependencies != null) && (dependencies.length > 0)) {
148 if (observer == null) {
149 observer = new BindingHelperObserver(this);
150 }
151 for (final Observable dep : dependencies) {
152 dep.addListener(observer);
153 }
154 }
155 }
156
157 /**
158 * Stop observing the dependencies for changes.
159 *
160 * @param dependencies
161 * the dependencies to stop observing
162 */
163 protected final void unbind(Observable... dependencies) {
164 if (observer != null) {
165 for (final Observable dep : dependencies) {
166 dep.removeListener(observer);
167 }
168 observer = null;
169 }
170 }
171
172 /**
173 * A default implementation of {@code dispose()} that is empty.
174 */
175 @Override
176 public void dispose() {
177 }
178
179 /**
180 * A default implementation of {@code getDependencies()} that returns an
181 * empty {@link javafx.collections.ObservableList}.
182 *
183 * @return an empty {@code ObservableList}
184 */
185 @Override
186 public ObservableList<?> getDependencies() {
187 return FXCollections.emptyObservableList();
188 }
189
190 /**
191 * Returns the result of {@link #computeValue()}. The method
192 * {@code computeValue()} is only called if the binding is invalid. The
193 * result is cached and returned if the binding did not become invalid since
194 * the last call of {@code get()}.
195 *
196 * @return the current value
197 */
198 @Override
199 public final double get() {
200 if (!valid) {
201 value = computeValue();
202 valid = true;
203 }
204 return value;
205 }
206
207 /**
208 * The method onInvalidating() can be overridden by extending classes to
209 * react, if this binding becomes invalid. The default implementation is
210 * empty.
211 */
212 protected void onInvalidating() {
213 }
214
215 @Override
216 public final void invalidate() {
217 if (valid) {
218 valid = false;
219 onInvalidating();
220 ExpressionHelper.fireValueChangedEvent(helper);
221 }
222 }
223
224 @Override
225 public final boolean isValid() {
226 return valid;
227 }
228
229 /**
230 * Calculates the current value of this binding.
231 * <p>
232 * Classes extending {@code DoubleBinding} have to provide an implementation
233 * of {@code computeValue}.
234 *
235 * @return the current value
236 */
237 protected abstract double computeValue();
238
239 /**
240 * Returns a string representation of this {@code DoubleBinding} object.
241 * @return a string representation of this {@code DoubleBinding} object.
242 */
243 @Override
244 public String toString() {
245 return valid ? "DoubleBinding [value: " + get() + "]"
246 : "DoubleBinding [invalid]";
247 }
248 }