com.jgoodies.binding.value
Interface ValueModel

All Known Implementing Classes:
AbstractConverter, AbstractValueModel, AbstractVetoableValueModel, BeanAdapter.SimplePropertyAdapter, BufferedValueModel, ComponentValueModel, ConverterFactory.BooleanNegator, ConverterFactory.BooleanToStringConverter, ConverterFactory.DoubleConverter, ConverterFactory.DoubleToIntegerConverter, ConverterFactory.FloatConverter, ConverterFactory.FloatToIntegerConverter, ConverterFactory.IntegerConverter, ConverterFactory.LongConverter, ConverterFactory.LongToIntegerConverter, ConverterFactory.StringConverter, DelayedReadValueModel, DelayedWriteValueModel, NonNullValueModel, PreferencesAdapter, PropertyAdapter, SelectionInList, Trigger, ValueHolder

public interface ValueModel

Describes models with a generic access to a single value that allow to observe value changes. The value can be accessed using the #getValue()/#setValue(Object) methods. Observers can register instances of PropertyChangeListener to be notified if the value changes.

If the value is read-only or write-only, an implementor may choose to reject an operation using an UnsupportedOperationException or may do nothing or perform an appropriate action, or may return an appropriate value.

The listeners registered with this ValueModel using #addValueChangeListener will be invoked only with PropertyChangeEvents that have the name set to "value". In other words, the listeners won't get notified when a PropertyChangeEvent is fired that has a null object as the name to indicate an arbitrary set of the event source's properties have changed. This is the case if you use the PropertyChangeSupport, either directly or indirectly, to fire property changes with the property name "value" specified. This constraint ensures that all ValueModel implementors behave like the AbstractValueModel subclasses. In the rare case, where you want to notify a PropertyChangeListener even with PropertyChangeEvents that have no property name set, you can register the listener with #addPropertyChangeListener, not #addValueChangeListener.

AbstractValueModel minimizes the effort required to implement this interface. It uses the PropertyChangeSupport to fire PropertyChangeEvents, and it adds PropertyChangeListeners for the specific property name "value". This ensures that the constraint mentioned above is met.

Implementors are encouraged to provide non-null values for the PropertyChangeEvent's old and new values. However, both may be null.

Version:
$Revision: 1.6 $
Author:
Karsten Lentzsch
See Also:
AbstractValueModel, ValueHolder, PropertyAdapter

Method Summary
 void addValueChangeListener(java.beans.PropertyChangeListener listener)
          Registers the given PropertyChangeListener with this ValueModel.
 java.lang.Object getValue()
          Returns this model's value.
 void removeValueChangeListener(java.beans.PropertyChangeListener listener)
          Deregisters the given PropertyChangeListener from this ValueModel.
 void setValue(java.lang.Object newValue)
          Sets a new value and notifies any registered value listeners if the value has changed.
 

Method Detail

getValue

java.lang.Object getValue()
Returns this model's value. In case of a write-only value, implementors may choose to either reject this operation or or return null or any other appropriate value.

Returns:
this model's value

setValue

void setValue(java.lang.Object newValue)
Sets a new value and notifies any registered value listeners if the value has changed. In case of a read-only value implementors may choose to either reject this operation or to do nothing.

Parameters:
newValue - the value to be set

addValueChangeListener

void addValueChangeListener(java.beans.PropertyChangeListener listener)
Registers the given PropertyChangeListener with this ValueModel. The listener will be notified if the value has changed. The PropertyChangeEvents delivered to the listener must have the name set to "value". The latter ensures that all ValueModel implementors behave like the AbstractValueModel subclasses.

To comply with the above specification implementors can use the PropertyChangeSupport's #addPropertyChangeListener method that accepts a property name, so that listeners will be invoked only if that specific property has changed.

Parameters:
listener - the listener to be added
See Also:
AbstractValueModel.addValueChangeListener(PropertyChangeListener)

removeValueChangeListener

void removeValueChangeListener(java.beans.PropertyChangeListener listener)
Deregisters the given PropertyChangeListener from this ValueModel.

Parameters:
listener - the listener to be removed


Copyright © 2002-2008 JGoodies Karsten Lentzsch. All Rights Reserved.