|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object com.jgoodies.binding.beans.Model cz.vity.freerapid.gui.MyPresentationModel<B>
B
- the type of the bean managed by this PresentationModelpublic class MyPresentationModel<B>
The standard base class to implement the Presentation Model pattern, that represents the state and behavior of a presentation independently of the GUI components used in the interface. This pattern is described in Martin Fowler's upcoming addition to his "Patterns of Enterprise Application Architecture". More details around this implementation of the Presentation Model pattern and a 3-tier Swing client architecture with a presentation model layer can be found in the JGoodies Binding presentation. This architecture is supported by the JGoodies Binding library. The PresentationModel pattern is known to users of VisualWorks Smalltalk as ApplicationModel.
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:
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
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 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 BeanAdapter
.Changing the Adapted Bean
#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:getBufferedModel(String)
that vend BufferedValueModels that wrap an adapted bean property. The buffer can be committed or flushed using
#triggerCommit
and #triggerFlush
respectively.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
#isBuffering
and can observe the bound property buffering.Tracking Changes in the Adapted Bean
#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
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:
BeanAdapter
,
ValueModel
,
PropertyAdapter
,
Trigger
,
Serialized FormField Summary | |
---|---|
static String |
PROPERTYNAME_AFTER_BEAN
The property name used in the PropertyChangeEvent that is fired after the bean property fires its PropertyChangeEvent. |
static String |
PROPERTYNAME_BEAN
The name of the read-write bound property that holds the target bean. |
static String |
PROPERTYNAME_BEFORE_BEAN
The property name used in the PropertyChangeEvent that is fired before the bean property fires its PropertyChangeEvent. |
static String |
PROPERTYNAME_BUFFERING
The name of the read-only bound bean property that indicates whether one of the buffered models is buffering. |
static String |
PROPERTYNAME_CHANGED
The name of the read-only bound bean property that indicates whether one of the observed models has changed. |
static String |
PROPERTYNAME_TRIGGERCHANNEL
The name of the read-write bound bean property for the trigger channel that is shared by all PropertyAdapters that are created via #getBufferedModel . |
Constructor Summary | |
---|---|
MyPresentationModel(Object bean)
Constructs a PresentationModel that adapts properties of the given bean. |
|
MyPresentationModel(Object bean,
com.jgoodies.binding.value.ValueModel triggerChannel)
Constructs a PresentationModel on the given bean using the given trigger channel. |
|
MyPresentationModel(com.jgoodies.binding.value.ValueModel beanChannel)
Constructs a PresentationModel on the given bean channel. |
|
MyPresentationModel(com.jgoodies.binding.value.ValueModel beanChannel,
com.jgoodies.binding.value.ValueModel triggerChannel)
Constructs a PresentationModel on the given bean channel using the given trigger channel. |
Method Summary | |
---|---|
void |
addBeanPropertyChangeListener(PropertyChangeListener listener)
Adds a PropertyChangeListener to the list of bean listeners. |
void |
addBeanPropertyChangeListener(String propertyName,
PropertyChangeListener listener)
Adds a PropertyChangeListener to the list of bean listeners for a specific property. |
void |
afterBeanChange(B oldBean,
B newBean)
The underlying BeanAdapter has changed the target bean. |
void |
beforeBeanChange(B oldBean,
B newBean)
The underlying BeanAdapter is about to change the bean. |
protected com.jgoodies.binding.beans.BeanAdapter<B> |
createBeanAdapter(com.jgoodies.binding.value.ValueModel beanChannel)
Creates and returns a BeanAdapter for the given bean channel. |
B |
getBean()
Returns the bean that holds the adapted properties. |
com.jgoodies.binding.value.ValueModel |
getBeanChannel()
Returns the ValueModel that holds the bean that in turn holds the adapted properties. |
PropertyChangeListener[] |
getBeanPropertyChangeListeners()
Returns an array of all the property change listeners registered on this component. |
PropertyChangeListener[] |
getBeanPropertyChangeListeners(String propertyName)
Returns an array of all the listeners which have been associated with the named property. |
com.jgoodies.binding.value.ComponentValueModel |
getBufferedComponentModel(String propertyName)
Looks up or creates a buffered component adapter to the read-write property with the given name on this PresentationModel's bean channel. |
com.jgoodies.binding.value.BufferedValueModel |
getBufferedModel(MyPreferencesAdapter model)
|
com.jgoodies.binding.value.BufferedValueModel |
getBufferedModel(String propertyName)
Looks up or creates a buffered adapter to the read-write property with the given name on this PresentationModel's bean channel. |
com.jgoodies.binding.value.BufferedValueModel |
getBufferedModel(String propertyName,
String getterName,
String setterName)
Looks up or creates a buffered adapter to the read-write property with the given name on this PresentationModel's bean channel using the specified getter and setter name to read and write values. |
com.jgoodies.binding.value.ValueModel |
getBufferedPreferences(String key,
Object defaultValue)
|
Object |
getBufferedValue(String propertyName)
Returns the value of specified buffered bean property. |
com.jgoodies.binding.value.ComponentValueModel |
getComponentModel(String propertyName)
Looks up and lazily creates a ComponentValueModel that adapts the bound property with the specified name. |
com.jgoodies.binding.value.AbstractValueModel |
getModel(String propertyName)
Looks up and lazily creates a ValueModel that adapts the bound property with the specified name. |
com.jgoodies.binding.value.AbstractValueModel |
getModel(String propertyName,
String getterName,
String setterName)
Looks up and lazily creates a ValueModel that adapts the bound property with the given name. |
com.jgoodies.binding.value.ValueModel |
getTriggerChannel()
Returns a ValueModel that can be shared and used to trigger commit and flush events in BufferedValueModels. |
Object |
getValue(String propertyName)
Returns the value of specified bean property, null if the current bean is null . |
boolean |
isBuffering()
Answers whether any of the buffered models is buffering. |
boolean |
isChanged()
Answers whether one of the registered ValueModels has changed since the changed state has been reset last time. |
void |
observeChanged(Object bean,
String propertyName)
Observes the specified readable bound bean property in the given bean. |
void |
observeChanged(com.jgoodies.binding.value.ValueModel valueModel)
Observes value changes in the given ValueModel. |
void |
release()
Removes the PropertyChangeHandler from the observed bean, if the bean is not null . |
void |
removeBeanPropertyChangeListener(PropertyChangeListener listener)
Removes a PropertyChangeListener from the list of bean listeners. |
void |
removeBeanPropertyChangeListener(String propertyName,
PropertyChangeListener listener)
Removes a PropertyChangeListener from the listener list for a specific property. |
void |
resetChanged()
Resets this model's changed state to false . |
void |
retractInterestFor(Object bean,
String propertyName)
Retracts interest for the specified readable bound bean property in the given bean. |
void |
retractInterestFor(com.jgoodies.binding.value.ValueModel valueModel)
Retracts interest for value changes in the given ValueModel. |
void |
setBean(B newBean)
Sets a new bean as content of the bean channel. |
void |
setBufferedValue(String propertyName,
Object newValue)
Buffers the given value for the specified bean property. |
void |
setBuffering(boolean newValue)
Sets the buffering state to the specified value. |
void |
setChanged(boolean newValue)
|
void |
setTriggerChannel(com.jgoodies.binding.value.ValueModel newTriggerChannel)
Sets the given ValueModel as this model's new trigger channel. |
void |
setValue(String propertyName,
Object newValue)
Sets the given new value for the specified bean property. |
void |
setVetoableValue(String propertyName,
Object newValue)
Sets a new value for the specified bean property. |
void |
triggerCommit()
Sets the trigger channel to true which in turn triggers commit events in all BufferedValueModels that share this trigger. |
void |
triggerFlush()
Sets the trigger channel to false which in turn triggers flush events in all BufferedValueModels that share this trigger. |
Methods inherited from class com.jgoodies.binding.beans.Model |
---|
addPropertyChangeListener, addPropertyChangeListener, addVetoableChangeListener, addVetoableChangeListener, equals, fireIndexedPropertyChange, fireIndexedPropertyChange, fireIndexedPropertyChange, fireMultiplePropertiesChanged, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, fireVetoableChange, fireVetoableChange, fireVetoableChange, fireVetoableChange, fireVetoableChange, fireVetoableChange, getPropertyChangeListeners, getPropertyChangeListeners, getVetoableChangeListeners, getVetoableChangeListeners, removePropertyChangeListener, removePropertyChangeListener, removeVetoableChangeListener, removeVetoableChangeListener |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
public static final String PROPERTYNAME_BEFORE_BEAN
public static final String PROPERTYNAME_BEAN
getBean()
,
setBean(Object)
,
Constant Field Valuespublic static final String PROPERTYNAME_AFTER_BEAN
public static final String PROPERTYNAME_TRIGGERCHANNEL
#getBufferedModel
.
getTriggerChannel()
,
setTriggerChannel(com.jgoodies.binding.value.ValueModel)
,
getBufferedModel(String)
,
Constant Field Valuespublic static final String PROPERTYNAME_BUFFERING
isBuffering()
,
getBufferedModel(String)
,
Constant Field Valuespublic static final String PROPERTYNAME_CHANGED
isChanged()
,
resetChanged()
,
observeChanged(com.jgoodies.binding.value.ValueModel)
,
observeChanged(Object,String)
,
Constant Field ValuesConstructor Detail |
---|
public MyPresentationModel(Object bean)
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.
bean
- the bean that holds the properties to adapt
com.jgoodies.binding.beans.PropertyUnboundException
- if the bean
does not provide a pair of methods to register a PropertyChangeListenerpublic MyPresentationModel(Object bean, com.jgoodies.binding.value.ValueModel triggerChannel)
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.
bean
- the bean that holds the properties to adapttriggerChannel
- the ValueModel that triggers commit and flush eventspublic MyPresentationModel(com.jgoodies.binding.value.ValueModel beanChannel)
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.
beanChannel
- the ValueModel that holds the bean
com.jgoodies.binding.beans.PropertyUnboundException
- if the bean
does not provide a pair of methods to register a PropertyChangeListenerpublic MyPresentationModel(com.jgoodies.binding.value.ValueModel beanChannel, com.jgoodies.binding.value.ValueModel triggerChannel)
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.
beanChannel
- the ValueModel that holds the beantriggerChannel
- the ValueModel that triggers commit and flush eventsMethod Detail |
---|
protected com.jgoodies.binding.beans.BeanAdapter<B> createBeanAdapter(com.jgoodies.binding.value.ValueModel beanChannel)
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.
beanChannel
- the ValueModel that holds the bean
public com.jgoodies.binding.value.ValueModel getBeanChannel()
#getModel
and
#getBufferedModel
.
getBean()
,
setBean(Object)
public B getBean()
setBean(Object)
,
getBeanChannel()
public void setBean(B newBean)
newBean
- the new beangetBean()
,
getBeanChannel()
public void beforeBeanChange(B oldBean, B newBean)
null
etc.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.
oldBean
- the bean before the changenewBean
- the bean that will be adapted after the changeafterBeanChange(Object,Object)
,
PROPERTYNAME_BEFORE_BEAN
,
PROPERTYNAME_BEAN
,
PROPERTYNAME_AFTER_BEAN
,
BeanAdapter
public void afterBeanChange(B oldBean, B newBean)
#beforeBeanChange
. Or you can reset values,
reset custom changed state, set fields to null
etc.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.
oldBean
- the bean that was adapted before the changenewBean
- the bean that is already the new target beanbeforeBeanChange(Object,Object)
,
PROPERTYNAME_BEFORE_BEAN
,
PROPERTYNAME_BEAN
,
PROPERTYNAME_AFTER_BEAN
,
BeanAdapter
public Object getValue(String propertyName)
null
if the current bean is null
.This operation is supported only for readable bean properties.
propertyName
- the name of the property to be read
NullPointerException
- if the property name is null
UnsupportedOperationException
- if the property is write-only
com.jgoodies.binding.beans.PropertyNotFoundException
- if the property could not be found
com.jgoodies.binding.beans.PropertyAccessException
- if the value could not be readpublic void setValue(String propertyName, Object newValue)
null
. If the setter associated with the propertyName throws a PropertyVetoException, it is silently
ignored.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.
propertyName
- the name of the property to setnewValue
- the value to set
NullPointerException
- if the property name is null
UnsupportedOperationException
- if the property is read-only
com.jgoodies.binding.beans.PropertyNotFoundException
- if the property could not be found
com.jgoodies.binding.beans.PropertyAccessException
- if the new value could not be setpublic void setVetoableValue(String propertyName, Object newValue) throws PropertyVetoException
null
. If the setter
associated with the propertyName throws a PropertyVetoException, this methods throws the same exception.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.
propertyName
- the name of the property to setnewValue
- the value to set
NullPointerException
- if the property name is null
UnsupportedOperationException
- if the property is read-only
com.jgoodies.binding.beans.PropertyNotFoundException
- if the property could not be found
com.jgoodies.binding.beans.PropertyAccessException
- if the new value could not be set
PropertyVetoException
- if the bean setter throws a PropertyVetoExceptionpublic Object getBufferedValue(String propertyName)
getBufferedModel(propertyName).getValue()As a side-effect, this method may create a buffered model.
propertyName
- the name of the property to be read
NullPointerException
- if the property name is null
UnsupportedOperationException
- if the property is write-only
com.jgoodies.binding.beans.PropertyNotFoundException
- if the property could not be found
com.jgoodies.binding.beans.PropertyAccessException
- if the value could not be readpublic void setBufferedValue(String propertyName, Object newValue)
getBufferedModel(propertyName).setValue(newValue)As a side-effect, this method may create a buffered model.
propertyName
- the name of the property to setnewValue
- the value to set
NullPointerException
- if the property name is null
com.jgoodies.binding.beans.PropertyNotFoundException
- if the property could not be found
com.jgoodies.binding.beans.PropertyAccessException
- if the new value could not be setpublic com.jgoodies.binding.value.AbstractValueModel getModel(String propertyName)
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.
propertyName
- the name of the property to adapt
NullPointerException
- if the property name is null
com.jgoodies.binding.beans.PropertyNotFoundException
- if the property could not be found
IllegalArgumentException
- if #getModel(String, String, String)
has been called before with
the same property name and a non-null getter or setter nameAbstractValueModel
,
BeanAdapter
,
getModel(String,String,String)
,
getBufferedModel(String)
public com.jgoodies.binding.value.AbstractValueModel getModel(String propertyName, String getterName, String setterName)
#getModel(String)
this method bypasses the Bean Introspection and uses the given getter and setter
names to setup the access to the adapted Bean property.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.
propertyName
- the name of the property to adaptgetterName
- the name of the method that reads the valuesetterName
- the name of the method that sets the value
NullPointerException
- if the property name is null
com.jgoodies.binding.beans.PropertyNotFoundException
- if the property could not be found
IllegalArgumentException
- if this method has been called before with the same property name and different
getter or setter namesAbstractValueModel
,
BeanAdapter
,
getModel(String,String,String)
,
getBufferedModel(String)
public com.jgoodies.binding.value.ComponentValueModel getComponentModel(String propertyName)
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.
propertyName
- the name of the property to adapt
NullPointerException
- if the property name is null
com.jgoodies.binding.beans.PropertyNotFoundException
- if the property could not be found
IllegalArgumentException
- if #getModel(String, String, String)
has been called before with
the same property name and a non-null getter or setter nameComponentValueModel
,
AbstractValueModel
,
BeanAdapter
,
getModel(String,String,String)
,
getBufferedModel(String)
,
Bindings.addComponentPropertyHandler(javax.swing.JComponent,
com.jgoodies.binding.value.ValueModel)
public com.jgoodies.binding.value.BufferedValueModel getBufferedModel(String propertyName)
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.
propertyName
- the name of the read-write property to adapt
NullPointerException
- if the property name is null
com.jgoodies.binding.beans.PropertyNotFoundException
- if the property could not be found
IllegalArgumentException
- if #getBufferedModel(String, String, String)
has been called before
with the same property name and a non-null getter or setter nameBufferedValueModel
,
ValueModel
,
Trigger
,
BeanAdapter
,
getModel(String)
,
getBufferedModel(String,String,String)
public com.jgoodies.binding.value.BufferedValueModel getBufferedModel(String propertyName, String getterName, String setterName)
BufferedValueModel
that wraps a ValueModel
that adapts the bean property with the
specified name. The buffered model uses this PresentationModel's trigger channel to listen for commit and flush
events.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.
propertyName
- the name of the property to adaptgetterName
- the name of the method that reads the valuesetterName
- the name of the method that sets the value
NullPointerException
- if the property name is null
com.jgoodies.binding.beans.PropertyNotFoundException
- if the property could not be found
IllegalArgumentException
- if this method has been called before with the same property name and different
getter or setter namesBufferedValueModel
,
ValueModel
,
Trigger
,
BeanAdapter
,
getModel(String)
,
getBufferedModel(String)
public com.jgoodies.binding.value.BufferedValueModel getBufferedModel(MyPreferencesAdapter model)
public com.jgoodies.binding.value.ComponentValueModel getBufferedComponentModel(String propertyName)
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.
propertyName
- the name of the read-write property to adapt
NullPointerException
- if the property name is null
com.jgoodies.binding.beans.PropertyNotFoundException
- if the property could not be found
IllegalArgumentException
- if #getBufferedModel(String, String, String)
has been called before
with the same property name and a non-null getter or setter nameComponentValueModel
,
BufferedValueModel
,
ValueModel
,
Trigger
,
BeanAdapter
,
getModel(String)
,
getBufferedModel(String)
,
getComponentModel(String)
,
Bindings.addComponentPropertyHandler(javax.swing.JComponent,
com.jgoodies.binding.value.ValueModel)
public com.jgoodies.binding.value.ValueModel getTriggerChannel()
#triggerCommit
and it changes to false in
#triggerFlush
.This trigger channel is used to commit and flush values in the BufferedValueModels returned by
#getBufferedModel
.
BufferedValueModel
,
ValueModel
,
setTriggerChannel(com.jgoodies.binding.value.ValueModel)
public void setTriggerChannel(com.jgoodies.binding.value.ValueModel newTriggerChannel)
#getBufferedModel
. Subsequent invocations of
#triggerCommit
and #triggerFlush
will trigger commit and flush events using the new
trigger channel.
newTriggerChannel
- the ValueModel to be set as this model's new trigger channel
NullPointerException
- if the new trigger channel is null
BufferedValueModel
,
ValueModel
,
getTriggerChannel()
public void triggerCommit()
triggerFlush()
public void triggerFlush()
triggerCommit()
public boolean isBuffering()
public void setBuffering(boolean newValue)
newValue
- the new buffering statepublic boolean isChanged()
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.
observeChanged(com.jgoodies.binding.value.ValueModel)
,
observeChanged(Object,String)
,
resetChanged()
public void resetChanged()
false
. Therefore it resets the changed states of the change
tracker and the underlying bean adapter.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(); }
isChanged()
,
observeChanged(com.jgoodies.binding.value.ValueModel)
,
observeChanged(Object,String)
public void setChanged(boolean newValue)
public void observeChanged(Object bean, String propertyName)
bean
- the bean to be observedpropertyName
- the name of the readable bound bean property
NullPointerException
- if the bean or propertyName is null
com.jgoodies.binding.beans.PropertyNotBindableException
- if this class can't add the PropertyChangeListener from the beanretractInterestFor(Object,String)
,
observeChanged(com.jgoodies.binding.value.ValueModel)
public void observeChanged(com.jgoodies.binding.value.ValueModel valueModel)
valueModel
- the ValueModel to observe
NullPointerException
- if the valueModel is nullretractInterestFor(com.jgoodies.binding.value.ValueModel)
,
observeChanged(Object,String)
public void retractInterestFor(Object bean, String propertyName)
bean
- the bean to be observedpropertyName
- the name of the readable bound bean property
NullPointerException
- if the bean or propertyName is null
com.jgoodies.binding.beans.PropertyNotBindableException
- if this class can't remove the PropertyChangeListener from the beanobserveChanged(Object,String)
,
retractInterestFor(com.jgoodies.binding.value.ValueModel)
public void retractInterestFor(com.jgoodies.binding.value.ValueModel valueModel)
valueModel
- the ValueModel to observe
NullPointerException
- if the valueModel is nullobserveChanged(com.jgoodies.binding.value.ValueModel)
,
retractInterestFor(Object,String)
public void addBeanPropertyChangeListener(PropertyChangeListener listener)
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.
listener
- the PropertyChangeListener to be addedremoveBeanPropertyChangeListener(java.beans.PropertyChangeListener)
,
removeBeanPropertyChangeListener(String,java.beans.PropertyChangeListener)
,
addBeanPropertyChangeListener(String,java.beans.PropertyChangeListener)
,
getBeanPropertyChangeListeners()
public void removeBeanPropertyChangeListener(PropertyChangeListener listener)
If listener is
null
, no exception is thrown and no action is performed.
listener
- the PropertyChangeListener to be removedaddBeanPropertyChangeListener(java.beans.PropertyChangeListener)
,
addBeanPropertyChangeListener(String,java.beans.PropertyChangeListener)
,
removeBeanPropertyChangeListener(String,java.beans.PropertyChangeListener)
,
getBeanPropertyChangeListeners()
public void addBeanPropertyChangeListener(String propertyName, PropertyChangeListener listener)
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.
propertyName
- one of the property names listed abovelistener
- the PropertyChangeListener to be addedremoveBeanPropertyChangeListener(String,java.beans.PropertyChangeListener)
,
addBeanPropertyChangeListener(String,java.beans.PropertyChangeListener)
,
getBeanPropertyChangeListeners(String)
public void removeBeanPropertyChangeListener(String propertyName, PropertyChangeListener listener)
If listener is
null
, no exception is thrown and no action is performed.
propertyName
- a valid property namelistener
- the PropertyChangeListener to be removedaddBeanPropertyChangeListener(String,java.beans.PropertyChangeListener)
,
removeBeanPropertyChangeListener(java.beans.PropertyChangeListener)
,
getBeanPropertyChangeListeners(String)
public PropertyChangeListener[] getBeanPropertyChangeListeners()
PropertyChangeListener
s or an empty array if no property change
listeners are currently registeredaddBeanPropertyChangeListener(java.beans.PropertyChangeListener)
,
removeBeanPropertyChangeListener(java.beans.PropertyChangeListener)
,
getBeanPropertyChangeListeners(String)
,
PropertyChangeSupport.getPropertyChangeListeners()
public PropertyChangeListener[] getBeanPropertyChangeListeners(String propertyName)
propertyName
- the name of the property to lookup listeners
PropertyChangeListeners
associated with the named property or an empty array if
no listeners have been addedaddBeanPropertyChangeListener(String,java.beans.PropertyChangeListener)
,
removeBeanPropertyChangeListener(String,java.beans.PropertyChangeListener)
,
getBeanPropertyChangeListeners()
public void release()
null
. Also removes all
listeners from the bean that have been registered with #addBeanPropertyChangeListener
before.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.
setBean(Object)
,
WeakReference
public com.jgoodies.binding.value.ValueModel getBufferedPreferences(String key, Object defaultValue)
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |