1 /*
   2  * Copyright (c) 2010, 2016, 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.value.ObservableValue;
  29 import javafx.collections.ObservableList;
  30 
  31 /**
  32  * A {@code Binding} calculates a value that depends on one or more sources. The
  33  * sources are usually called the dependency of a binding. A binding observes
  34  * its dependencies for changes and updates its value automatically.
  35  * <p>
  36  * While a dependency of a binding can be anything, it is almost always an
  37  * implementation of {@link javafx.beans.value.ObservableValue}. {@code Binding}
  38  * implements {@code ObservableValue} allowing to use it in another binding.
  39  * With that one can assemble very complex bindings from simple bindings.
  40  * <p>
  41  * All bindings in the JavaFX runtime are calculated lazily. That means, if
  42  * a dependency changes, the result of a binding is not immediately
  43  * recalculated, but it is marked as invalid. Next time the value of an invalid
  44  * binding is requested, it is recalculated.
  45  * <p>
  46  * It is recommended to use one of the base classes defined in this package
  47  * (e.g. {@link DoubleBinding}) to define a custom binding, because these
  48  * classes already provide most of the needed functionality. See
  49  * {@link DoubleBinding} for an example.
  50  *
  51  * @param <T> the type of the wrapped value
  52  * @see DoubleBinding
  53  *
  54  * @since JavaFX 2.0
  55  */
  56 public interface Binding<T> extends ObservableValue<T> {
  57 
  58     /**
  59      * Checks if a binding is valid.
  60      *
  61      * @return {@code true} if the {@code Binding} is valid, {@code false}
  62      *         otherwise
  63      */
  64     boolean isValid();
  65 
  66     /**
  67      * Mark a binding as invalid. This forces the recalculation of the value of
  68      * the {@code Binding} next time it is request.
  69      */
  70     void invalidate();
  71 
  72     /**
  73      * Returns the dependencies of a binding in an unmodifiable
  74      * {@link javafx.collections.ObservableList}. The implementation is
  75      * optional. The main purpose of this method is to support developers during
  76      * development. It allows to explore and monitor dependencies of a binding
  77      * during runtime.
  78      * <p>
  79      * Because this method should not be used in production code, it is
  80      * recommended to implement this functionality as sparse as possible. For
  81      * example if the dependencies do not change, each call can generate a new
  82      * {@code ObservableList}, avoiding the necessity to store the result.
  83      *
  84      * @return an unmodifiable {@code} ObservableList of the dependencies
  85      */
  86     ObservableList<?> getDependencies();
  87 
  88     /**
  89      * Signals to the {@code Binding} that it will not be used anymore and any
  90      * references can be removed. A call of this method usually results in the
  91      * binding stopping to observe its dependencies by unregistering its
  92      * listener(s). The implementation is optional.
  93      * <p>
  94      * All bindings in our implementation use instances of
  95      * {@link javafx.beans.WeakInvalidationListener}, which means usually
  96      * a binding does not need to be disposed. But if you plan to use your
  97      * application in environments that do not support {@code WeakReferences}
  98      * you have to dispose unused {@code Bindings} to avoid memory leaks.
  99      */
 100     void dispose();
 101 
 102 }