Java Doc for PresentationModel.java in  » Swing-Library » jgoodies-data-binding » com » jgoodies » binding » Java Source Code / Java DocumentationJava Source Code and Java Documentation

This class minimizes the effort required to bind, edit, buffer, and observe the bound properties of an exchangeable bean. Therefore it provides five groups of features that are described below:

1. adapt bean properties,
2. change the adapted bean,
3. buffer values,
4. observe the buffering state, and
5. track changes in adapted bean properties.

Typically this class will be extended to add custom models, Actions, presentation logic, model operations and other higher-level behavior. However, in simple cases you can use this class as-is. Several methods are intended to be used as-is and a typical subclass should not modify them. For example #isChanged, #isBuffering, #getBean, #setBean, #getBeanChannel, #getModel, #getBufferedModel, #getTriggerChannel, #setTriggerChannel, #triggerCommit and #triggerFlush.

Adapting Bean Properties
The method PresentationModel.getModel(String) vends ValueModels that adapt a bound bean property of an exchangeable bean. These ValueModels will be requested from an underlying BeanAdapter. To get such a model you specify the name of the bean property. All properties adapted must be read-write and must comply with the Java Bean coding conventions. In case you need to adapt a read-only or write-only property, or if the bean uses custom names for the reader and writer, use PresentationModel.getModel(String,String,String) . Also note that you must not mix calls to these methods for the same property name. For details see the JavaDoc class comment in com.jgoodies.binding.beans.BeanAdapter .

Changing the Adapted Bean
The adapted bean is not stored in this PresentationModel. Instead it is held by a ValueModel, the bean channel - just as in the PropertyAdapter and BeanAdapter. This indirection enables you to manage the adapted bean outside of this PresentationModel, and it enables you to share bean channels between multiple PresentationModels, PropertyAdapters, and BeanAdapters. The bean channel is used by all adapting models created by the factory methods #getModel. You can get and set the current bean by means of #getBean and #setBean. Or you can set a new value to the bean channel.

PresentationModel fires three PropertyChangeEvents if the bean changes: beforeBean, bean and afterBean. This is useful when sharing a bean channel and you must perform an operation before or after other listeners handle a bean change. Since you cannot rely on the order listeners will be notified, only the beforeBean and afterBean events are guaranteed to be fired before and after the bean change is fired. Note that #getBean() returns the new bean before any of these three PropertyChangeEvents is fired. Therefore listeners that handle these events must use the event's old and new value to determine the old and new bean. The order of events fired during a bean change is:

1. the bean channel fires a value change,
2. this model fires a beforeBean change,
3. this model fires the bean change,
4. this model fires an afterBean change.

The trigger channel is provided as a bound Java bean property triggerChannel that must be a non-null ValueModel with values of type Boolean. Attempts to read or write other value types may be rejected with runtime exceptions. By default the trigger channel is initialized as an instance of Trigger. As an alternative it can be set in the constructor.

Observing the Buffering State
This class also provides support for observing the buffering state of the BufferedValueModels created with this model. The buffering state is useful for UI actions and operations that are enabled or disabled if there are pending changes, for example on OK or APPLY button. API users can request the buffering state via #isBuffering and can observe the bound property buffering.

Tracking Changes in the Adapted Bean
PresentationModel provides support for observing bean property changes and it tracks all changes to report the overall changed state. The latter is useful to detect whether the bean has changed at all, for example to mark the bean as dirty, so it will be updated in a database. API users can request the changed state via #isChanged and can observe the bound property changed. If you want to track changes of other ValueModels, bean properties, or of submodels, register them using #observeChanged. To reset the changed state invoke #resetChanged. In case you track the changed state of submodels you should override #resetChanged to reset the changed state in these submodels.

The changed state changes once only (from false to true). If you need instant notifications about changes in the properties of the target bean, you can register PropertyChangeListeners with this model. This is useful if you change the bean and don't want to move your listeners from one bean to the other. And it's useful if you want to observe multiple bean properties at the same time. These listeners are managed by the method set #addBeanPropertyChangeListener and #removeBeanPropertyChangeListener. Listeners registered via these methods will be removed from the old bean before the bean changes and will be re-added after the new bean has been set. Therefore these listeners will be notified about changes only if the current bean changes a property. They won't be notified if the bean changes - and in turn the property value. If you want to observes property changes caused by bean changes too, register with the adapting ValueModel as returned by #getModel(String).

