org.springframework.binding.form
Interface FormModel

All Superinterfaces:

PropertyChangePublisher

All Known Subinterfaces:

ConfigurableFormModel, HierarchicalFormModel, ValidatingFormModel

All Known Implementing Classes:

AbstractFormModel, DefaultFormModel

public interface FormModel
extends PropertyChangePublisher

A formModel groups valueModels and actions that are related to the same backing object. It will manage the creation/handling of the valueModels, their associated metadata and an overal state.

The formModel can be in one of three 'user' states:

• Disabled: all user interaction should be ignored.
• Enabled and readOnly: user may interact, but not edit.
• Enabled and editable: user may interact and edit where needed.

These states are counterparts of the enabled/editable state of a component/textcomponent.

The formModel also tracks its inner states:

• Dirty: one of its valueModels has a changed value.
• Committable: all valueModels are in an 'error-free' state.

Author:

Keith Donald, Oliver Hutchison

See Also:

ConfigurableFormModel

Field Summary

static String	COMMITTABLE_PROPERTY The name of the bound property committable.
static String	DIRTY_PROPERTY The name of the bound property dirty.
static String	ENABLED_PROPERTY The name of the bound property enabled.
static String	READONLY_PROPERTY The name of the bound property readonly.

Method Summary

void	addCommitListener(CommitListener listener) Adds the specified listener to the list if listeners notified when a commit happens.
void	commit() Commits any changes buffered by the form property value models into the current form backing object.
FieldFace	getFieldFace(String field) FIXME: this should be on the FieldMetadata class
FieldMetadata	getFieldMetadata(String field) 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.
String	getId() Returns the id that is used to identify this form model.
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.
boolean	hasValueModel(String formProperty) Returns true if the form has a value model for the provided property name.
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 any of the value models holding properties of this form have been modified since the last call to either commit or revert or since the last change of the form backing object.
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.
void	registerPropertyConverter(String propertyName, org.springframework.binding.convert.Converter toConverter, org.springframework.binding.convert.Converter fromConverter) Register converters for a given property name.
void	removeCommitListener(CommitListener listener) Removes the specified listener to the list if listeners notified when a commit happens.
void	reset() Reset the form by replacing the form object with a newly instantiated object of the type of the current form object.
void	revert() Reverts any dirty value models back to the original values that were loaded from the current form backing object since last call to either commit or revert or since the last change of the form backing object.
void	setFormObject(Object formObject) Sets the object currently backing this form.

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

addPropertyChangeListener, addPropertyChangeListener, removePropertyChangeListener, removePropertyChangeListener

Field Detail

DIRTY_PROPERTY

static final String DIRTY_PROPERTY

The name of the bound property dirty.

See Also:

Constant Field Values

ENABLED_PROPERTY

static final String ENABLED_PROPERTY

The name of the bound property enabled.

See Also:

Constant Field Values

READONLY_PROPERTY

static final String READONLY_PROPERTY

The name of the bound property readonly.

See Also:

Constant Field Values

COMMITTABLE_PROPERTY

static final String COMMITTABLE_PROPERTY

The name of the bound property committable.

See Also:

Constant Field Values

Method Detail

getId

String getId()

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

getFormObject

Object getFormObject()

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

setFormObject

void setFormObject(Object formObject)

Sets the object currently backing this form.

getFormObjectHolder

ValueModel getFormObjectHolder()

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

getValueModel

ValueModel getValueModel(String formProperty)

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

Throws:

InvalidPropertyException - if the form has no such property

getValueModel

ValueModel getValueModel(String formProperty,
                         Class targetClass)

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.

Throws:

InvalidPropertyException - if the form has no such property

IllegalArgumentException - if no suitable converter from the original property class to the targetClass can be found

getFieldMetadata

FieldMetadata getFieldMetadata(String field)

Returns the metadata for the given form field.

getFieldNames

Set getFieldNames()

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

registerPropertyConverter

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

Register converters for a given property name.

Parameters:

propertyName - name of property on which to register converters

toConverter - Convert from source to target type

fromConverter - Convert from target to source type

hasValueModel

boolean hasValueModel(String formProperty)

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

commit

void commit()

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

Throws:

IllegalStateException - if the form model is not committable

See Also:

isCommittable()

revert

void revert()

Reverts any dirty value models back to the original values that were loaded from the current form backing object since last call to either commit or revert or since the last change of the form backing object.

reset

void reset()

Reset the form by replacing the form object with a newly instantiated object of the type of the current form object. Note that this may lead to NPE's if the newly created object has null sub-objects and this form references any of these objects.

isBuffered

boolean isBuffered()

Does this form model buffer changes?

isDirty

boolean isDirty()

Returns true if any of the value models holding properties of this form have been modified since the last call to either commit or revert or since the last change of the form backing object.

isEnabled

boolean isEnabled()

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.

isReadOnly

boolean isReadOnly()

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.

Returns:

true if this form is readOnly.

isCommittable

boolean isCommittable()

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.

addCommitListener

void addCommitListener(CommitListener listener)

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

removeCommitListener

void removeCommitListener(CommitListener listener)

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

getFieldFace

FieldFace getFieldFace(String field)

FIXME: this should be on the FieldMetadata class