org.springframework.richclient.form
Class AbstractForm

Show UML class diagram

java.lang.Object
  org.springframework.richclient.application.support.ApplicationServicesAccessor
      org.springframework.richclient.factory.AbstractControlFactory
          org.springframework.richclient.form.AbstractForm

All Implemented Interfaces:

CommitListener, ControlFactory, Form

Direct Known Subclasses:

AbstractDetailForm, AbstractMasterForm, AbstractReporterForm, AbstractWidgetForm, FilterForm, GeneratedForm, LoginForm, StringLenghtConstraintDialog.StringLengthConstraintForm

public abstract class AbstractForm
extends AbstractControlFactory
implements Form, CommitListener

Base implementation of a Form. Commands provided:

• CommitCommand: wraps the FormModel.commit() method. Writes data to backing bean. Guarded mask FormGuard.ON_NOERRORS, FormGuard.ON_ISDIRTY and FormGuard.ON_ENABLED.
• RevertCommand: wraps the FormModel.revert() method. Fall back to the values of the backing bean. Guarded mask FormGuard.ON_ISDIRTY and FormGuard.ON_ENABLED.
• NewFormObjectCommand: set a fresh instance on the FormModel. Guarded mask FormGuard.ON_ENABLED

All commands provide a securityControllerId.

Author:

Keith Donald

Field Summary

Fields inherited from class org.springframework.richclient.application.support.ApplicationServicesAccessor

logger

Constructor Summary

protected	AbstractForm() Default constructor will use the uncapitalized simplename of the class to construct its id.
protected	AbstractForm(FormModel formModel) Create an AbstractForm with the given FormModel.
protected	AbstractForm(FormModel formModel, String formId) Create an AbstractForm.
protected	AbstractForm(HierarchicalFormModel parentFormModel, String formId, String childFormObjectPropertyPath) Create a Form with a FormModel that has a child-parent relation with the provided parentFormModel.
protected	AbstractForm(HierarchicalFormModel parentFormModel, String formId, ValueModel childFormObjectHolder) Create a Form with a FormModel that has a child-parent relation with the provided parentFormModel.
protected	AbstractForm(Object formObject) Convenience constructor which creates a FormModel by calling FormModelHelper.createFormModel(Object).
protected	AbstractForm(String formId) Id configurable constructor.

Method Summary

