Bean (JGoodies Common 1.8 API)
Date: 2015-01-03

com.jgoodies.common.bean

## Class Bean

- java.lang.Object
- - com.jgoodies.common.bean.Bean

- All Implemented Interfaces:
    ObservableBean, ObservableBean2, Serializable

      public abstract class Bean
      extends Object
      implements Serializable, ObservableBean2

  An abstract superclass that minimizes the effort required to provide change support for bound and constrained Bean properties. This class follows the conventions and recommendations as described in the Java Bean Specification.

  This class uses the standard `PropertyChangeSupport` to notify registered listeners about changes. Subclasses can use different change support implementations by overriding `createPropertyChangeSupport`, for example to ensure that notifications are sent in the Event dispatch thread, or to compare old and new values with `==` not `equals`.

  Author:
    Karsten Lentzsch
  See Also:
    `PropertyChangeEvent`, `PropertyChangeListener`, `PropertyChangeSupport`, `VetoableChangeListener`, `VetoableChangeSupport`, Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected PropertyChangeSupport` | `changeSupport` If any`PropertyChangeListeners` have been registered, the `changeSupport` field describes them.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Bean()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addPropertyChangeListener(PropertyChangeListener listener)` Adds a PropertyChangeListener to the listener list.
    `void` | `addPropertyChangeListener(String propertyName, PropertyChangeListener listener)` Adds a PropertyChangeListener to the listener list for a specific property.
    `void` | `addVetoableChangeListener(String propertyName, VetoableChangeListener listener)` Adds a VetoableChangeListener to the listener list for a specific property.
    `void` | `addVetoableChangeListener(VetoableChangeListener listener)` Adds a VetoableChangeListener to the listener list.
    `protected PropertyChangeSupport` | `createPropertyChangeSupport(Object bean)` Creates and returns a PropertyChangeSupport for the given bean.
    `protected void` | `fireIndexedPropertyChange(String propertyName, int index, boolean oldValue, boolean newValue)` Report a `boolean` bound indexed property update to any registered listeners.
    `protected void` | `fireIndexedPropertyChange(String propertyName, int index, int oldValue, int newValue)` Report an `int` bound indexed property update to any registered listeners.
    `protected void` | `fireIndexedPropertyChange(String propertyName, int index, Object oldValue, Object newValue)` Report a bound indexed property update to any registered listeners.
    `protected void` | `fireMultiplePropertiesChanged()` Indicates that an arbitrary set of bound properties have changed.
    `protected void` | `firePropertyChange(PropertyChangeEvent event)` General support for reporting bound property changes.
    `protected void` | `firePropertyChange(String propertyName, boolean oldValue, boolean newValue)` Support for reporting bound property changes for boolean properties.
    `protected void` | `firePropertyChange(String propertyName, double oldValue, double newValue)` Support for reporting bound property changes for integer properties.
    `protected void` | `firePropertyChange(String propertyName, float oldValue, float newValue)` Support for reporting bound property changes for integer properties.
    `protected void` | `firePropertyChange(String propertyName, int oldValue, int newValue)` Support for reporting bound property changes for integer properties.
    `protected void` | `firePropertyChange(String propertyName, long oldValue, long newValue)` Support for reporting bound property changes for integer properties.
    `protected void` | `firePropertyChange(String propertyName, Object oldValue, Object newValue)` Support for reporting bound property changes for Object properties.
    `protected void` | `fireVetoableChange(PropertyChangeEvent event)` General support for reporting constrained property changes.
    `protected void` | `fireVetoableChange(String propertyName, boolean oldValue, boolean newValue)` Support for reporting changes for constrained boolean properties.
    `protected void` | `fireVetoableChange(String propertyName, double oldValue, double newValue)` Support for reporting changes for constrained integer properties.
    `protected void` | `fireVetoableChange(String propertyName, float oldValue, float newValue)` Support for reporting changes for constrained integer properties.
    `protected void` | `fireVetoableChange(String propertyName, int oldValue, int newValue)` Support for reporting changes for constrained integer properties.
    `protected void` | `fireVetoableChange(String propertyName, long oldValue, long newValue)` Support for reporting changes for constrained integer properties.
    `protected void` | `fireVetoableChange(String propertyName, Object oldValue, Object newValue)` Support for reporting changes for constrained Object properties.
    `PropertyChangeListener[]` | `getPropertyChangeListeners()` Returns an array of all the property change listeners registered on this component.
    `PropertyChangeListener[]` | `getPropertyChangeListeners(String propertyName)` Returns an array of all the listeners which have been associated with the named property.
    `VetoableChangeListener[]` | `getVetoableChangeListeners()` Returns an array of all the property change listeners registered on this component.
    `VetoableChangeListener[]` | `getVetoableChangeListeners(String propertyName)` Returns an array of all the listeners which have been associated with the named property.
    `void` | `removePropertyChangeListener(PropertyChangeListener listener)` Removes a PropertyChangeListener from the listener list.
    `void` | `removePropertyChangeListener(String propertyName, PropertyChangeListener listener)` Removes a PropertyChangeListener from the listener list for a specific property.
    `void` | `removeVetoableChangeListener(String propertyName, VetoableChangeListener listener)` Removes a VetoableChangeListener from the listener list for a specific property.
    `void` | `removeVetoableChangeListener(VetoableChangeListener listener)` Removes a VetoableChangeListener from the listener list.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### changeSupport

          protected transient PropertyChangeSupport changeSupport

      If any`PropertyChangeListeners` have been registered, the `changeSupport` field describes them.
      See Also:
        `addPropertyChangeListener(PropertyChangeListener)`, `addPropertyChangeListener(String, PropertyChangeListener)`, `removePropertyChangeListener(PropertyChangeListener)`, `removePropertyChangeListener(String, PropertyChangeListener)`, `PropertyChangeSupport`

  - ### Constructor Detail

    - #### Bean

          public Bean()

  - ### Method Detail

    - #### addPropertyChangeListener

          public final void addPropertyChangeListener(PropertyChangeListener listener)

      Adds a PropertyChangeListener to the listener list. The listener is registered for all bound properties of this class.

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

      Specified by:
        `addPropertyChangeListener` in interface `ObservableBean`
      Parameters:
        `listener` - the PropertyChangeListener to be added
      See Also:
        `removePropertyChangeListener(PropertyChangeListener)`, `removePropertyChangeListener(String, PropertyChangeListener)`, `addPropertyChangeListener(String, PropertyChangeListener)`, `getPropertyChangeListeners()`

    - #### removePropertyChangeListener

          public final void removePropertyChangeListener(PropertyChangeListener listener)

      Removes a PropertyChangeListener from the listener list. This method should be used to remove PropertyChangeListeners that were registered for all bound properties of this class.

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

      Specified by:
        `removePropertyChangeListener` in interface `ObservableBean`
      Parameters:
        `listener` - the PropertyChangeListener to be removed
      See Also:
        `addPropertyChangeListener(PropertyChangeListener)`, `addPropertyChangeListener(String, PropertyChangeListener)`, `removePropertyChangeListener(String, PropertyChangeListener)`, `getPropertyChangeListeners()`

    - #### addPropertyChangeListener

          public final void addPropertyChangeListener(String propertyName,
                                       PropertyChangeListener listener)

      Adds a PropertyChangeListener to the listener list for a specific property. The specified property may be user-defined.

      Note that if this Model is inheriting a bound property, then no event will be fired in response to a change in the inherited property.

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

      Specified by:
        `addPropertyChangeListener` in interface `ObservableBean2`
      Parameters:
        `propertyName` - one of the property names listed above
        `listener` - the PropertyChangeListener to be added
      See Also:
        `removePropertyChangeListener(String, PropertyChangeListener)`, `addPropertyChangeListener(String, PropertyChangeListener)`, `getPropertyChangeListeners(String)`

    - #### removePropertyChangeListener

          public final void removePropertyChangeListener(String propertyName,
                                          PropertyChangeListener listener)

      Removes a PropertyChangeListener from the listener list for a specific property. This method should be used to remove PropertyChangeListeners that were registered for a specific bound property.

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

      Specified by:
        `removePropertyChangeListener` in interface `ObservableBean2`
      Parameters:
        `propertyName` - a valid property name
        `listener` - the PropertyChangeListener to be removed
      See Also:
        `addPropertyChangeListener(String, PropertyChangeListener)`, `removePropertyChangeListener(PropertyChangeListener)`, `getPropertyChangeListeners(String)`

    - #### addVetoableChangeListener

          public final void addVetoableChangeListener(VetoableChangeListener listener)

      Adds a VetoableChangeListener to the listener list. The listener is registered for all bound properties of this class.

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

      Parameters:
        `listener` - the VetoableChangeListener to be added
      See Also:
        `removeVetoableChangeListener(String, VetoableChangeListener)`, `addVetoableChangeListener(String, VetoableChangeListener)`, `getVetoableChangeListeners()`

    - #### removeVetoableChangeListener

          public final void removeVetoableChangeListener(VetoableChangeListener listener)

      Removes a VetoableChangeListener from the listener list. This method should be used to remove VetoableChangeListeners that were registered for all bound properties of this class.

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

      Parameters:
        `listener` - the VetoableChangeListener to be removed
      See Also:
        `addVetoableChangeListener(String, VetoableChangeListener)`, `removeVetoableChangeListener(String, VetoableChangeListener)`, `getVetoableChangeListeners()`

    - #### addVetoableChangeListener

          public final void addVetoableChangeListener(String propertyName,
                                       VetoableChangeListener listener)

      Adds a VetoableChangeListener to the listener list for a specific property. The specified property may be user-defined.

      Note that if this Model is inheriting a bound property, then no event will be fired in response to a change in the inherited property.

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

      Parameters:
        `propertyName` - one of the property names listed above
        `listener` - the VetoableChangeListener to be added
      See Also:
        `removeVetoableChangeListener(String, VetoableChangeListener)`, `addVetoableChangeListener(String, VetoableChangeListener)`, `getVetoableChangeListeners(String)`

    - #### removeVetoableChangeListener

          public final void removeVetoableChangeListener(String propertyName,
                                          VetoableChangeListener listener)

      Removes a VetoableChangeListener from the listener list for a specific property. This method should be used to remove VetoableChangeListeners that were registered for a specific bound property.

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

      Parameters:
        `propertyName` - a valid property name
        `listener` - the VetoableChangeListener to be removed
      See Also:
        `addVetoableChangeListener(String, VetoableChangeListener)`, `removeVetoableChangeListener(VetoableChangeListener)`, `getVetoableChangeListeners(String)`

    - #### getPropertyChangeListeners

          public final PropertyChangeListener[] getPropertyChangeListeners()

      Returns an array of all the property change listeners registered on this component.
      Specified by:
        `getPropertyChangeListeners` in interface `ObservableBean2`
      Returns:
        all of this component's `PropertyChangeListener`s or an empty array if no property change listeners are currently registered
      See Also:
        `addPropertyChangeListener(PropertyChangeListener)`, `removePropertyChangeListener(PropertyChangeListener)`, `getPropertyChangeListeners(String)`, `PropertyChangeSupport.getPropertyChangeListeners()`

    - #### getPropertyChangeListeners

          public final PropertyChangeListener[] getPropertyChangeListeners(String propertyName)

      Returns an array of all the listeners which have been associated with the named property.
      Specified by:
        `getPropertyChangeListeners` in interface `ObservableBean2`
      Parameters:
        `propertyName` - the name of the property to lookup listeners
      Returns:
        all of the `PropertyChangeListeners` associated with the named property or an empty array if no listeners have been added
      See Also:
        `addPropertyChangeListener(String, PropertyChangeListener)`, `removePropertyChangeListener(String, PropertyChangeListener)`, `getPropertyChangeListeners()`

    - #### getVetoableChangeListeners

          public final VetoableChangeListener[] getVetoableChangeListeners()

      Returns an array of all the property change listeners registered on this component.
      Returns:
        all of this component's `VetoableChangeListener`s or an empty array if no property change listeners are currently registered
      See Also:
        `addVetoableChangeListener(VetoableChangeListener)`, `removeVetoableChangeListener(VetoableChangeListener)`, `getVetoableChangeListeners(String)`, `VetoableChangeSupport.getVetoableChangeListeners()`

    - #### getVetoableChangeListeners

          public final VetoableChangeListener[] getVetoableChangeListeners(String propertyName)

      Returns an array of all the listeners which have been associated with the named property.
      Parameters:
        `propertyName` - the name of the property to lookup listeners
      Returns:
        all of the `VetoableChangeListeners` associated with the named property or an empty array if no listeners have been added
      See Also:
        `addVetoableChangeListener(String, VetoableChangeListener)`, `removeVetoableChangeListener(String, VetoableChangeListener)`, `getVetoableChangeListeners()`

    - #### createPropertyChangeSupport

          protected PropertyChangeSupport createPropertyChangeSupport(Object bean)

      Creates and returns a PropertyChangeSupport for the given bean. Invoked by the first call to `addPropertyChangeListener(java.beans.PropertyChangeListener)` when lazily creating the sole change support instance used throughout this bean.

      This default implementation creates a `PropertyChangeSupport`. Subclasses may override to return other change support implementations. For example to ensure that listeners are notified in the Event dispatch thread (EDT change support). The JGoodies Binding uses an extended change support that allows to configure whether the old and new value are compared with `==` or `equals`.

      Parameters:
        `bean` - the bean to create a change support for
      Returns:
        the new change support

    - #### firePropertyChange

          protected final void firePropertyChange(PropertyChangeEvent event)

      General support for reporting bound property changes. Sends the given PropertyChangeEvent to any registered PropertyChangeListener.

      Most bean setters will invoke the fireXXX methods that get a property name and the old and new value. However some frameworks and setters may prefer to use this general method. Also, this method allows to fire IndexedPropertyChangeEvents that have been introduced in Java 5.

      Parameters:
        `event` - describes the property change
      Since:
        1.3

    - #### firePropertyChange

          protected final void firePropertyChange(String propertyName,
                                Object oldValue,
                                Object newValue)

      Support for reporting bound property changes for Object properties. This method can be called when a bound property has changed and it will send the appropriate PropertyChangeEvent to any registered PropertyChangeListeners.
      Parameters:
        `propertyName` - the property whose value has changed
        `oldValue` - the property's previous value
        `newValue` - the property's new value

    - #### firePropertyChange

          protected final void firePropertyChange(String propertyName,
                                boolean oldValue,
                                boolean newValue)

      Support for reporting bound property changes for boolean properties. This method can be called when a bound property has changed and it will send the appropriate PropertyChangeEvent to any registered PropertyChangeListeners.
      Parameters:
        `propertyName` - the property whose value has changed
        `oldValue` - the property's previous value
        `newValue` - the property's new value

    - #### firePropertyChange

          protected final void firePropertyChange(String propertyName,
                                double oldValue,
                                double newValue)

      Support for reporting bound property changes for integer properties. This method can be called when a bound property has changed and it will send the appropriate PropertyChangeEvent to any registered PropertyChangeListeners.
      Parameters:
        `propertyName` - the property whose value has changed
        `oldValue` - the property's previous value
        `newValue` - the property's new value

    - #### firePropertyChange

          protected final void firePropertyChange(String propertyName,
                                float oldValue,
                                float newValue)

      Support for reporting bound property changes for integer properties. This method can be called when a bound property has changed and it will send the appropriate PropertyChangeEvent to any registered PropertyChangeListeners.
      Parameters:
        `propertyName` - the property whose value has changed
        `oldValue` - the property's previous value
        `newValue` - the property's new value

    - #### firePropertyChange

          protected final void firePropertyChange(String propertyName,
                                int oldValue,
                                int newValue)

      Support for reporting bound property changes for integer properties. This method can be called when a bound property has changed and it will send the appropriate PropertyChangeEvent to any registered PropertyChangeListeners.
      Parameters:
        `propertyName` - the property whose value has changed
        `oldValue` - the property's previous value
        `newValue` - the property's new value

    - #### firePropertyChange

          protected final void firePropertyChange(String propertyName,
                                long oldValue,
                                long newValue)

      Support for reporting bound property changes for integer properties. This method can be called when a bound property has changed and it will send the appropriate PropertyChangeEvent to any registered PropertyChangeListeners.
      Parameters:
        `propertyName` - the property whose value has changed
        `oldValue` - the property's previous value
        `newValue` - the property's new value

    - #### fireMultiplePropertiesChanged

          protected final void fireMultiplePropertiesChanged()

      Indicates that an arbitrary set of bound properties have changed. Sends a PropertyChangeEvent with property name, old and new value set to `null` to any registered PropertyChangeListeners.
      Since:
        1.0.3
      See Also:
        `PropertyChangeEvent`

    - #### fireIndexedPropertyChange

          protected final void fireIndexedPropertyChange(String propertyName,
                                       int index,
                                       Object oldValue,
                                       Object newValue)

      Report a bound indexed property update to any registered listeners.

      No event is fired if old and new values are equal and non-null.

      Parameters:
        `propertyName` - The programmatic name of the property that was changed.
        `index` - index of the property element that was changed.
        `oldValue` - The old value of the property.
        `newValue` - The new value of the property.
      Since:
        2.0

    - #### fireIndexedPropertyChange

          protected final void fireIndexedPropertyChange(String propertyName,
                                       int index,
                                       int oldValue,
                                       int newValue)

      Report an `int` bound indexed property update to any registered listeners.

      No event is fired if old and new values are equal and non-null.

      This is merely a convenience wrapper around the more general fireIndexedPropertyChange method which takes Object values.

      Parameters:
        `propertyName` - The programmatic name of the property that was changed.
        `index` - index of the property element that was changed.
        `oldValue` - The old value of the property.
        `newValue` - The new value of the property.
      Since:
        2.0

    - #### fireIndexedPropertyChange

          protected final void fireIndexedPropertyChange(String propertyName,
                                       int index,
                                       boolean oldValue,
                                       boolean newValue)

      Report a `boolean` bound indexed property update to any registered listeners.

      No event is fired if old and new values are equal and non-null.

      This is merely a convenience wrapper around the more general fireIndexedPropertyChange method which takes Object values.

      Parameters:
        `propertyName` - The programmatic name of the property that was changed.
        `index` - index of the property element that was changed.
        `oldValue` - The old value of the property.
        `newValue` - The new value of the property.
      Since:
        2.0

    - #### fireVetoableChange

          protected final void fireVetoableChange(PropertyChangeEvent event)
                                           throws PropertyVetoException

      General support for reporting constrained property changes. Sends the given PropertyChangeEvent to any registered PropertyChangeListener.

      Most bean setters will invoke the fireXXX methods that get a property name and the old and new value. However some frameworks and setters may prefer to use this general method. Also, this method allows to fire IndexedPropertyChangeEvents that have been introduced in Java 5.

      Parameters:
        `event` - describes the property change
      Throws:
        `PropertyVetoException` - if a constrained property change is rejected
      Since:
        1.3

    - #### fireVetoableChange

          protected final void fireVetoableChange(String propertyName,
                                Object oldValue,
                                Object newValue)
                                           throws PropertyVetoException

      Support for reporting changes for constrained Object properties. This method can be called before a constrained property will be changed and it will send the appropriate PropertyChangeEvent to any registered VetoableChangeListeners.
      Parameters:
        `propertyName` - the property whose value has changed
        `oldValue` - the property's previous value
        `newValue` - the property's new value
      Throws:
        `PropertyVetoException` - if a constrained property change is rejected

    - #### fireVetoableChange

          protected final void fireVetoableChange(String propertyName,
                                boolean oldValue,
                                boolean newValue)
                                           throws PropertyVetoException

      Support for reporting changes for constrained boolean properties. This method can be called before a constrained property will be changed and it will send the appropriate PropertyChangeEvent to any registered VetoableChangeListeners.
      Parameters:
        `propertyName` - the property whose value has changed
        `oldValue` - the property's previous value
        `newValue` - the property's new value
      Throws:
        `PropertyVetoException` - if a constrained property change is rejected

    - #### fireVetoableChange

          protected final void fireVetoableChange(String propertyName,
                                double oldValue,
                                double newValue)
                                           throws PropertyVetoException

      Support for reporting changes for constrained integer properties. This method can be called before a constrained property will be changed and it will send the appropriate PropertyChangeEvent to any registered VetoableChangeListeners.
      Parameters:
        `propertyName` - the property whose value has changed
        `oldValue` - the property's previous value
        `newValue` - the property's new value
      Throws:
        `PropertyVetoException` - if a constrained property change is rejected

    - #### fireVetoableChange

          protected final void fireVetoableChange(String propertyName,
                                int oldValue,
                                int newValue)
                                           throws PropertyVetoException

      Support for reporting changes for constrained integer properties. This method can be called before a constrained property will be changed and it will send the appropriate PropertyChangeEvent to any registered VetoableChangeListeners.
      Parameters:
        `propertyName` - the property whose value has changed
        `oldValue` - the property's previous value
        `newValue` - the property's new value
      Throws:
        `PropertyVetoException` - if a constrained property change is rejected

    - #### fireVetoableChange

          protected final void fireVetoableChange(String propertyName,
                                float oldValue,
                                float newValue)
                                           throws PropertyVetoException

      Support for reporting changes for constrained integer properties. This method can be called before a constrained property will be changed and it will send the appropriate PropertyChangeEvent to any registered VetoableChangeListeners.
      Parameters:
        `propertyName` - the property whose value has changed
        `oldValue` - the property's previous value
        `newValue` - the property's new value
      Throws:
        `PropertyVetoException` - if a constrained property change is rejected

    - #### fireVetoableChange

          protected final void fireVetoableChange(String propertyName,
                                long oldValue,
                                long newValue)
                                           throws PropertyVetoException

      Support for reporting changes for constrained integer properties. This method can be called before a constrained property will be changed and it will send the appropriate PropertyChangeEvent to any registered VetoableChangeListeners.
      Parameters:
        `propertyName` - the property whose value has changed
        `oldValue` - the property's previous value
        `newValue` - the property's new value
      Throws:
        `PropertyVetoException` - if a constrained property change is rejected

Copyright © 2009-2014 JGoodies Software GmbH. All Rights Reserved.