Package org.jdesktop.beansbinding

Class BeanProperty<S,​V>

  • Type Parameters:
    S - the type of source object that this BeanProperty operates on
    V - the type of value that this BeanProperty represents
    public final class BeanProperty<S,​V>
extends PropertyHelper<S,​V>
    An implementation of Property that uses a simple dot-separated path syntax to address Java Beans properties of source objects. For example, to create a property representing the firstName property of an obect: 

    
    BeanProperty.create("firstName");

    Or to create a property representing the firstName property of an object's mother property: 

    
    BeanProperty.create("mother.firstName");

    An instance of BeanProperty is immutable and can be used with different source objects. When a PropertyStateListener is added to a BeanProperty for a given source object, the BeanProperty starts listening to all objects along the path (based on that source object) for change notification, and reflects any changes by notifying the listener associated with the property for that source object. So, in the second example above, if a PropertyStateListener is added to the property for an object Duke, the PropertyStateListener is notified when either Duke's mother changes (if the new mother's name is different), or Duke's mother's firstName changes.

    It is very important that any bean properties addressed via a BeanProperty follow the Java Beans specification, including firing property change notification; otherwise, BeanProperty cannot respond to change. As some beans outside of your control may not follow the Java Beans specification, BeanProperty always checks the BeanAdapterFactory to see if a delegate provider has been registered to provide a delegate bean to take the place of an object for a given property. See the ext package level documentation for more details.

    When there are no PropertyStateListeners installed on a BeanProperty for a given source, all Property methods act by traversing the entire path from the source to the end point, thereby always providing "live" information. On the contrary, when there are PropertyStateListeners installed, the beans along the path (including the final value) are cached, and only updated upon notification of change from a bean. Again, this makes it very important that any bean property that could change along the path fires property change notification.

    Readability of a BeanProperty for a given source is defined as follows: A BeanProperty is readable for a given source if and only if a) each bean in the path, starting with the source, defines a Java Beans getter method for the the property to be read on it AND b) each bean in the path, starting with the source and ending with the bean on which we read the final property, is non-null. The final value being null does not affect the readability.

    So, in the second example given earlier, the BeanProperty is readable for (@code Duke} when all of the following are true: Duke defines a Java Beans getter for mother, Duke's mother defines a Java Beans getter for firstName, Duke is non-null, Duke's mother is non-null. The BeanProperty is therefore unreadable when any of the following is true: Duke does not define a Java Beans getter for mother, Duke's mother does not define a Java Beans getter for firstName, Duke is null, Duke's mother is null.

    Writeability of a BeanProperty for a given source is defined as follows: A BeanProperty is writeable for a given source if and only if a) each bean in the path, starting with the source and ending with the bean on which we set the final property, defines a Java Beans getter method for the property to be read on it AND b) the bean on which we set the final property defines a Java Beans setter for the property to be set on it AND c) each bean in the path, starting with the source and ending with the bean on which we set the final property, is non-null. The final value being null does not affect the writeability.

    So, in the second example given earlier, the BeanProperty is writeable for Duke when all of the following are true: Duke defines a Java Beans getter for mother, Duke's mother defines a Java Beans setter for firstName, Duke is non-null, Duke's mother is non-null. The BeanProperty is therefore unreadable when any of the following is true: Duke does not define a Java Beans getter for mother, Duke's mother does not define a Java Beans setter for firstName, Duke is null, Duke's mother is null.

    In addition to working on Java Beans properties, any object in the path can be an instance of Map. In this case, the Map's get method is used with the property name as the getter, and the Map's put method is used with the property name as the setter. BeanProperty can only respond to changes in Maps if they are instances of ObservableMap.

    Some methods in this class document that they can throw PropertyResolutionException if an exception occurs while trying to resolve the path. The throwing of this exception represents an abnormal condition and if listeners are installed for the given source object, leaves the BeanProperty in an inconsistent state for that source object. A BeanProperty should not be used again for that same source object after such an exception without first removing all listeners associated with the BeanProperty for that source object.

    Author:
    Shannon Hickey, Scott Violet

    • Method Detail

      • create

        public static final <S,​V> BeanProperty<S,​V> create​(String path)
        Creates an instance of BeanProperty for the given path.
        Parameters:
        path - the path
        Returns:
        an instance of BeanProperty for the given path
        Throws:
        IllegalArgumentException - if the path is null, or contains no property names

      • create

        public static final <S,​V> BeanProperty<S,​V> create​(Property<S,​?> baseProperty,
                                                               String path)
        Creates an instance of BeanProperty for the given base property and path. The path is relative to the value of the base property.
        Parameters:
        baseProperty - the base property
        path - the path
        Returns:
        an instance of BeanProperty for the given base property and path
        Throws:
        IllegalArgumentException - if the path is null, or contains no property names

      • getValue

        public V getValue​(S source)
        Returns the value of this Property for the given source.

        See the class level documentation for the definition of readability.

        Specified by:
        getValue in class PropertyHelper<S,​V>
        Parameters:
        source - the source object on which to operate
        Returns:
        the value of this Property for the given source
        Throws:
        UnsupportedOperationException - if the Property is not readable for the given source
        PropertyResolutionException - if an exception occurs while resolving the path
        See Also:
        isReadable(S)

      • listeningStarted

        protected final void listeningStarted​(S source)
        Description copied from class: PropertyHelper
        Called when this PropertyHelper changes from having no listeners installed for the given source object to having listeners installed for the given source object. This is the ideal time for subclasses to install any listeners needed to track change on the source object.
        Overrides:
        listeningStarted in class PropertyHelper<S,​V>
        See Also:
        PropertyHelper.listeningStopped(S)

      • listeningStopped

        protected final void listeningStopped​(S source)
        Description copied from class: PropertyHelper
        Called when this PropertyHelper changes from having listeners installed for the given source object to having no listeners installed for the given source object. This is the ideal time for subclasses to remove any listeners that they've installed to track changes on the source object.
        Overrides:
        listeningStopped in class PropertyHelper<S,​V>
        See Also:
        PropertyHelper.listeningStopped(S)

      • toString

        public String toString()
        Returns a string representation of the BeanProperty. This method is intended to be used for debugging purposes only, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.
        Overrides:
        toString in class Object
        Returns:
        a string representation of this BeanProperty