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.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 }