Instance Creation
PresentationModel can be instantiated using four different constructors: you can specify the target bean directly, or you can provide a bean channel to access the bean indirectly. In the latter case you specify a ValueModel that holds the bean that in turn holds the adapted property. In both cases the target bean is accessed indirectly through the bean channel. In both cases you can specify a custom trigger channel, or you can use a default trigger channel.

Note: This PresentationModel provides bound bean properties and you can register and unregister PropertyChangeListers as usual using #addPropertyChangeListener and #removePropertyChangeListener. Do not mix up the model listeners with the listeners registered with the bean.

Warning: PresentationModels register a PropertyChangeListener with the target bean. Hence, a bean has a reference to all PresentationModels that hold it as target bean. To avoid memory leaks it is recommended to remove this listener if the bean lives much longer than the PresentationModel, enabling the garbage collector to remove the PresentationModel. Setting a PresentationModel's target bean to null removes this listener, which in turn clears the reference from the bean to the PresentationModel. To do so, you can call setBean(null) or set the bean channel's value to null. As an alternative you can use event listener lists in your beans that implement references with WeakReference. Setting the bean to null has side effects, which is fine in most cases. However, you can release all listeners by calling #release.

TODO: Further improve the class comment.

TODO: Consider adding a feature to ensure that update notifications are performed in the event dispatch thread. In case the adapted bean is changed in a thread other than the event dispatch thread, such a feature would help complying with Swing's single thread rule. The feature could be implemented by an extended PropertyChangeSupport.

TODO: I plan to improve the support for adapting beans that do not fire PropertyChangeEvents. This affects the classes PropertyAdapter, BeanAdapter, and PresentationModel. Basically the PropertyAdapter and the BeanAdapter's internal SimplePropertyAdapter's shall be able to optionally self-fire a PropertyChangeEvent in case the bean does not. There are several downsides with self-firing events compared to bound bean properties. See Issue 49 for more information about the downsides.

The observeChanges constructor parameter shall be replaced by a more fine-grained choice to not observe (former observeChanges=false), to observe bound properties (former observeChanges=true), and a new setting for self-firing PropertyChangeEvents if a value is set. The latter case may be further split up to specify how the self-fired PropertyChangeEvent is created:

1. oldValue=null, newValue=null
2. oldValue=null, newValue=the value set
3. oldValue=value read before the set, newValue=the value set
4. oldValue=value read before the set, newValue=value read after the set

Installs a default bean channel that checks the identity not equity to ensure that listeners are unregistered properly if the old and new bean are equal but not the same.

Installs a Trigger as initial trigger channel.

This operation is supported only for readable bean properties.

Note: Unlike #resetChanged this method is not intended to be overridden by subclasses.

PresentationModels have a PropertyChangeListener registered with the target bean.

Subclasses may override this method to reset the changed state of submodels.

Installs a default bean channel that checks the identity not equity to ensure that listeners are unregistered properly if the old and new bean are equal but not the same.

Installs a Trigger as initial trigger channel.
Parameters:
  bean - the bean that holds the properties to adapt
throws:
  PropertyUnboundException - if the bean does notprovide a pair of methods to register a PropertyChangeListener

Installs a default bean channel that checks the identity not equity to ensure that listeners are unregistered properly if the old and new bean are equal but not the same.

The trigger channel is shared by all buffered models that are created using #getBufferedModel. It can be replaced by any other Boolean ValueModel later. Note that PresentationModel observes trigger value changes, not value state. Therefore you must ensure that customer triggers report value changes when asked to commit or flush. See the Trigger implementation for an example.
Parameters:
  bean - the bean that holds the properties to adapt
Parameters:
  triggerChannel - the ValueModel that triggers commit and flush events

It is strongly recommended that the bean channel checks the identity not equity. This ensures that listeners are unregistered properly if the old and new bean are equal but not the same.