void	addChildForm(Form childForm) Add a child (or sub) form to this form.
void	addFormObjectChangeListener(PropertyChangeListener listener)
void	addFormValueChangeListener(String formPropertyPath, PropertyChangeListener listener)
void	addGuarded(Guarded guarded) Attach the given Guarded object with the default mask to the formModel.
void	addGuarded(Guarded guarded, int mask) Attach the given Guarded object with the specified mask to the formModel.
void	addValidationListener(ValidationListener listener) Add a ValidationListener.
void	addValidationResultsReporter(ValidationResultsReporter reporter) Add a ValidationResultsReporter to this Form.
protected void	attachFormErrorGuard(Guarded guarded)
protected void	attachFormGuard(Guarded guarded, int mask)
void	commit() Commit all values of the FormModel.
protected String	constructSecurityControllerId(String commandFaceId) Construct a default security controller Id for a given command face id.
protected JButton	createCommitButton()
protected JComponent	createControl() Subclasses must override this method to create a new instance of the control that this factory produces.
protected abstract JComponent	createFormControl()
protected JButton	createNewFormObjectButton()
protected Object	createNewObject() Create a new object to install into the form.
protected void	detachFormGuard(Guarded guarded)
BindingFactory	getBindingFactory() Returns a BindingFactory bound to the inner FormModel to provide binding support.
protected Form	getChildForm(String id) Return a child form of this form with the given form id.
ActionCommand	getCommitCommand()
protected String	getCommitCommandFaceDescriptorId()
protected String	getCommitSecurityControllerId() Subclasses may override to return a security controller id to be attached to the commit command.
protected JButton	getDefaultButton()
protected Object	getEditableFormObject(int selectionIndex)
protected int	getEditingFormObjectIndex()
ValidatingFormModel	getFormModel() Returns the formModel used by the form.
Object	getFormObject() Convenience method to return the formObject currently used in the inner formModel.
String	getId() Returns the id of this form.
ActionCommand	getNewFormObjectCommand()
protected String	getNewFormObjectCommandId()
protected String	getNewFormObjectSecurityControllerId() Subclasses may override to return a security controller id to be attached to the newFormObject command.
protected HierarchicalFormModel	getParent() Returns the parent of this Form's FormModel or null.
ActionCommand	getRevertCommand()
protected String	getRevertCommandFaceDescriptorId()
List	getValidationResultsReporters() Returns the list of ValidationResultsReporters of this Form.
Object	getValue(String formProperty) Convenience method to get the value of a specific property from the inner formModel.
ValueModel	getValueModel(String formProperty) Convenience method to get the valueModel of a specific property from the inner formModel.
protected void	handleEnabledChange(boolean enabled)
boolean	hasErrors() Returns true if the inner FormModel has errors.
protected void	init() Hook called when constructing the Form.
boolean	isDirty()
boolean	isEditingNewFormObject()
boolean	isEnabled()
ValidationResultsReporter	newSingleLineResultsReporter(Messagable messageReceiver) Construct the validation results reporter for this form and attach it to the provided Guarded object.
void	postCommit(FormModel formModel) Called just after a form model is commited.
void	preCommit(FormModel formModel) Called just before a form model is about to commit.
void	removeChildForm(Form childForm) Remove the given Form as child from this Form.
void	removeFormObjectChangeListener(PropertyChangeListener listener)
void	removeFormValueChangeListener(String formPropertyPath, PropertyChangeListener listener)
void	removeGuarded(Guarded guarded) Detach the Guarded object.
void	removeValidationListener(ValidationListener listener) Remove a ValidationListener.
void	removeValidationResultsReporter(ValidationResultsReporter reporter) Remove the given ValidationResultsReporter from this Form.
void	reset() Reset the FormModel.
void	revert() Revert the FormModel.
void	setClearFormOnCommit(boolean clearFormOnCommit)
protected void	setDefaultButton(JButton button)
protected void	setEditableFormObjects(ObservableList editableFormObjects)
protected void	setEditingFormObjectIndexHolder(ValueModel valueModel)
protected void	setEditingFormObjectIndexSilently(int index)
protected void	setEditingNewFormObject(boolean editingNewFormOject) Set the "editing new form object" state as indicated.
void	setEnabled(boolean enabled)
protected void	setFormModel(ValidatingFormModel formModel) Set the FormModel for this Form.
protected void	setFormModelDefaultEnabledState() Set the form's enabled state based on a default policy--specifically, disable if the form object is null or the form object is guarded and is marked as disabled.
void	setFormObject(Object formObject) Convenience method to set the formObject on the inner formModel.
protected void	setId(String formId) Set the id used to configure this Form.

Methods inherited from class org.springframework.richclient.factory.AbstractControlFactory

createControlIfNecessary, getControl, isControlCreated, isSingleton, setSingleton

Methods inherited from class org.springframework.richclient.application.support.ApplicationServicesAccessor

getActiveWindow, getApplication, getApplicationContext, getApplicationName, getApplicationServices, getCommandConfigurer, getComponentFactory, getConversionService, getIconSource, getImageSource, getMessage, getMessage, getMessage, getMessage, getMessages, getMessageSource, getObjectConfigurer, getService

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.springframework.richclient.factory.ControlFactory

getControl

Constructor Detail

AbstractForm

protected AbstractForm()

Default constructor will use the uncapitalized simplename of the class to construct its id.

AbstractForm

protected AbstractForm(String formId)

Id configurable constructor.

AbstractForm

