org.springframework.binding.form.support
Class AbstractFormModel

Show UML class diagram

java.lang.Object
  org.springframework.binding.value.support.AbstractPropertyChangePublisher
      org.springframework.binding.form.support.AbstractFormModel

All Implemented Interfaces:

ConfigurableFormModel, FormModel, HierarchicalFormModel, PropertyChangePublisher, Authorizable

Direct Known Subclasses:

DefaultFormModel

public abstract class AbstractFormModel
extends AbstractPropertyChangePublisher
implements HierarchicalFormModel, ConfigurableFormModel

Base implementation of HierarchicalFormModel and ConfigurableFormModel subclasses need only implement the 4 value model interception methods.

Author:

Keith Donald, Oliver Hutchison

Nested Class Summary

protected class	AbstractFormModel.ChildStateChangeHandler Listener to be registered on properties of child form models and other valueModels.
protected static class	AbstractFormModel.ConvertingValueModelKey Class for keys in the convertingValueModels map.
protected class	AbstractFormModel.ParentStateChangeHandler Listener to be registered on properties of the parent form model.

Field Summary

protected PropertyChangeListener	childStateChangeHandler
protected PropertyChangeListener	parentStateChangeHandler

Fields inherited from class org.springframework.binding.value.support.AbstractPropertyChangePublisher

logger

Fields inherited from interface org.springframework.binding.form.FormModel

COMMITTABLE_PROPERTY, DIRTY_PROPERTY, ENABLED_PROPERTY, READONLY_PROPERTY

Fields inherited from interface org.springframework.richclient.core.Authorizable

AUTHORIZED_PROPERTY

Constructor Summary

protected	AbstractFormModel()
protected	AbstractFormModel(MutablePropertyAccessStrategy propertyAccessStrategy, boolean buffered)
protected	AbstractFormModel(Object domainObject)
	AbstractFormModel(Object domainObject, boolean buffered)
protected	AbstractFormModel(ValueModel domainObjectHolder, boolean buffered)

Method Summary