The trigger channel is initialized as a Trigger. It may be replaced by any other Boolean ValueModel later. Note that PresentationModel observes trigger value changes, not value state. Therefore you must ensure that customer triggers report value changes when asked to commit or flush. See the Trigger implementation for an example.
Parameters:
  beanChannel - the ValueModel that holds the bean
throws:
  PropertyUnboundException - if the bean does notprovide a pair of methods to register a PropertyChangeListener

It is strongly recommended that the bean channel checks the identity not equity. This ensures that listeners are unregistered properly if the old and new bean are equal but not the same.

The trigger channel is shared by all buffered models that are created using #buffer. It can be replaced by any other Boolean ValueModel later. Note that PresentationModel observes trigger value changes, not value state. Therefore you must ensure that customer triggers report value changes when asked to commit or flush. See the Trigger implementation for an example.
Parameters:
  beanChannel - the ValueModel that holds the bean
Parameters:
  triggerChannel - the ValueModel that triggers commit and flush events

The listener will be notified if and only if this BeanAdapter's current bean changes a property. It'll not be notified if the bean changes.

If listener is null, no exception is thrown and no action is performed.
Parameters:
  listener - the PropertyChangeListener to be added
See Also:   PresentationModel.removeBeanPropertyChangeListener(PropertyChangeListener)
See Also:   PresentationModel.removeBeanPropertyChangeListener(String,PropertyChangeListener)
See Also:   PresentationModel.addBeanPropertyChangeListener(String,PropertyChangeListener)
See Also:   PresentationModel.getBeanPropertyChangeListeners()

The listener will be notified if and only if this BeanAdapter's current bean changes the specified property. It'll not be notified if the bean changes. If you want to observe property changes and bean changes, you may observe the ValueModel that adapts this property - as returned by #getModel(String).

Note that if the bean 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
Parameters:
  listener - the PropertyChangeListener to be added
See Also:   PresentationModel.removeBeanPropertyChangeListener(String,PropertyChangeListener)
See Also:   PresentationModel.addBeanPropertyChangeListener(String,PropertyChangeListener)
See Also:   PresentationModel.getBeanPropertyChangeListeners(String)

The default behavior resets the change tracker's changed state and fires a PropertyChangeEvent for the property #PROPERTYNAME_AFTER_BEAN. Note: Subclasses that override this method must invoke super or perform the same behavior.

This method is invoked by the BeanChangeHandler listening to the afterBean non-readable property of the BeanAdapter.
Parameters:
  oldBean - the bean that was adapted before the change
Parameters:
  newBean - the bean that is already the new target bean
See Also:   PresentationModel.beforeBeanChange(Object,Object)
See Also:   PresentationModel.PROPERTYNAME_BEFORE_BEAN
See Also:   PresentationModel.PROPERTYNAME_BEAN
See Also:   PresentationModel.PROPERTYNAME_AFTER_BEAN
See Also:   BeanAdapter

The default behavior fires a PropertyChangeEvent for property #PROPERTYNAME_BEFORE_BEAN. Note: Subclasses that override this method must invoke super or perform the same behavior.

This method is invoked by the BeanChangeHandler listening to the beforeBean non-readable property of the BeanAdapter.
Parameters:
  oldBean - the bean before the change
Parameters:
  newBean - the bean that will be adapted after the change
See Also:   PresentationModel.afterBeanChange(Object,Object)
See Also:   PresentationModel.PROPERTYNAME_BEFORE_BEAN
See Also:   PresentationModel.PROPERTYNAME_BEAN
See Also:   PresentationModel.PROPERTYNAME_AFTER_BEAN
See Also:   BeanAdapter