protected AbstractForm(Object formObject)

Convenience constructor which creates a FormModel by calling FormModelHelper.createFormModel(Object).

Parameters:

formObject - object used to create the formModel.

See Also:

AbstractForm(FormModel)

AbstractForm

protected AbstractForm(FormModel formModel)

Create an AbstractForm with the given FormModel. Use the formModel's id to configure the Form.

See Also:

AbstractForm(FormModel, String)

AbstractForm

protected AbstractForm(FormModel formModel,
                       String formId)

Create an AbstractForm.

AbstractForm

protected AbstractForm(HierarchicalFormModel parentFormModel,
                       String formId,
                       String childFormObjectPropertyPath)

Create a Form with a FormModel that has a child-parent relation with the provided parentFormModel.

Parameters:

parentFormModel - the parent formModel.

formId - id used for this Form's configuration.

childFormObjectPropertyPath - the path relative to the parentFormModel's formObject that leads to the child formObject that will be handled by this Form.

See Also:

FormModelHelper.createChildPageFormModel(HierarchicalFormModel, String, String)

AbstractForm

protected AbstractForm(HierarchicalFormModel parentFormModel,
                       String formId,
                       ValueModel childFormObjectHolder)

Create a Form with a FormModel that has a child-parent relation with the provided parentFormModel.

Parameters:

parentFormModel - the parent formModel.

formId - id used for this Form's configuration.

childFormObjectHolder - the valueModel of the parentFormModel that holds the child formObject that will be handled by this Form.

See Also:

FormModelHelper.createChildPageFormModel(HierarchicalFormModel, String, ValueModel)

Method Detail

init

protected void init()

Hook called when constructing the Form.

getId

public String getId()

Description copied from interface: Form

Returns the id of this form.

Specified by:

getId in interface Form

setId

protected void setId(String formId)

Set the id used to configure this Form.

getFormModel

public ValidatingFormModel getFormModel()

Description copied from interface: Form

Returns the formModel used by the form.

Specified by:

getFormModel in interface Form

getBindingFactory

public BindingFactory getBindingFactory()

Returns a BindingFactory bound to the inner FormModel to provide binding support.

setFormModel

protected void setFormModel(ValidatingFormModel formModel)

Set the FormModel for this Form. Normally a Form won't change it's FormModel as this may lead to an inconsistent state. Only use this when the formModel isn't set yet. TODO check why we do allow setting when no control is created. ValueModels might exist already leading to an inconsistent state.

Parameters:

formModel -

getParent

protected HierarchicalFormModel getParent()

Returns the parent of this Form's FormModel or null.

addChildForm

public void addChildForm(Form childForm)

Add a child (or sub) form to this form. Child forms will be tied in to the same validation results reporter as this form and they will be configured to control the same guarded object as this form.

Validation listeners are unique to a form, so calling addValidationListener(ValidationListener) will only add a listener to this form. If you want to listen to the child forms, you will need to add a validation listener on each child form of interest.

Note: It is very important that the child form provided be created using a form model that is a child model of this form's form model. If this is not done, then commit and revert operations will not be properly delegated to the child form models.

Specified by:

addChildForm in interface Form

Parameters:

childForm - to add

getValidationResultsReporters

public List getValidationResultsReporters()

Description copied from interface: Form

Returns the list of ValidationResultsReporters of this Form.

Specified by:

getValidationResultsReporters in interface Form

addValidationResultsReporter

public void addValidationResultsReporter(ValidationResultsReporter reporter)

Description copied from interface: Form

Add a ValidationResultsReporter to this Form.

Specified by:

addValidationResultsReporter in interface Form

removeValidationResultsReporter

public void removeValidationResultsReporter(ValidationResultsReporter reporter)

Description copied from interface: Form

Remove the given ValidationResultsReporter from this Form.

Specified by:

removeValidationResultsReporter in interface Form

removeChildForm

public void removeChildForm(Form childForm)

Description copied from interface: Form