ValueModel	add(String propertyName) Add a valueModel for the given property.
ValueModel	add(String formProperty, ValueModel valueModel) Add the given valueModel as wrapper for the given property.
ValueModel	add(String propertyName, ValueModel valueModel, FieldMetadata metadata) Add the given valueModel as wrapper for the given property.
void	addChild(HierarchicalFormModel child) Add child to this FormModel.
void	addCommitListener(CommitListener listener) Adds the specified listener to the list if listeners notified when a commit happens.
ValueModel	addMethod(String propertyMethodName, String derivedFromProperty) Add a valueModel that holds a derived value computed by invoking the given method with the given property as argument on the formModel.
ValueModel	addMethod(String propertyMethodName, String[] derivedFromProperties) Add a valueModel that holds a derived value computed by invoking the given method with a number of other properties as arguments on the formModel.
protected void	childStateChanged(PropertyChangeEvent evt) Events from the child form model or value models that have side-effects on this form model should be handled here.
void	commit() Commits any changes buffered by the form property value models into the current form backing object.
protected void	committableUpdated() Fires the necessary property change event for changes to the committable property.
protected ValueModel	createConvertingValueModel(String formProperty, Class targetClass)
protected ValueModel	createValueModel(String formProperty) Creates a new value mode for the the given property.
protected void	dirtyUpdated() Fires the necessary property change event for changes to the dirty property.
protected void	enabledUpdated() Fires the necessary property change event for changes to the enabled property.
FormModel[]	getChildren() Returns an array of child form models.
org.springframework.binding.convert.ConversionService	getConversionService()
Class	getDefaultInstanceClass()
FieldFace	getFieldFace(String field) FIXME: this should be on the FieldMetadata class
protected FieldFaceSource	getFieldFaceSource() Returns the FieldFaceSource that should be used to obtain FieldFace instances for this form model.
FieldMetadata	getFieldMetadata(String propertyName) Returns the metadata for the given form field.
Set	getFieldNames() Returns the fields that are used by this formModel.
Object	getFormObject() Returns the object currently backing this form.
ValueModel	getFormObjectHolder() Returns the value model which holds the object currently backing this form.
MutablePropertyAccessStrategy	getFormObjectPropertyAccessStrategy()
String	getId() Returns the id that is used to identify this form model.
HierarchicalFormModel	getParent() Returns the parent form model or null of there is none.
PropertyAccessStrategy	getPropertyAccessStrategy()
ValueModel	getValueModel(String formProperty) Returns a value model that holds the value of the specified form property.
ValueModel	getValueModel(String formProperty, Class targetClass) Returns a type converting value model for the given form property.
protected void	handleSetNullFormObject()
boolean	hasValueModel(String formProperty) Returns true if the form has a value model for the provided property name.
boolean	isAuthorized() Check if the form has the correct authorization and can be edited.
boolean	isBuffered() Does this form model buffer changes?
boolean	isCommittable() Returns true if the changes held by this form are able to be committed.
boolean	isDirty() Returns true if this formModel or any of its children has dirty valueModels.
boolean	isEnabled() A form can be enabled/disabled which reflects a global state on the associated valueModels and their metaData.
boolean	isReadOnly() A form can be set as readOnly which reflects a global state on the valueModels and their metaData.
protected void	parentStateChanged(PropertyChangeEvent evt) Events from the parent form model that have side-effects on this form model should be handled here.
protected void	postCommit() Hook for subclasses to intercept after a successful commit has finished.
protected abstract void	postProcessNewConvertingValueModel(String formProperty, Class targetClass, ValueModel valueModel) Provides a hook for subclasses to perform some processing after a new converting value model has been added to this form model.
protected abstract void	postProcessNewValueModel(String formProperty, ValueModel valueModel) Provides a hook for subclasses to perform some processing after a new value model has been added to this form model.
protected void	preCommit() Hook for subclasses to intercept before a commit.
protected void	prepareValueModel(ValueModel valueModel) Prepare the provided value model for use in this form model.
protected abstract ValueModel	preProcessNewConvertingValueModel(String formProperty, Class targetClass, ValueModel formValueModel) Provides a hook for subclasses to optionally decorate a new converting value model added to this form model.
protected abstract ValueModel	preProcessNewValueModel(String formProperty, ValueModel formValueModel) Provides a hook for subclasses to optionally decorate a new value model added to this form model.
protected void	readOnlyUpdated() Fires the necessary property change event for changes to the readOnly property.
void	registerPropertyConverter(String propertyName, org.springframework.binding.convert.Converter toConverter, org.springframework.binding.convert.Converter fromConverter) Register converters for a given property name.
void	removeChild(HierarchicalFormModel child) Remove a child FormModel.
void	removeCommitListener(CommitListener listener) Removes the specified listener to the list if listeners notified when a commit happens.
void	removeParent() Remove the parent form model
void	reset() Complex forms with parent-child relations can use derived formModels.
void	revert() Revert state.
void	setAuthorized(boolean authorized) Set whether or not the form is authorized and can be edited.
void	setConversionService(org.springframework.binding.convert.ConversionService conversionService)
void	setDefaultInstanceClass(Class defaultInstanceClass)
void	setEnabled(boolean enabled) Set the enabled state of this formModel.
void	setFieldFaceSource(FieldFaceSource fieldFaceSource) Sets the FieldFaceSource that will be used to obtain FieldFace instances.
void	setFormObject(Object formObject) Sets the object currently backing this form.
void	setId(String id) An id to identify this formModel.
void	setParent(HierarchicalFormModel parent) Sets the parent form model.
void	setReadOnly(boolean readOnly) Set the readOnly state of this formModel.

Methods inherited from class org.springframework.binding.value.support.AbstractPropertyChangePublisher