Here's an example code for a custom implementation:

 boolean observe =
 (beanChannel == null)
 || (beanChannel.getValue() == null)
 || BeanUtils.supportsBoundProperties((beanChannel.getValue().getClass());
 return new BeanAdapter(beanChannel, observe);
 

A future implementation shall return a BeanAdapter-like interface, not a BeanAdapter.
Parameters:
  beanChannel - the ValueModel that holds the bean the created bean adapter
since:
   1.3

The created ComponentValueModel is stored in a Map. Hence subsequent calls to this method with the same property name return the same ComponentValueModel.

To prevent potential runtime errors this method eagerly looks up the associated PropertyDescriptor if the target bean is not null.

For each property name all calls to this method and to #getBufferedModel(String, String, String) must use the same getter and setter names. Attempts to violate this constraint will be rejected with an IllegalArgumentException. Especially once you've called this method you must not call #getBufferedModel(String, String, String) with a non-null getter or setter name. And vice versa, once you've called the latter method with a non-null getter or setter name, you must not call this method.
Parameters:
  propertyName - the name of the read-write property to adapt a ComponentValueModel that wraps a buffered adapterto the property with the given nameon this model's bean channel using this model's trigger channel
throws:
  NullPointerException - if the property name is null
throws:
  PropertyNotFoundException - if the property could not be found
throws:
  IllegalArgumentException - if #getBufferedModel(String, String, String) has beencalled before with the same property name and a non-null getteror setter name
See Also:   ComponentValueModel
See Also:   BufferedValueModel
See Also:   ValueModel
See Also:   Trigger
See Also:   BeanAdapter
See Also:   PresentationModel.getModel(String)
See Also:   PresentationModel.getBufferedModel(String)
See Also:   PresentationModel.getComponentModel(String)
See Also:   Bindings.addComponentPropertyHandler(JComponentValueModel)
since:
   1.1

The created BufferedValueModel is stored in a Map. Hence subsequent calls to this method with the same property name return the same BufferedValueModel.

To prevent potential runtime errors this method eagerly looks up the associated PropertyDescriptor if the target bean is not null.

For each property name all calls to this method and to #getBufferedModel(String, String, String) must use the same getter and setter names. Attempts to violate this constraint will be rejected with an IllegalArgumentException. Especially once you've called this method you must not call #getBufferedModel(String, String, String) with a non-null getter or setter name. And vice versa, once you've called the latter method with a non-null getter or setter name, you must not call this method.
Parameters:
  propertyName - the name of the read-write property to adapt a buffered adapter to the property with the given nameon this model's bean channel using this model's trigger channel
throws:
  NullPointerException - if the property name is null
throws:
  PropertyNotFoundException - if the property could not be found
throws:
  IllegalArgumentException - if #getBufferedModel(String, String, String) has beencalled before with the same property name and a non-null getteror setter name
See Also:   BufferedValueModel
See Also:   ValueModel
See Also:   Trigger
See Also:   BeanAdapter
See Also:   PresentationModel.getModel(String)
See Also:   PresentationModel.getBufferedModel(String,String,String)

The created BufferedValueModel is stored in a Map so it can be looked up if it is requested multiple times.

To prevent potential runtime errors this method eagerly looks up the associated PropertyDescriptor if the target bean is not null.

For each property name all calls to this method and to #getBufferedModel(String) must use the same getter and setter names. Attempts to violate this constraint will be rejected with an IllegalArgumentException. Especially once you've called this method with a non-null getter or setter name, you must not call #getBufferedModel(String). And vice versa, once you've called the latter method you must not call this method with a non-null getter or setter name.
Parameters:
  propertyName - the name of the property to adapt
Parameters:
  getterName - the name of the method that reads the value
Parameters:
  setterName - the name of the method that sets the value a buffered adapter to the property with the given nameon this model's bean channel using this model's trigger channel
throws:
  NullPointerException - if the property name is null
throws:
  PropertyNotFoundException - if the property could not be found
throws:
  IllegalArgumentException - if this method has been called beforewith the same property name and different getter or setter names
See Also:   BufferedValueModel
See Also:   ValueModel
See Also:   Trigger
See Also:   BeanAdapter
See Also:   PresentationModel.getModel(String)
See Also:   PresentationModel.getBufferedModel(String)

getBufferedModel(propertyName).getValue()

Subsequent calls to this method with the same property name return the same ComponentValueModel.

To prevent potential runtime errors it eagerly looks up the associated PropertyDescriptor if the target bean is not null.

For each property name all calls to this method and to #getModel(String, String, String) must use the same getter and setter names. Attempts to violate this constraint will be rejected with an IllegalArgumentException. Especially once you've called this method you must not call #getModel(String, String, String) with a non-null getter or setter name. And vice versa, once you've called the latter method with a non-null getter or setter name, you must not call this method.

This returned ComponentValueModel provides convenience type converter method from AbstractValueModel and allows to modify GUI state such as enabled, visible, and editable in this presentation model. This can significantly shrink the source code necessary to handle GUI state changes.
Parameters:
  propertyName - the name of the property to adapt a ValueModel that adapts the property with the specified name
throws:
  NullPointerException - if the property name is null
throws:
  PropertyNotFoundException - if the property could not be found
throws:
  IllegalArgumentException - if #getModel(String, String, String) has beencalled before with the same property name and a non-null getteror setter name
See Also:   ComponentValueModel
See Also:   AbstractValueModel
See Also:   BeanAdapter
See Also:   PresentationModel.getModel(String,String,String)
See Also:   PresentationModel.getBufferedModel(String)
See Also:   Bindings.addComponentPropertyHandler(JComponentValueModel)
since:
   1.1

Subsequent calls to this method with the same property name return the same ValueModel.

To prevent potential runtime errors it eagerly looks up the associated PropertyDescriptor if the target bean is not null.

For each property name all calls to this method and to #getModel(String, String, String) must use the same getter and setter names. Attempts to violate this constraint will be rejected with an IllegalArgumentException. Especially once you've called this method you must not call #getModel(String, String, String) with a non-null getter or setter name. And vice versa, once you've called the latter method with a non-null getter or setter name, you must not call this method.

This method uses a return type of AbstractValueModel, not a ValueModel. This makes the AbstractValueModel convenience type converters available, which can significantly shrink the source code necessary to read and write values from/to these models.
Parameters:
  propertyName - the name of the property to adapt a ValueModel that adapts the property with the specified name
throws:
  NullPointerException - if the property name is null
throws:
  PropertyNotFoundException - if the property could not be found
throws:
  IllegalArgumentException - if #getModel(String, String, String) has beencalled before with the same property name and a non-null getteror setter name
See Also:   AbstractValueModel
See Also:   BeanAdapter
See Also:   PresentationModel.getModel(String,String,String)
See Also:   PresentationModel.getBufferedModel(String)

Subsequent calls to this method with the same parameters will return the same ValueModel.

To prevent potential runtime errors this method eagerly looks up the associated PropertyDescriptor if the target bean is not null.

For each property name all calls to this method and to #getModel(String) must use the same getter and setter names. Attempts to violate this constraint will be rejected with an IllegalArgumentException. Especially once you've called this method with a non-null getter or setter name, you must not call #getModel(String). And vice versa, once you've called the latter method you must not call this method with a non-null getter or setter name.

This method uses a return type of AbstractValueModel, not a ValueModel. This makes the AbstractValueModel convenience type converters available, which can significantly shrink the source code necessary to read and write values from/to these models.
Parameters:
  propertyName - the name of the property to adapt
Parameters:
  getterName - the name of the method that reads the value
Parameters:
  setterName - the name of the method that sets the value a ValueModel that adapts the property with the specified name
throws:
  NullPointerException - if the property name is null
throws:
  PropertyNotFoundException - if the property could not be found
throws:
  IllegalArgumentException - if this method has been called beforewith the same property name and different getter or setter names
See Also:   AbstractValueModel
See Also:   BeanAdapter
See Also:   PresentationModel.getModel(String,String,String)
See Also:   PresentationModel.getBufferedModel(String)

This trigger channel is used to commit and flush values in the BufferedValueModels returned by #getBufferedModel. this model's trigger channel
See Also:   BufferedValueModel
See Also:   ValueModel
See Also:   PresentationModel.setTriggerChannel(ValueModel)

This operation is supported only for readable bean properties.
Parameters:
  propertyName - the name of the property to be read the value of the adapted bean property, null if the bean is null
throws:
  NullPointerException - if the property name is null
throws:
  UnsupportedOperationException - if the property is write-only
throws:
  PropertyNotFoundException - if the property could not be found
throws:
  PropertyAccessException - if the value could not be read
since:
   1.1

Note: Unlike #resetChanged this method is not intended to be overridden by subclasses. If you want to track changes of other ValueModels, bean properties, or of submodels, register them by means of #observeChanged. Overriding #isChanged to include the changed state of submodels would return the correct changed value, but it would bypass the change notification from submodels to this model. Therefore submodels must be observed, which can be achieve using #observeChanged.

To reset the changed state invoke #resetChanged. In case you track the changed state of submodels override #resetChanged to reset the changed state in these submodels too. true if an observed property has changed since the last reset
See Also:   PresentationModel.observeChanged(ValueModel)
See Also:   PresentationModel.observeChanged(Object,String)
See Also:   PresentationModel.resetChanged()

PresentationModels have a PropertyChangeListener registered with the target bean. Hence, a bean has a reference to all PresentationModels that hold it as bean. To avoid memory leaks it is recommended to remove this listener, if the bean lives much longer than the PresentationModel, enabling the garbage collector to remove the PresentationModel. To do so, you can call setBean(null) or set the bean channel's value to null. As an alternative you can use event listener lists in your beans that implement references with WeakReference.

Setting the bean to null has side-effects, for example the model fires a change event for the bound property bean and other properties. And the value of ValueModel's vent by this model may change. However, typically this is fine and setting the bean to null is the first choice for removing the reference from the bean to the PresentationModel. Another way to clear the reference from the target bean is to call this #release method. It has no side-effects, but the PresentationModel must not be used anymore once #release has been called.
See Also:   PresentationModel.setBean(Object)
See Also:   java.lang.ref.WeakReference
since:
   1.2

If listener is null, no exception is thrown and no action is performed.
Parameters:
  listener - the PropertyChangeListener to be removed
See Also:   PresentationModel.addBeanPropertyChangeListener(PropertyChangeListener)
See Also:   PresentationModel.addBeanPropertyChangeListener(String,PropertyChangeListener)
See Also:   PresentationModel.removeBeanPropertyChangeListener(String,PropertyChangeListener)
See Also:   PresentationModel.getBeanPropertyChangeListeners()

If listener is null, no exception is thrown and no action is performed.
Parameters:
  propertyName - a valid property name
Parameters:
  listener - the PropertyChangeListener to be removed
See Also:   PresentationModel.addBeanPropertyChangeListener(String,PropertyChangeListener)
See Also:   PresentationModel.removeBeanPropertyChangeListener(PropertyChangeListener)
See Also:   PresentationModel.getBeanPropertyChangeListeners(String)

Subclasses may override this method to reset the changed state of submodels. The overriding method must invoke this super behavior. For example if you have a MainModel that is composed of two submodels Submodel1 and Submodel2, you may write:

 public void resetChanged() {
 super.resetChanged();
 getSubmodel1().resetChanged();
 getSubmodel2().resetChanged();
 }
 

getBufferedModel(propertyName).setValue(newValue)

Notifies the associated value change listeners if the bean reports a property change. Note that a bean may suppress PropertyChangeEvents if the old and new value are the same, or if the old and new value are equal.

This operation is supported only for writable bean properties.
Parameters:
  propertyName - the name of the property to set
Parameters:
  newValue - the value to set
throws:
  NullPointerException - if the property name is null
throws:
  UnsupportedOperationException - if the property is read-only
throws:
  PropertyNotFoundException - if the property could not be found
throws:
  PropertyAccessException - if the new value could not be set
since:
   1.1

Notifies the associated value change listeners if the bean reports a property change. Note that a bean may suppress PropertyChangeEvents if the old and new value are the same, or if the old and new value are equal.

This operation is supported only for writable bean properties.
Parameters:
  propertyName - the name of the property to set
Parameters:
  newValue - the value to set
throws:
  NullPointerException - if the property name is null
throws:
  UnsupportedOperationException - if the property is read-only
throws:
  PropertyNotFoundException - if the property could not be found
throws:
  PropertyAccessException - if the new value could not be set
throws:
  PropertyVetoException - if the bean setterthrows a PropertyVetoException
since:
   1.1