Remove the given Form as child from this Form. Parent-child relation will be removed from their FormModels and other aspects as well.

Specified by:

removeChildForm in interface Form

getChildForm

protected Form getChildForm(String id)

Return a child form of this form with the given form id.

Parameters:

id - of child form

Returns:

child form, null if no child form with the given id has been registered

setEditableFormObjects

protected void setEditableFormObjects(ObservableList editableFormObjects)

setEditingFormObjectIndexHolder

protected void setEditingFormObjectIndexHolder(ValueModel valueModel)

isEditingNewFormObject

public boolean isEditingNewFormObject()

setEditingNewFormObject

protected void setEditingNewFormObject(boolean editingNewFormOject)

Set the "editing new form object" state as indicated.

Parameters:

editingNewFormOject -

getEditingFormObjectIndex

protected int getEditingFormObjectIndex()

getEditableFormObject

protected Object getEditableFormObject(int selectionIndex)

setClearFormOnCommit

public void setClearFormOnCommit(boolean clearFormOnCommit)

getDefaultButton

protected JButton getDefaultButton()

setDefaultButton

protected void setDefaultButton(JButton button)

createControl

protected final JComponent createControl()

Description copied from class: AbstractControlFactory

Subclasses must override this method to create a new instance of the control that this factory produces.

Specified by:

createControl in class AbstractControlFactory

Returns:

The newly created control, never null.

setFormModelDefaultEnabledState

protected void setFormModelDefaultEnabledState()

Set the form's enabled state based on a default policy--specifically, disable if the form object is null or the form object is guarded and is marked as disabled.

createFormControl

protected abstract JComponent createFormControl()

handleEnabledChange

protected void handleEnabledChange(boolean enabled)

getNewFormObjectCommand

public ActionCommand getNewFormObjectCommand()

getCommitCommand

public ActionCommand getCommitCommand()

getRevertCommand

public ActionCommand getRevertCommand()

createNewObject

protected Object createNewObject()

Create a new object to install into the form. By default, this simply returns null. This will cause the form model to instantiate a new copy of the model object class. Subclasses should override this method if they need more control over how new objects are constructed.

Returns:

new object for editing

setEditingFormObjectIndexSilently

protected void setEditingFormObjectIndexSilently(int index)

preCommit

public void preCommit(FormModel formModel)

Description copied from interface: CommitListener

Called just before a form model is about to commit.

Specified by:

preCommit in interface CommitListener

postCommit

public void postCommit(FormModel formModel)

Description copied from interface: CommitListener

Called just after a form model is commited.

Specified by:

postCommit in interface CommitListener

createNewFormObjectButton

protected final JButton createNewFormObjectButton()

createCommitButton

protected final JButton createCommitButton()

getNewFormObjectCommandId

protected String getNewFormObjectCommandId()

getCommitCommandFaceDescriptorId

protected String getCommitCommandFaceDescriptorId()

getRevertCommandFaceDescriptorId

protected String getRevertCommandFaceDescriptorId()

getNewFormObjectSecurityControllerId

protected String getNewFormObjectSecurityControllerId()

Subclasses may override to return a security controller id to be attached to the newFormObject command. The default is [formModel.id] + "." + [getNewFormObjectCommandId()].

This id can be mapped to a specific security controller using the SecurityControllerManager service.

Returns:

security controller id, may be null if the face id is null

See Also:

SecurityControllerManager

getCommitSecurityControllerId

protected String getCommitSecurityControllerId()

Subclasses may override to return a security controller id to be attached to the commit command. The default is The default is [formModel.id] + "." + [getCommitCommandFaceDescriptorId()].

This id can be mapped to a specific security controller using the SecurityControllerManager service.

Returns:

security controller id, may be null if the face id is null

See Also:

SecurityControllerManager

constructSecurityControllerId

protected String constructSecurityControllerId(String commandFaceId)