addPropertyChangeListener, addPropertyChangeListener, addVetoableChangeListener, addVetoableChangeListener, firePropertiesChanged, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, fireVetoableChange, fireVetoableChange, fireVetoableChange, fireVetoableChange, fireVetoableChange, getPropertyChangeListeners, getPropertyChangeListeners, getVetoableChangeListeners, getVetoableChangeListeners, hasChanged, hasChanged, hasChanged, hasChanged, hasChanged, hasChanged, removePropertyChangeListener, removePropertyChangeListener, removeVetoableChangeListener, removeVetoableChangeListener

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.springframework.binding.value.PropertyChangePublisher

addPropertyChangeListener, addPropertyChangeListener, removePropertyChangeListener, removePropertyChangeListener

Field Detail

parentStateChangeHandler

protected final PropertyChangeListener parentStateChangeHandler

childStateChangeHandler

protected final PropertyChangeListener childStateChangeHandler

Constructor Detail

AbstractFormModel

protected AbstractFormModel()

AbstractFormModel

protected AbstractFormModel(Object domainObject)

AbstractFormModel

public AbstractFormModel(Object domainObject,
                         boolean buffered)

AbstractFormModel

protected AbstractFormModel(ValueModel domainObjectHolder,
                            boolean buffered)

AbstractFormModel

protected AbstractFormModel(MutablePropertyAccessStrategy propertyAccessStrategy,
                            boolean buffered)

Method Detail

prepareValueModel

protected void prepareValueModel(ValueModel valueModel)

Prepare the provided value model for use in this form model.

Parameters:

valueModel - to prepare

getId

public String getId()

Description copied from interface: FormModel

Returns the id that is used to identify this form model.

Specified by:

getId in interface FormModel

setId

public void setId(String id)

Description copied from interface: ConfigurableFormModel

An id to identify this formModel.

Specified by:

setId in interface ConfigurableFormModel

getFormObject

public Object getFormObject()

Description copied from interface: FormModel

Returns the object currently backing this form. This object is held by the FormObjectHolder.

Specified by:

getFormObject in interface FormModel

setFormObject

public void setFormObject(Object formObject)

Description copied from interface: FormModel

Sets the object currently backing this form.

Specified by:

setFormObject in interface FormModel

setDefaultInstanceClass

public void setDefaultInstanceClass(Class defaultInstanceClass)

getDefaultInstanceClass

public Class getDefaultInstanceClass()

handleSetNullFormObject

protected void handleSetNullFormObject()

getFormObjectHolder

public ValueModel getFormObjectHolder()

Returns the value model which holds the object currently backing this form.

Specified by:

getFormObjectHolder in interface FormModel

getParent

public HierarchicalFormModel getParent()

Description copied from interface: HierarchicalFormModel

Returns the parent form model or null of there is none.

Specified by:

getParent in interface HierarchicalFormModel

setParent

public void setParent(HierarchicalFormModel parent)

Sets the parent form model. When the parent is set, the enabled and read-only states are bound and updated as needed.

Specified by:

setParent in interface HierarchicalFormModel

removeParent

public void removeParent()

Description copied from interface: HierarchicalFormModel

Remove the parent form model

Specified by:

removeParent in interface HierarchicalFormModel

getChildren

public FormModel[] getChildren()

Description copied from interface: HierarchicalFormModel

Returns an array of child form models.

Specified by:

getChildren in interface HierarchicalFormModel

addChild

public void addChild(HierarchicalFormModel child)

Add child to this FormModel. Dirty and committable changes are forwarded to parent model.

Specified by:

addChild in interface HierarchicalFormModel

Parameters:

child - FormModel to add as child.

removeChild

public void removeChild(HierarchicalFormModel child)

Remove a child FormModel. Dirty and committable listeners are removed. When child was dirty, remove the formModel from the dirty list and update the dirty state.

Specified by:

removeChild in interface HierarchicalFormModel

Parameters:

child - FormModel to remove from childlist.

hasValueModel

public boolean hasValueModel(String formProperty)

Description copied from interface: FormModel

Returns true if the form has a value model for the provided property name.

Specified by:

hasValueModel in interface FormModel

getValueModel

public ValueModel getValueModel(String formProperty)

Description copied from interface: FormModel

Returns a value model that holds the value of the specified form property.

Specified by:

getValueModel in interface FormModel

getValueModel

public ValueModel getValueModel(String formProperty,
                                Class targetClass)

Description copied from interface: FormModel

Returns a type converting value model for the given form property. The type of the value returned from the returned value model is guaranteed to be of class targetClass.

Specified by:

getValueModel in interface FormModel

createValueModel

protected ValueModel createValueModel(String formProperty)

Creates a new value mode for the the given property. Usually delegates to the underlying property access strategy but subclasses may provide alternative value model creation strategies.

createConvertingValueModel

protected ValueModel createConvertingValueModel(String formProperty,
                                                Class targetClass)

registerPropertyConverter

public void registerPropertyConverter(String propertyName,
                                      org.springframework.binding.convert.Converter toConverter,
                                      org.springframework.binding.convert.Converter fromConverter)

Register converters for a given property name.

Specified by:

registerPropertyConverter in interface FormModel

Parameters:

propertyName - name of property on which to register converters

toConverter - Convert from source to target type

fromConverter - Convert from target to source type

add

public ValueModel add(String propertyName)

Description copied from interface: ConfigurableFormModel

Add a valueModel for the given property. Property should be accessible on the formObject.

Specified by:

add in interface ConfigurableFormModel

Parameters:

propertyName - the property to create a valueModel for.

Returns:

a ValueModel that wraps the property.

add

public ValueModel add(String formProperty,
                      ValueModel valueModel)

Description copied from interface: ConfigurableFormModel

Add the given valueModel as wrapper for the given property. Property should be accessible on the formObject. Note that the given valueModel should be used to access the property, but may be wrapped(chained) a number of times in other valueModels.

Specified by:

add in interface ConfigurableFormModel

Parameters:

formProperty - the property.

valueModel - the valueModel to access the property.

Returns:

a valueModel that wraps the given valueModel.

add

public ValueModel add(String propertyName,
                      ValueModel valueModel,
                      FieldMetadata metadata)

Add the given valueModel as wrapper for the given property. Note that the given valueModel should be used to access the property, but may be wrapped(chained) a number of times in other valueModels.

This adds another dimension to the formModel as this makes it possible to provide your own property that is not present on the formObject but does have a valueModel and metadata to bind fields and listen to.

Specified by:

add in interface ConfigurableFormModel

Parameters:

propertyName - the property, possibly not bound to the formObject.

valueModel - the valueModel to access the property.

metadata - the metadata for this valueModel.

Returns:

a valueModel that is or wraps the given valueModel.

See Also:

DerivedValueModel, AbstractDerivedValueModel, MessageFormatValueModel

preProcessNewValueModel

protected abstract ValueModel preProcessNewValueModel(String formProperty,
                                                      ValueModel formValueModel)

Provides a hook for subclasses to optionally decorate a new value model added to this form model.

postProcessNewValueModel

protected abstract void postProcessNewValueModel(String formProperty,
                                                 ValueModel valueModel)

Provides a hook for subclasses to perform some processing after a new value model has been added to this form model.

preProcessNewConvertingValueModel

protected abstract ValueModel preProcessNewConvertingValueModel(String formProperty,
                                                                Class targetClass,
                                                                ValueModel formValueModel)

Provides a hook for subclasses to optionally decorate a new converting value model added to this form model.

postProcessNewConvertingValueModel

protected abstract void postProcessNewConvertingValueModel(String formProperty,
                                                           Class targetClass,
                                                           ValueModel valueModel)

Provides a hook for subclasses to perform some processing after a new converting value model has been added to this form model.

