Spec-Zone .ru
спецификации, руководства, описания, API
001/*
002 * Copyright (c) 2010, 2013, Oracle and/or its affiliates. All rights reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation.  Oracle designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Oracle in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
022 * or visit www.oracle.com if you need additional information or have any
023 * questions.
024 */
025
026package javafx.beans.binding;
027
028import javafx.beans.InvalidationListener;
029import javafx.beans.Observable;
030import javafx.beans.value.ChangeListener;
031import javafx.collections.FXCollections;
032import javafx.collections.ObservableList;
033import com.sun.javafx.collections.annotations.ReturnsUnmodifiableCollection;
034
035import com.sun.javafx.binding.BindingHelperObserver;
036import com.sun.javafx.binding.ExpressionHelper;
037
038/**
039 * Base class that provides most of the functionality needed to implement a
040 * {@link Binding} of a {@code double} value.
041 * <p>
042 * {@code DoubleBinding} provides a simple invalidation-scheme. An extending
043 * class can register dependencies by calling {@link #bind(Observable...)}.
044 * If One of the registered dependencies becomes invalid, this
045 * {@code DoubleBinding} is marked as invalid. With
046 * {@link #unbind(Observable...)} listening to dependencies can be stopped.
047 * <p>
048 * To provide a concrete implementation of this class, the method
049 * {@link #computeValue()} has to be implemented to calculate the value of this
050 * binding based on the current state of the dependencies. It is called when
051 * {@link #get()} is called for an invalid binding.
052 * <p>
053 * Below is a simple example of a {@code DoubleBinding} calculating the square-
054 * root of a {@link javafx.beans.value.ObservableNumberValue} {@code moo}.
055 * 
056 * <pre>
057 * <code>
058 * final ObservableDoubleValue moo = ...;
059 * 
060 * DoubleBinding foo = new DoubleBinding() {
061 * 
062 *     {
063 *         super.bind(moo);
064 *     }
065 * 
066 *     &#x40;Override
067 *     protected double computeValue() {
068 *         return Math.sqrt(moo.getValue());
069 *     }
070 * };
071 * </code>
072 * </pre>
073 * 
074 * Following is the same example with implementations for the optional methods
075 * {@link Binding#getDependencies()} and {@link Binding#dispose()}.
076 * 
077 * <pre>
078 * <code>
079 * final ObservableDoubleValue moo = ...;
080 * 
081 * DoubleBinding foo = new DoubleBinding() {
082 * 
083 *     {
084 *         super.bind(moo);
085 *     }
086 * 
087 *     &#x40;Override
088 *     protected double computeValue() {
089 *         return Math.sqrt(moo.getValue());
090 *     }
091 * 
092 *     &#x40;Override
093 *     public ObservableList<?> getDependencies() {
094 *         return FXCollections.singletonObservableList(moo);
095 *     }
096 *     
097 *     &#x40;Override
098 *     public void dispose() {
099 *         super.unbind(moo);
100 *     }
101 * };
102 * </code>
103 * </pre>
104 * 
105 * @see Binding
106 * @see NumberBinding
107 * @see javafx.beans.binding.DoubleExpression
108 * 
109 * 
110 */
111public 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    @ReturnsUnmodifiableCollection
187    public ObservableList<?> getDependencies() {
188        return FXCollections.emptyObservableList();
189    }
190
191    /**
192     * Returns the result of {@link #computeValue()}. The method
193     * {@code computeValue()} is only called if the binding is invalid. The
194     * result is cached and returned if the binding did not become invalid since
195     * the last call of {@code get()}.
196     * 
197     * @return the current value
198     */
199    @Override
200    public final double get() {
201        if (!valid) {
202            value = computeValue();
203            valid = true;
204        }
205        return value;
206    }
207
208    /**
209     * The method onInvalidating() can be overridden by extending classes to
210     * react, if this binding becomes invalid. The default implementation is
211     * empty.
212     */
213    protected void onInvalidating() {
214    }
215
216    @Override
217    public final void invalidate() {
218        if (valid) {
219            valid = false;
220            onInvalidating();
221            ExpressionHelper.fireValueChangedEvent(helper);
222        }
223    }
224
225    @Override
226    public final boolean isValid() {
227        return valid;
228    }
229
230    /**
231     * Calculates the current value of this binding.
232     * <p>
233     * Classes extending {@code DoubleBinding} have to provide an implementation
234     * of {@code computeValue}.
235     * 
236     * @return the current value
237     */
238    protected abstract double computeValue();
239
240    /**
241     * Returns a string representation of this {@code DoubleBinding} object.
242     * @return a string representation of this {@code DoubleBinding} object.
243     */ 
244    @Override
245    public String toString() {
246        return valid ? "DoubleBinding [value: " + get() + "]"
247                : "DoubleBinding [invalid]";
248    }
249}