Construct a default security controller Id for a given command face id. The id will be a combination of the form model id, if any, and the face id.

[formModel.id] + "." + [commandFaceId] if the form model id is not null.

[commandFaceId] if the form model is null.

null if the commandFaceId is null.

Parameters:

commandFaceId -

Returns:

default security controller id

attachFormErrorGuard

protected void attachFormErrorGuard(Guarded guarded)

attachFormGuard

protected void attachFormGuard(Guarded guarded,
                               int mask)

detachFormGuard

protected void detachFormGuard(Guarded guarded)

getFormObject

public Object getFormObject()

Description copied from interface: Form

Convenience method to return the formObject currently used in the inner formModel.

Specified by:

getFormObject in interface Form

setFormObject

public void setFormObject(Object formObject)

Description copied from interface: Form

Convenience method to set the formObject on the inner formModel.

Specified by:

setFormObject in interface Form

getValue

public Object getValue(String formProperty)

Description copied from interface: Form

Convenience method to get the value of a specific property from the inner formModel.

Specified by:

getValue in interface Form

getValueModel

public ValueModel getValueModel(String formProperty)

Description copied from interface: Form

Convenience method to get the valueModel of a specific property from the inner formModel.

Specified by:

getValueModel in interface Form

isEnabled

public boolean isEnabled()

setEnabled

public void setEnabled(boolean enabled)

addValidationListener

public void addValidationListener(ValidationListener listener)

Description copied from interface: Form

Add a ValidationListener.

Specified by:

addValidationListener in interface Form

removeValidationListener

public void removeValidationListener(ValidationListener listener)

Description copied from interface: Form

Remove a ValidationListener.

Specified by:

removeValidationListener in interface Form

newSingleLineResultsReporter

public ValidationResultsReporter newSingleLineResultsReporter(Messagable messageReceiver)

Construct the validation results reporter for this form and attach it to the provided Guarded object. An instance of SimpleValidationResultsReporter will be constructed and returned. All registered child forms will be attached to the same guarded and messageReceiver as this form.

Specified by:

newSingleLineResultsReporter in interface Form

Parameters:

messageReceiver - the message receiver used by the created resultsReporter.

Returns:

a new ResultsReporter.

addFormObjectChangeListener

public void addFormObjectChangeListener(PropertyChangeListener listener)

removeFormObjectChangeListener

public void removeFormObjectChangeListener(PropertyChangeListener listener)

addFormValueChangeListener

public void addFormValueChangeListener(String formPropertyPath,
                                       PropertyChangeListener listener)

removeFormValueChangeListener

public void removeFormValueChangeListener(String formPropertyPath,
                                          PropertyChangeListener listener)

isDirty

public boolean isDirty()

hasErrors

public boolean hasErrors()

Description copied from interface: Form

Returns true if the inner FormModel has errors.

Specified by:

hasErrors in interface Form

commit

public void commit()

Description copied from interface: Form

Commit all values of the FormModel.

Specified by:

commit in interface Form

See Also:

FormModel.commit()

revert

public void revert()

Description copied from interface: Form

Revert the FormModel.

Specified by:

revert in interface Form

See Also:

FormModel.revert()

reset

public void reset()

Description copied from interface: Form

Reset the FormModel.

Specified by:

reset in interface Form

See Also:

FormModel.reset()

addGuarded

public void addGuarded(Guarded guarded)

Description copied from interface: Form

Attach the given Guarded object with the default mask to the formModel.

Specified by:

addGuarded in interface Form

See Also:

Form.addGuarded(Guarded, int), FormGuard

addGuarded

public void addGuarded(Guarded guarded,
                       int mask)

Description copied from interface: Form

Attach the given Guarded object with the specified mask to the formModel.

Specified by:

addGuarded in interface Form

See Also:

FormGuard

removeGuarded

public void removeGuarded(Guarded guarded)

Description copied from interface: Form

Detach the Guarded object.

Specified by:

removeGuarded in interface Form