getFieldMetadata

public FieldMetadata getFieldMetadata(String propertyName)

Description copied from interface: FormModel

Returns the metadata for the given form field.

Specified by:

getFieldMetadata in interface FormModel

getFieldNames

public Set getFieldNames()

Returns the fields that are used by this formModel. Each field has an associated ValueModel.

Specified by:

getFieldNames in interface FormModel

setFieldFaceSource

public void setFieldFaceSource(FieldFaceSource fieldFaceSource)

Sets the FieldFaceSource that will be used to obtain FieldFace instances.

If this value is null the default FieldFaceSource from ApplicationServices instance will be used.

getFieldFaceSource

protected FieldFaceSource getFieldFaceSource()

Returns the FieldFaceSource that should be used to obtain FieldFace instances for this form model.

getFieldFace

public FieldFace getFieldFace(String field)

Description copied from interface: FormModel

FIXME: this should be on the FieldMetadata class

Specified by:

getFieldFace in interface FormModel

addMethod

public ValueModel addMethod(String propertyMethodName,
                            String derivedFromProperty)

Description copied from interface: ConfigurableFormModel

Add a valueModel that holds a derived value computed by invoking the given method with the given property as argument on the formModel.

Specified by:

addMethod in interface ConfigurableFormModel

Parameters:

propertyMethodName - method to invoke.

derivedFromProperty - property to use as argument.

Returns:

a valueModel holding the derived value.

addMethod

public ValueModel addMethod(String propertyMethodName,
                            String[] derivedFromProperties)

Description copied from interface: ConfigurableFormModel

Add a valueModel that holds a derived value computed by invoking the given method with a number of other properties as arguments on the formModel.

Specified by:

addMethod in interface ConfigurableFormModel

Parameters:

propertyMethodName - method to invoke.

derivedFromProperties - a number of properties to use as arguments on the method.

Returns:

a valueModel holding the derived value.

getConversionService

public org.springframework.binding.convert.ConversionService getConversionService()

setConversionService

public void setConversionService(org.springframework.binding.convert.ConversionService conversionService)

getFormObjectPropertyAccessStrategy

public MutablePropertyAccessStrategy getFormObjectPropertyAccessStrategy()

getPropertyAccessStrategy

public PropertyAccessStrategy getPropertyAccessStrategy()

commit

public void commit()

Description copied from interface: FormModel

Commits any changes buffered by the form property value models into the current form backing object.

Specified by:

commit in interface FormModel

See Also:

FormModel.isCommittable()

preCommit

protected void preCommit()

Hook for subclasses to intercept before a commit.

postCommit

protected void postCommit()

Hook for subclasses to intercept after a successful commit has finished.

revert

public void revert()

Revert state. If formModel has children, these will be reverted first. CommitTrigger is used to revert bufferedValueModels while revertToOriginal() is called upon FormMediatingValueModels.

Specified by:

revert in interface FormModel

reset

public void reset()

Complex forms with parent-child relations can use derived formModels. Such a Hierarchical tree cannot have its children reset on its own as it would break the top-down structure. see RCP-329 and the cvs maillist. TODO add a unit test with such a complex use case

Specified by:

reset in interface FormModel

See Also:

FormModel.reset()

isBuffered

public boolean isBuffered()

Description copied from interface: FormModel

Does this form model buffer changes?

Specified by:

isBuffered in interface FormModel

isDirty

public boolean isDirty()

Returns true if this formModel or any of its children has dirty valueModels.

Specified by:

isDirty in interface FormModel

dirtyUpdated

protected void dirtyUpdated()

Fires the necessary property change event for changes to the dirty property. Must be called whenever the value of dirty is changed.

setReadOnly

public void setReadOnly(boolean readOnly)

Description copied from interface: ConfigurableFormModel

Set the readOnly state of this formModel. All fieldMetaData should take the readOnly state of the formModel into account but should not alter their own enclosed readOnly state.

