Package com.globalmentor.beans

Class BoundPropertyObject

  • All Implemented Interfaces:
    PropertyBindable, PropertyConstrainable
    Direct Known Subclasses:
    AbstractTask, BoundPropertyResource, DefaultModifiable, DefaultURIAccessible
    public class BoundPropertyObject
extends java.lang.Object
implements PropertyBindable, PropertyConstrainable
    An object that automatically supports bound and constrained properties.

    Property change support is only created when needed; if no property change listeners are added, the property change support will never be created or invoked, even when firing property change events.

    Vetoable change support is only created when needed; if no vetoable change listeners are added, the vetoable change support will never be created or invoked, even when firing vetoable change events.

    This class was modeled in part from the property support of Component.

    This implementation creates generic-aware property value change events.

    Author:
    Garret Wilson
    See Also:
    PropertyChangeSupport, GenericPropertyChangeEvent, GenericPropertyChangeListener

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected static java.beans.PropertyChangeListener[] NO_PROPERTY_CHANGE_LISTENERS
      A convenience static empty array of property change listeners.
      protected static java.beans.VetoableChangeListener[] NO_VETOABLE_CHANGE_LISTENERS
      A convenience static empty array of vetoable change listeners.

    • Constructor Summary

      Constructors 
      Constructor Description
      BoundPropertyObject()
      Default constructor.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addPropertyChangeListener​(java.beans.PropertyChangeListener listener)
      Adds a property change listener to the listener list.
      void addPropertyChangeListener​(java.lang.String propertyName, java.beans.PropertyChangeListener listener)
      Add a property change listener for a specific property.
      void addVetoableChangeListener​(java.beans.VetoableChangeListener listener)
      Adds a vetoable listener to the listener list.
      void addVetoableChangeListener​(java.lang.String propertyName, java.beans.VetoableChangeListener listener)
      Adds a vetoable change listener for a specific property.
      protected PostponedPropertyChangeEvent createPostponedPropertyChangeEvent​(java.beans.PropertyChangeEvent propertyChangeEvent)
      Creates an object representing a postponement of firing the property change event.
      protected void firePropertyChange​(java.beans.PropertyChangeEvent propertyChangeEvent)
      Reports that a bound property has changed.
      protected void firePropertyChange​(java.lang.String propertyName, boolean oldValue, boolean newValue)
      Reports that a bound boolean property has changed, reporting old and new values of type Boolean.
      protected void firePropertyChange​(java.lang.String propertyName, int oldValue, int newValue)
      Reports that a bound integer property has changed, reporting old and new values of type Integer.
      protected void firePropertyChange​(java.lang.String propertyName, long oldValue, long newValue)
      Reports that a bound long property has changed, reporting old and new values of type Long.
      protected <V> void firePropertyChange​(java.lang.String propertyName, V oldValue, V newValue)
      Reports that a bound property has changed.
      void fireVetoableChange​(java.beans.PropertyChangeEvent propertyChangeEvent)
      Fires a vetoable property update to any registered listeners.
      protected void fireVetoableChange​(java.lang.String propertyName, boolean oldValue, boolean newValue)
      Reports that an integer vetoable property updtae to any registered listeners, reporting old and new values of type Boolean.
      protected void fireVetoableChange​(java.lang.String propertyName, int oldValue, int newValue)
      Reports that an integer vetoable property updtae to any registered listeners, reporting old and new values of type Integer.
      <V> void fireVetoableChange​(java.lang.String propertyName, V oldValue, V newValue)
      Reports a vetoable property update to any registered listeners.
      protected java.beans.PropertyChangeListener getForwardPropertyChangeListener()  
      java.beans.PropertyChangeListener[] getPropertyChangeListeners()
      Returns an array of all the listeners that were added to the with addPropertyChangeListener(PropertyChangeListener).
      java.beans.PropertyChangeListener[] getPropertyChangeListeners​(java.lang.String propertyName)
      Returns an array of all the listeners which have been associated with the named property.
      protected java.beans.PropertyChangeSupport getPropertyChangeSupport()  
      protected java.beans.PropertyChangeListener getRepeatPropertyChangeListener()  
      protected java.beans.VetoableChangeListener getRepeatVetoableChangeListener()  
      java.beans.VetoableChangeListener[] getVetoableChangeListeners()
      Returns the list of vetoable change listeners.
      java.beans.VetoableChangeListener[] getVetoableChangeListeners​(java.lang.String propertyName)
      Returns an array of all the listeners which have been associated with the named property.
      protected java.beans.VetoableChangeSupport getVetoableChangeSupport()  
      boolean hasPropertyChangeListeners​(java.lang.String propertyName)
      Checks if there are any listeners for a specific property, including those registered on all properties.
      boolean hasVetoableChangeListeners​(java.lang.String propertyName)
      Checks if there are any vetoable change listeners for a specific property, including those registered on all properties.
      void removePropertyChangeListener​(java.beans.PropertyChangeListener listener)
      Remove a property change listener from the listener list.
      void removePropertyChangeListener​(java.lang.String propertyName, java.beans.PropertyChangeListener listener)
      Remove a property change listener for a specific property.
      void removeVetoableChangeListener​(java.beans.VetoableChangeListener listener)
      Removes a vetoable change listener from the listener list.
      void removeVetoableChangeListener​(java.lang.String propertyName, java.beans.VetoableChangeListener listener)
      Removes a vetoable change listener for a specific property.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • NO_PROPERTY_CHANGE_LISTENERS

        protected static final java.beans.PropertyChangeListener[] NO_PROPERTY_CHANGE_LISTENERS
        A convenience static empty array of property change listeners.

      • NO_VETOABLE_CHANGE_LISTENERS

        protected static final java.beans.VetoableChangeListener[] NO_VETOABLE_CHANGE_LISTENERS
        A convenience static empty array of vetoable change listeners.

    • Constructor Detail

      • BoundPropertyObject

        public BoundPropertyObject()
        Default constructor.

    • Method Detail

      • getPropertyChangeSupport

        protected java.beans.PropertyChangeSupport getPropertyChangeSupport()
        Returns:
        Support for property change event management, creating support if necessary.

      • getVetoableChangeSupport

        protected java.beans.VetoableChangeSupport getVetoableChangeSupport()
        Returns:
        Support for vetoable change management, creating support if necessary.

      • getRepeatPropertyChangeListener

        protected java.beans.PropertyChangeListener getRepeatPropertyChangeListener()
        Returns:
        A property change listener to repeat copies of events received, using this object as the source.

      • getForwardPropertyChangeListener

        protected java.beans.PropertyChangeListener getForwardPropertyChangeListener()
        Returns:
        A lazily-created property change listener to forward along events received unmodified.

      • getRepeatVetoableChangeListener

        protected java.beans.VetoableChangeListener getRepeatVetoableChangeListener()
        Returns:
        A vetoable change listener to repeat copies of events received, using this object as the source.

      • addPropertyChangeListener

        public void addPropertyChangeListener​(java.beans.PropertyChangeListener listener)
        Adds a property change listener to the listener list. The listener is registered for all properties.

        If the listener is null, no exception is thrown and no action is performed.

        Specified by:
        addPropertyChangeListener in interface PropertyBindable
        Parameters:
        listener - The PropertyChangeListener to be added.
        See Also:
        PropertyChangeEvent

      • removePropertyChangeListener

        public void removePropertyChangeListener​(java.beans.PropertyChangeListener listener)
        Remove a property change listener from the listener list. This removes a PropertyChangeListener that was registered for all properties.

        If the listener is null, no exception is thrown and no action is performed.

        Specified by:
        removePropertyChangeListener in interface PropertyBindable
        Parameters:
        listener - The PropertyChangeListener to be removed.

      • addPropertyChangeListener

        public void addPropertyChangeListener​(java.lang.String propertyName,
                                      java.beans.PropertyChangeListener listener)
        Add a property change listener for a specific property. The listener will be invoked only when a call to firePropertyChange(String, Object, Object) names that specific property.

        If the listener is null, no exception is thrown and no action is performed.

        Specified by:
        addPropertyChangeListener in interface PropertyBindable
        Parameters:
        propertyName - The name of the property to listen on.
        listener - The PropertyChangeListener to be added.

      • removePropertyChangeListener

        public void removePropertyChangeListener​(java.lang.String propertyName,
                                         java.beans.PropertyChangeListener listener)
        Remove a property change listener for a specific property.

        If the listener is null, no exception is thrown and no action is performed.

        Specified by:
        removePropertyChangeListener in interface PropertyBindable
        Parameters:
        propertyName - The name of the property that was listened on.
        listener - The PropertyChangeListener to be removed

      • getPropertyChangeListeners

        public java.beans.PropertyChangeListener[] getPropertyChangeListeners()
        Returns an array of all the listeners that were added to the with addPropertyChangeListener(PropertyChangeListener). If some listeners have been added with a named property, then the returned array will be a mixture of PropertyChangeListeners and PropertyChangeListenerProxy s. If the calling method is interested in distinguishing the listeners then it must test each element to see if it's a PropertyChangeListenerProxy, perform the cast, and examine the parameter.
        Specified by:
        getPropertyChangeListeners in interface PropertyBindable
        Returns:
        all of the PropertyChangeListeners added or an empty array if no listeners have been added
        See Also:
        PropertyChangeListenerProxy

      • getPropertyChangeListeners

        public java.beans.PropertyChangeListener[] getPropertyChangeListeners​(java.lang.String propertyName)
        Returns an array of all the listeners which have been associated with the named property.
        Specified by:
        getPropertyChangeListeners in interface PropertyBindable
        Parameters:
        propertyName - The name of the property.
        Returns:
        All of the PropertyChangeListeners associated with the named property; if no such listeners have been added or if propertyName is null, an empty array is returned

      • hasPropertyChangeListeners

        public boolean hasPropertyChangeListeners​(java.lang.String propertyName)
        Checks if there are any listeners for a specific property, including those registered on all properties. If propertyName is null, this method only checks for listeners registered on all properties.
        Specified by:
        hasPropertyChangeListeners in interface PropertyBindable
        Parameters:
        propertyName - The property name.
        Returns:
        true if there are one or more listeners for the given property.

      • firePropertyChange

        protected <V> void firePropertyChange​(java.lang.String propertyName,
                                      V oldValue,
                                      V newValue)
        Reports that a bound property has changed. This method can be called when a bound property has changed and it will send the appropriate property change event to any registered property change listeners. No event is fired if old and new are both null or are both non-null and equal according to the Object.equals(java.lang.Object) method. No event is fired if no listeners are registered for the given property. This method delegates actual firing of the event to firePropertyChange(PropertyChangeEvent).
        Type Parameters:
        V - The type of the property values.
        Parameters:
        propertyName - The name of the property being changed.
        oldValue - The old property value.
        newValue - The new property value.
        See Also:
        firePropertyChange(PropertyChangeEvent), hasPropertyChangeListeners(String), GenericPropertyChangeEvent, GenericPropertyChangeListener

      • firePropertyChange

        protected void firePropertyChange​(java.lang.String propertyName,
                                  int oldValue,
                                  int newValue)
        Reports that a bound integer property has changed, reporting old and new values of type Integer. No event is fired if the values are equal, or if no event is fired if no listeners are registered for the given property. This method delegates actual firing of the event to firePropertyChange(String, Object, Object).
        Parameters:
        propertyName - The name of the property being changed.
        oldValue - The old property value.
        newValue - The new property value.

      • firePropertyChange

        protected void firePropertyChange​(java.lang.String propertyName,
                                  long oldValue,
                                  long newValue)
        Reports that a bound long property has changed, reporting old and new values of type Long. No event is fired if the values are equal, or if no event is fired if no listeners are registered for the given property. This method delegates actual firing of the event to firePropertyChange(String, Object, Object).
        Parameters:
        propertyName - The name of the property being changed.
        oldValue - The old property value.
        newValue - The new property value.

      • firePropertyChange

        protected void firePropertyChange​(java.lang.String propertyName,
                                  boolean oldValue,
                                  boolean newValue)
        Reports that a bound boolean property has changed, reporting old and new values of type Boolean. No event is fired if the values are equal, or if no event is fired if no listeners are registered for the given property. This method delegates actual firing of the event to firePropertyChange(String, Object, Object).
        Parameters:
        propertyName - The name of the property being changed.
        oldValue - The old property value.
        newValue - The new property value.

      • firePropertyChange

        protected void firePropertyChange​(java.beans.PropertyChangeEvent propertyChangeEvent)
        Reports that a bound property has changed. This method does the actual delegation to the property change support.
        Parameters:
        propertyChangeEvent - The event to fire.

      • createPostponedPropertyChangeEvent

        protected PostponedPropertyChangeEvent createPostponedPropertyChangeEvent​(java.beans.PropertyChangeEvent propertyChangeEvent)
        Creates an object representing a postponement of firing the property change event.
        Parameters:
        propertyChangeEvent - The property change event the firing of which to postpone.
        Returns:
        A newly created postponed property change event.

      • addVetoableChangeListener

        public void addVetoableChangeListener​(java.beans.VetoableChangeListener listener)
        Adds a vetoable listener to the listener list. The listener is registered for all properties.

        The same listener object may be added more than once, and will be called as many times as it is added.

        If listener is null, no exception is thrown and no action is taken.

        Specified by:
        addVetoableChangeListener in interface PropertyConstrainable
        Parameters:
        listener - The VetoableChangeListener to be added.

      • removeVetoableChangeListener

        public void removeVetoableChangeListener​(java.beans.VetoableChangeListener listener)
        Removes a vetoable change listener from the listener list. This removes a VetoableChangeListener that was registered for all properties.

        If listener was added more than once to the same event source, it will be notified one less time after being removed.

        If listener is null, or was never added, no exception is thrown and no action is taken.

        Specified by:
        removeVetoableChangeListener in interface PropertyConstrainable
        Parameters:
        listener - The VetoableChangeListener to be removed

      • addVetoableChangeListener

        public void addVetoableChangeListener​(java.lang.String propertyName,
                                      java.beans.VetoableChangeListener listener)
        Adds a vetoable change listener for a specific property. The listener will be invoked only when a call to fireVetoableChange(String, int, int) names that specific property.

        The same listener object may be added more than once. For each property, the listener will be invoked the number of times it was added for that property.

        If propertyName or listener is null, no exception is thrown and no action is taken.

        Specified by:
        addVetoableChangeListener in interface PropertyConstrainable
        Parameters:
        propertyName - The name of the property to listen on.
        listener - The VetoableChangeListener to be added.

      • removeVetoableChangeListener

        public void removeVetoableChangeListener​(java.lang.String propertyName,
                                         java.beans.VetoableChangeListener listener)
        Removes a vetoable change listener for a specific property.

        If listener was added more than once to the same event source for the specified property, it will be notified one less time after being removed.

        If propertyName is null, no exception is thrown and no action is taken.

        If listener is null, or was never added for the specified property, no exception is thrown and no action is taken.

        Specified by:
        removeVetoableChangeListener in interface PropertyConstrainable
        Parameters:
        propertyName - The name of the property that was listened on.
        listener - The VetoableChangeListener to be removed.

      • getVetoableChangeListeners

        public java.beans.VetoableChangeListener[] getVetoableChangeListeners()
        Returns the list of vetoable change listeners. If named vetoable change listeners were added, then VetoableChangeListenerProxy wrappers will returned.
        Specified by:
        getVetoableChangeListeners in interface PropertyConstrainable
        Returns:
        All added vetoable change listeners, including vetoable change listener proxys if named vetoable change listeners were added.

      • getVetoableChangeListeners

        public java.beans.VetoableChangeListener[] getVetoableChangeListeners​(java.lang.String propertyName)
        Returns an array of all the listeners which have been associated with the named property.
        Specified by:
        getVetoableChangeListeners in interface PropertyConstrainable
        Parameters:
        propertyName - The name of the property being listened to.
        Returns:
        All the VetoableChangeListeners associated with the named property; if no such listeners have been added, or if propertyName is null, an empty array is returned.

      • hasVetoableChangeListeners

        public boolean hasVetoableChangeListeners​(java.lang.String propertyName)
        Checks if there are any vetoable change listeners for a specific property, including those registered on all properties. If propertyName is null, this method only checks for listeners registered on all properties.
        Specified by:
        hasVetoableChangeListeners in interface PropertyConstrainable
        Parameters:
        propertyName - The property name.
        Returns:
        true if there are one or more listeners for the given property.

      • fireVetoableChange

        public <V> void fireVetoableChange​(java.lang.String propertyName,
                                   V oldValue,
                                   V newValue)
                            throws java.beans.PropertyVetoException
        Reports a vetoable property update to any registered listeners. If any veotable change listeners vetos the change, then a new event will be fired reverting all the listeners to the old value, after which the PropertyVetoException will be rethrown. No event is fired if old and new are equal and non- null. This method delegates actual firing of the event to fireVetoableChange(PropertyChangeEvent).
        Type Parameters:
        V - The type of the property values.
        Parameters:
        propertyName - The name of the property that is about to change.
        oldValue - The old value of the property.
        newValue - The new value of the property.
        Throws:
        java.beans.PropertyVetoException - if the recipient wishes the property change to be rolled back.
        See Also:
        fireVetoableChange(PropertyChangeEvent), hasVetoableChangeListeners(String), GenericPropertyChangeEvent, GenericVetoableChangeListener

      • fireVetoableChange

        protected void fireVetoableChange​(java.lang.String propertyName,
                                  int oldValue,
                                  int newValue)
                           throws java.beans.PropertyVetoException
        Reports that an integer vetoable property updtae to any registered listeners, reporting old and new values of type Integer. No event is fired if the values are equal, or if no event is fired if no listeners are registered for the given property. This method delegates actual firing of the event to fireVetoableChange(String, Object, Object).
        Parameters:
        propertyName - The name of the property that is about to change.
        oldValue - The old property value.
        newValue - The new property value.
        Throws:
        java.beans.PropertyVetoException - if the recipient wishes the property change to be rolled back.

      • fireVetoableChange

        protected void fireVetoableChange​(java.lang.String propertyName,
                                  boolean oldValue,
                                  boolean newValue)
                           throws java.beans.PropertyVetoException
        Reports that an integer vetoable property updtae to any registered listeners, reporting old and new values of type Boolean. No event is fired if the values are equal, or if no event is fired if no listeners are registered for the given property. This method delegates actual firing of the event to fireVetoableChange(String, Object, Object).
        Parameters:
        propertyName - The name of the property that is about to change.
        oldValue - The old property value.
        newValue - The new property value.
        Throws:
        java.beans.PropertyVetoException - if the recipient wishes the property change to be rolled back.

      • fireVetoableChange

        public void fireVetoableChange​(java.beans.PropertyChangeEvent propertyChangeEvent)
                        throws java.beans.PropertyVetoException
        Fires a vetoable property update to any registered listeners. If any veotable change listeners vetos the change, then a new event will be fired reverting all the listeners to the old value, after which the PropertyVetoException will be rethrown. No event is fired if old and new are equal and non- null. This method does the actual delegation to the vetoable change support.
        Parameters:
        propertyChangeEvent - The event to fire.
        Throws:
        java.beans.PropertyVetoException - if the recipient wishes the property change to be rolled back.