Package com.globalmentor.beans

Class BoundPropertyObject

java.lang.Object
com.globalmentor.beans.BoundPropertyObject
All Implemented Interfaces:
PropertyBindable, PropertyConstrainable
Direct Known Subclasses:
AbstractTask, BoundPropertyResource, DefaultModifiable, DefaultURIAccessible
public class BoundPropertyObject extends 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:

  • Field Details

    • NO_PROPERTY_CHANGE_LISTENERS

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

    • NO_VETOABLE_CHANGE_LISTENERS

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

  • Constructor Details

    • BoundPropertyObject

      public BoundPropertyObject()
      Default constructor.

  • Method Details

    • getPropertyChangeSupport

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

    • getVetoableChangeSupport

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

    • getRepeatPropertyChangeListener

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

    • getForwardPropertyChangeListener

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

    • getRepeatVetoableChangeListener

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

    • addPropertyChangeListener

      public void addPropertyChangeListener(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:

    • removePropertyChangeListener

      public void removePropertyChangeListener(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(String propertyName, 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(String propertyName, 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 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:

    • getPropertyChangeListeners

      public PropertyChangeListener[] getPropertyChangeListeners(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(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(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

      protected void firePropertyChange(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(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(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(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(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(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(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(String propertyName, 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(String propertyName, 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 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 VetoableChangeListener[] getVetoableChangeListeners(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(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(String propertyName, V oldValue, V newValue) throws PropertyVetoException
      Reports a vetoable property update to any registered listeners. If any vetoable change listeners vetoes 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:
      PropertyVetoException - if the recipient wishes the property change to be rolled back.
      See Also:

    • fireVetoableChange

      protected void fireVetoableChange(String propertyName, int oldValue, int newValue) throws 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:
      PropertyVetoException - if the recipient wishes the property change to be rolled back.

    • fireVetoableChange

      protected void fireVetoableChange(String propertyName, boolean oldValue, boolean newValue) throws 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:
      PropertyVetoException - if the recipient wishes the property change to be rolled back.

    • fireVetoableChange

      public void fireVetoableChange(PropertyChangeEvent propertyChangeEvent) throws PropertyVetoException
      Fires a vetoable property update to any registered listeners. If any vetoable change listeners vetoes 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:
      PropertyVetoException - if the recipient wishes the property change to be rolled back.