A formModel in readOnly state can be seen as visual component in which the user can navigate but not alter any values. (Eg editable TextFields)

Specified by:

setReadOnly in interface ConfigurableFormModel

Parameters:

readOnly - set to true if all fields should be set readOnly.

isReadOnly

public boolean isReadOnly()

Description copied from interface: FormModel

A form can be set as readOnly which reflects a global state on the valueModels and their metaData. A form may be enabled and readonly when all values are accessible, but not changeable. A form can be seen as not readOnly if some visual representatives of the valuemodels are set to editable/changeable.

Specified by:

isReadOnly in interface FormModel

Returns:

true if this form is readOnly.

isAuthorized

public boolean isAuthorized()

Check if the form has the correct authorization and can be edited.

Specified by:

isAuthorized in interface Authorizable

Returns:

true if this form is authorized and may be edited.

setAuthorized

public void setAuthorized(boolean authorized)

Set whether or not the form is authorized and can be edited.

Specified by:

setAuthorized in interface Authorizable

Parameters:

authorized - true if this form may be edited.

readOnlyUpdated

protected void readOnlyUpdated()

Fires the necessary property change event for changes to the readOnly property. Must be called whenever the value of readOnly is changed.

setEnabled

public void setEnabled(boolean enabled)

Description copied from interface: ConfigurableFormModel

Set the enabled state of this formModel. All fieldMetaData should take the enabled state of the formModel into account but should not alter their own enclosed enabled state.

A disabled formModel can be compared to a visual component which doesn't respond to any user interaction (grey-out).

Specified by:

setEnabled in interface ConfigurableFormModel

Parameters:

enabled - set to true if the formModel should be enabled. Set to false if all fields should be disabled.

isEnabled

public boolean isEnabled()

Description copied from interface: FormModel

A form can be enabled/disabled which reflects a global state on the associated valueModels and their metaData. It may be viewed as enabling the visual representatives of the valuemodels. All user related interaction should be disabled. This is usually viewed as a grey-out of the visual form. Returns true if this form is enabled.

Specified by:

isEnabled in interface FormModel

enabledUpdated

protected void enabledUpdated()

Fires the necessary property change event for changes to the enabled property. Must be called whenever the value of enabled is changed.

isCommittable

public boolean isCommittable()

Description copied from interface: FormModel

Returns true if the changes held by this form are able to be committed. A form is committable when it and it's child form models have no validation errors.

Specified by:

isCommittable in interface FormModel

committableUpdated

protected void committableUpdated()

Fires the necessary property change event for changes to the committable property. Must be called whenever the value of committable is changed.

addCommitListener

public void addCommitListener(CommitListener listener)

Description copied from interface: FormModel

Adds the specified listener to the list if listeners notified when a commit happens.

Specified by:

addCommitListener in interface FormModel

removeCommitListener

public void removeCommitListener(CommitListener listener)

Description copied from interface: FormModel

Removes the specified listener to the list if listeners notified when a commit happens.

Specified by:

removeCommitListener in interface FormModel

parentStateChanged

protected void parentStateChanged(PropertyChangeEvent evt)

Events from the parent form model that have side-effects on this form model should be handled here. This includes:

• Enabled state: when parent gets disabled, child should be disabled as well. If parent is enabled, child should go back to its original state.
• Read-only state: when a parent is set read-only, child should be read-only as well. If parent is set editable, child should go back to its original state.

childStateChanged

protected void childStateChanged(PropertyChangeEvent evt)

Events from the child form model or value models that have side-effects on this form model should be handled here. This includes:

• Dirty state: when a child is dirty, the parent should be dirty.
• Committable state: when a child is committable, the parent might be committable as well. The committable state of the parent should be taken into account and revised when a child sends this event.

Note that we include value models and their metadata as being children. As these are low level models, they cannot be parents and therefore don't show up in parentStateChanged(PropertyChangeEvent).