Class FormController
- java.lang.Object
-
- net.sf.jguiraffe.gui.builder.window.ctrl.FormController
-
- All Implemented Interfaces:
EventListener
,FormActionListener
,FormEventListener
,FormFocusListener
,WindowListener
public class FormController extends Object implements WindowListener, FormFocusListener, FormActionListener
A base class for form controllers.
The form builder library follows the MVC paradigm when dealing with forms:
- The dialog window displaying the input fields plays the role of the view.
- The model is represented by a data object, the so-called form bean
or model object. This object has
properties that are bound to the input fields of the form. It stores the data
entered by the user. In the initialization phase it provides the data for
filling the input fields. Access to the model object is controlled by a
BindingStrategy
. - The controller can be an instance of this class or one of its subclasses. It controls the form's life-cycle and ensures that user input is validated and correctly saved in the model.
This class provides a fully functional controller implementation, which handles all phases of the form's life-cycle. It can be used out of the box. In most cases adaptation to a specific application's needs is possible by configuring some of the helper objects used by this class. This way for instance the validation handling can be changed or the way fields containing invalid data are displayed. Refer to the documentation of the corresponding set methods for further details.
One of the main tasks of this class is to ensure that input validation is performed when necessary. When clicking the OK button, a validation has to be performed in any case. But it is also possible to perform validation earlier, e.g. when the user left an input field. This can be achieved by configuring a corresponding
FormValidationTrigger
. AFieldMarker
is used for defining the appearance of input fields depending on their validation status.Implementation note: This class is not thread-safe. It is intended to be associated with a single form instance and not to be used concurrently with multiple forms or threads.
- Version:
- $Id: FormController.java 205 2012-01-29 18:29:57Z oheger $
- Author:
- Oliver Heger
-
-
Constructor Summary
Constructors Constructor Description FormController()
Creates a new instance ofFormController
.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
actionPerformed(FormActionEvent e)
Processes action events.void
addFieldStatusListener(FormControllerFieldStatusListener l)
Adds aFormControllerFieldStatusListener
to this controller.void
addFormListener(FormControllerFormListener l)
Adds aFormControllerFormListener
to this controller.void
addValidationListener(FormControllerValidationListener l)
Adds aFormControllerValidationListener
to this controller.protected void
cancelButtonClicked(FormActionEvent event)
The cancel button was clicked.protected void
closeForm()
Closes the associated form.protected MessageOutput
fetchMessageOutput()
Returns the currentMessageOutput
object.protected String
fetchValidationMessageBoxCaption()
Returns the caption for a message box for displaying validation error messages.protected FormValidationMessageFormat
fetchValidationMessageFormat()
Obtains theFormValidationMessageFormat
object to be used.protected void
fireFieldStatusEvent(String fieldName)
Notifies all registered field status listeners about a change in the status of a field.protected void
fireFormEvent()
Notifies all registered form listeners that the form has been closed.protected void
fireValidationEvent(FormValidatorResults results)
Notifies all registered validation listeners about a validation operation.void
focusGained(FormFocusEvent e)
A component of the associated window was given the focus.void
focusLost(FormFocusEvent e)
A component of the associated window lost the focus.String
getBtnCancelName()
Returns the name of the component representing the cancel button.String
getBtnOkName()
Returns the name of the component representing the OK button.protected BuilderData
getBuilderData()
Returns the currentBuilderData
object.Command
getCancelCommand()
Returns the command to be executed when the form is canceled.ComponentBuilderData
getComponentBuilderData()
Returns theComponentBuilderData
object.FormControllerFieldStatusListener[]
getFieldStatusListeners()
Returns an array with allFormControllerFieldStatusListener
objects registered at thisFormController
.Form
getForm()
Returns the current form.Object
getFormBean()
Returns the current form bean.FormControllerFormListener[]
getFormListeners()
Returns an array with allFormControllerFormListener
objects registered at thisFormController
.FormValidator
getFormValidator()
Returns aFormValidator
for validating the associated form.FormValidatorResults
getLastValidationResults()
Returns the results of the last validation operation.MessageOutput
getMessageOutput()
Returns theMessageOutput
object to be used by this controller.Command
getOkCommand()
Returns the command to be executed when the form is closed in reaction of the OK button.FormControllerValidationListener[]
getValidationListeners()
Returns an array with allFormControllerValidationListener
objects registered at thisFormController
.String
getValidationMessageBoxCaption()
Returns the caption of the message box for displaying validation error messages.FormValidationMessageFormat
getValidationMessageFormat()
Returns theFormValidationMessageFormat
object to be used by this controller.FormValidationTrigger
getValidationTrigger()
Returns theFormValidationTrigger
.Window
getWindow()
Returns the associated window.WindowBuilderData
getWindowBuilderData()
Returns theWindowBuilderData
object.protected boolean
isCommitted()
Returns a flag whether the form was committed.boolean
isFieldVisited(String name)
Tests whether the field with the given name has already been visited by the user.protected void
okButtonClicked(FormActionEvent event)
The OK button was clicked.void
removeFieldStatusListener(FormControllerFieldStatusListener l)
Removes the specifiedFormControllerFieldStatusListener
from this controller.void
removeFormListener(FormControllerFormListener l)
Removes the specifiedFormControllerFormListener
from this controller.void
removeValidationListener(FormControllerValidationListener l)
Removes the specifiedFormControllerValidationListener
from this controller.void
setBtnCancelName(String btnCancelName)
Sets the name of the component representing the cancel button.void
setBtnOkName(String btnOkName)
Sets the name of the component representing the OK button.void
setCancelCommand(Command cancelCommand)
Sets the command to be executed when the form is canceled.void
setComponentBuilderData(ComponentBuilderData componentBuilderData)
Sets theComponentBuilderData
object.void
setFormValidator(FormValidator formValidator)
Sets aFormValidator
for the the associated form.void
setMessageOutput(MessageOutput messageOutput)
Sets theMessageOutput
object to be used by this controller.void
setOkCommand(Command okCommand)
Sets the command to be executed when the form is closed in reaction of the OK button.void
setValidationMessageBoxCaption(String validationMessageBoxCaption)
Sets the caption of the message box for displaying validation error messages.void
setValidationMessageFormat(FormValidationMessageFormat validationMessageFormat)
Sets theFormValidationMessageFormat
object to be used by this controller.void
setValidationTrigger(FormValidationTrigger validationTrigger)
Sets theFormValidationTrigger
.void
setWindowBuilderData(WindowBuilderData windowBuilderData)
Sets theWindowBuilderData
object.FormValidatorResults
validate()
Performs a validation of the associated form.FormValidatorResults
validateAndDisplayMessages()
Performs a validation of the associated form and displays validation messages if this is not successful.void
windowActivated(WindowEvent event)
Dummy implementation of this window event.void
windowClosed(WindowEvent event)
The associated window was closed.void
windowClosing(WindowEvent event)
Dummy implementation of this window event.void
windowDeactivated(WindowEvent event)
Dummy implementation of this window event.void
windowDeiconified(WindowEvent event)
Dummy implementation of this window event.void
windowIconified(WindowEvent event)
Dummy implementation of this window event.void
windowOpened(WindowEvent event)
The window containing the associated form was opened.
-
-
-
Method Detail
-
getComponentBuilderData
public ComponentBuilderData getComponentBuilderData()
Returns theComponentBuilderData
object.- Returns:
- the object with information about all components that belong to the current form
-
setComponentBuilderData
public void setComponentBuilderData(ComponentBuilderData componentBuilderData)
Sets theComponentBuilderData
object. This object must have been set before an instance of this class can be used. It allows access to all components involved and the current form as well.- Parameters:
componentBuilderData
- the component builder data object
-
getWindowBuilderData
public WindowBuilderData getWindowBuilderData()
Returns theWindowBuilderData
object.- Returns:
- the data object with information about the current window
-
setWindowBuilderData
public void setWindowBuilderData(WindowBuilderData windowBuilderData)
Sets theWindowBuilderData
object. This object must have been set before an instance of this class can be used. It allows access to important information about the current window including its form bean.- Parameters:
windowBuilderData
- the window builder data object
-
getFormValidator
public FormValidator getFormValidator()
Returns aFormValidator
for validating the associated form. Result can be null if no specificFormValidator
was set. Note that the result of this method need not always be in sync with the object returned byForm.getFormValidator()
: this method always returns the object that was set on a previoussetFormValidator(FormValidator)
call.- Returns:
- the
FormValidator
- See Also:
setFormValidator(FormValidator)
-
setFormValidator
public void setFormValidator(FormValidator formValidator)
Sets aFormValidator
for the the associated form. This method is intended to be called during a builder script. When the associated form is opened, theFormValidator
is automatically installed. If this method is called later (if the window is already open and the form exists), the specified inFormValidator
is directly passed to theForm
object.- Parameters:
formValidator
- theFormValidator
for the associatedForm
-
getFormBean
public Object getFormBean()
Returns the current form bean. This is a convenience method which obtains the form bean from theWindowBuilderData
object.- Returns:
- the current form bean
-
getForm
public Form getForm()
Returns the current form. This is a convenience method which obtains the form from theComponentBuilderData
object.- Returns:
- the current form
-
getWindow
public Window getWindow()
Returns the associated window. This is the window containing the form. It is obtained from theWindowBuilderData
object.- Returns:
- the associated window
-
getMessageOutput
public MessageOutput getMessageOutput()
Returns theMessageOutput
object to be used by this controller. This can be null if no specific object has been set.- Returns:
- the
MessageOutput
object - See Also:
setMessageOutput(MessageOutput)
-
setMessageOutput
public void setMessageOutput(MessageOutput messageOutput)
Sets theMessageOutput
object to be used by this controller. TheMessageOutput
object is used for displaying validation error messages to the user. Per default theMessageOutput
object defined in theBuilderData
object will be used (which is typically the application-global output object). With this method it is possible to set a specific output object for this controller.- Parameters:
messageOutput
- theMessageOutput
object to use- See Also:
fetchMessageOutput()
-
getValidationMessageFormat
public FormValidationMessageFormat getValidationMessageFormat()
Returns theFormValidationMessageFormat
object to be used by this controller. This can be null if no specific object has been set.- Returns:
- the
FormValidationMessageFormat
object - See Also:
setValidationMessageFormat(FormValidationMessageFormat)
-
setValidationMessageFormat
public void setValidationMessageFormat(FormValidationMessageFormat validationMessageFormat)
Sets theFormValidationMessageFormat
object to be used by this controller. This object is used for generating error messages for a failed validation that are to be displayed to the user. With this method it is possible to set a specific format object for this purpose. If no specific object is set, the application-global default format object is used (which is obtained from the currentBeanContext
).- Parameters:
validationMessageFormat
- theFormValidationMessageFormat
object to use- See Also:
fetchValidationMessageFormat()
-
getBtnOkName
public String getBtnOkName()
Returns the name of the component representing the OK button.- Returns:
- the name of the OK button
-
setBtnOkName
public void setBtnOkName(String btnOkName)
Sets the name of the component representing the OK button. This controller will register an action listener at this component for handling the commit operation accordingly.- Parameters:
btnOkName
- the name of the OK button component
-
getBtnCancelName
public String getBtnCancelName()
Returns the name of the component representing the cancel button.- Returns:
- the name of the cancel button
-
setBtnCancelName
public void setBtnCancelName(String btnCancelName)
Sets the name of the component representing the cancel button. This controller will register an action listener at this component for handling the cancel operation accordingly.- Parameters:
btnCancelName
- the name of the cancel button component
-
getValidationMessageBoxCaption
public String getValidationMessageBoxCaption()
Returns the caption of the message box for displaying validation error messages.- Returns:
- the caption of the validation error message box
-
setValidationMessageBoxCaption
public void setValidationMessageBoxCaption(String validationMessageBoxCaption)
Sets the caption of the message box for displaying validation error messages. If the user hits the OK button, the data entered by the user is validated. If this validation fails, a message box with the found validation problems is displayed. This property allows defining the caption of this message box. If no caption is set, a default caption is used (which is defined as a resource ID and resolved using the current resource manager).- Parameters:
validationMessageBoxCaption
- the caption of the validation error message box
-
getValidationTrigger
public FormValidationTrigger getValidationTrigger()
Returns theFormValidationTrigger
.- Returns:
- the validation trigger (can be null if none was set)
-
setValidationTrigger
public void setValidationTrigger(FormValidationTrigger validationTrigger)
Sets theFormValidationTrigger
. This object is called once in the initialization phase to give it opportunity to register itself as event listener.- Parameters:
validationTrigger
- the new validation trigger (can be null)
-
addValidationListener
public void addValidationListener(FormControllerValidationListener l)
Adds aFormControllerValidationListener
to this controller. The listener will be notified whenever a validation is performed.- Parameters:
l
- the listener to be added (must not be null)- Throws:
IllegalArgumentException
- if the event listener is null
-
removeValidationListener
public void removeValidationListener(FormControllerValidationListener l)
Removes the specifiedFormControllerValidationListener
from this controller. If the listener is not registered, this method has no effect.- Parameters:
l
- the listener to be removed
-
getValidationListeners
public FormControllerValidationListener[] getValidationListeners()
Returns an array with allFormControllerValidationListener
objects registered at thisFormController
.- Returns:
- an array with all registered
FormControllerValidationListener
objects
-
addFieldStatusListener
public void addFieldStatusListener(FormControllerFieldStatusListener l)
Adds aFormControllerFieldStatusListener
to this controller. The listener will be notified whenever the visited status of a field in the controller's form changes.- Parameters:
l
- the listener to be added (must not be null)- Throws:
IllegalArgumentException
- if the event listener is null
-
removeFieldStatusListener
public void removeFieldStatusListener(FormControllerFieldStatusListener l)
Removes the specifiedFormControllerFieldStatusListener
from this controller. If the listener is not registered, this method has no effect.- Parameters:
l
- the listener to be removed
-
getFieldStatusListeners
public FormControllerFieldStatusListener[] getFieldStatusListeners()
Returns an array with allFormControllerFieldStatusListener
objects registered at thisFormController
.- Returns:
- an array with all registered
FormControllerFieldStatusListener
objects
-
addFormListener
public void addFormListener(FormControllerFormListener l)
Adds aFormControllerFormListener
to this controller. The listener will be notified when the form associated with this controller is closed.- Parameters:
l
- the listener to be added (must not be null)- Throws:
IllegalArgumentException
- if the listener is null
-
removeFormListener
public void removeFormListener(FormControllerFormListener l)
Removes the specifiedFormControllerFormListener
from this controller. If the listener is not registered, this method has no effect.- Parameters:
l
- the listener to be removed
-
getFormListeners
public FormControllerFormListener[] getFormListeners()
Returns an array with allFormControllerFormListener
objects registered at thisFormController
.- Returns:
- an array with all registered
FormControllerFormListener
objects
-
getOkCommand
public Command getOkCommand()
Returns the command to be executed when the form is closed in reaction of the OK button.- Returns:
- the command to be executed after OK was clicked
-
setOkCommand
public void setOkCommand(Command okCommand)
Sets the command to be executed when the form is closed in reaction of the OK button. When the user commits a form often some actions have to be performed (e.g. saving some data in the database, triggering some other components, etc.). These actions can be implemented as a
object and associated with this controller. In its action handler for the OK event the controller will check (after a successful validation) whether a command was set. If this is the case, it will be passed to the current command queue.Command
- Parameters:
okCommand
- the command to be executed when the form is committed
-
getCancelCommand
public Command getCancelCommand()
Returns the command to be executed when the form is canceled.- Returns:
- the command to be executed after the cancel button was clicked
-
setCancelCommand
public void setCancelCommand(Command cancelCommand)
Sets the command to be executed when the form is canceled. This method is similar to
, but it allows to associate asetOkCommand(Command)
object with the cancel button (or any other close action that does not mean a commit). This way it is possible to execute some action when the user decides to throw away its input.Command
- Parameters:
cancelCommand
- the command to be executed when the form is canceled
-
validate
public FormValidatorResults validate()
Performs a validation of the associated form. After that theFormControllerValidationListener
objects registered at this controller will be notified.- Returns:
- a data object with information about the result of the validation
-
validateAndDisplayMessages
public FormValidatorResults validateAndDisplayMessages()
Performs a validation of the associated form and displays validation messages if this is not successful. This method delegates tovalidate()
. If validation results indicate errors, a message window is displayed containing corresponding validation error messages. This method is intended to do a validation in reaction on a user action, e.g. when the user clicks an apply button.- Returns:
- a data object with information about the result of the validation
- Since:
- 1.3.1
-
getLastValidationResults
public FormValidatorResults getLastValidationResults()
Returns the results of the last validation operation. The object returned by this method is the same as was returned by the lastvalidate()
call. This is useful for instance to determine which input fields are currently invalid. If no validation has been performed so far, a valid result object is returned.- Returns:
- a
FormValidatorResults
object with the last validation results
-
windowActivated
public void windowActivated(WindowEvent event)
Dummy implementation of this window event.- Specified by:
windowActivated
in interfaceWindowListener
- Parameters:
event
- the received event
-
windowClosed
public void windowClosed(WindowEvent event)
The associated window was closed. This implementation checks whether commands were registered for either the OK or the cancel button. If this is the case, the correct command is executed. Also, registeredFormControllerFormListener
objects are notified.- Specified by:
windowClosed
in interfaceWindowListener
- Parameters:
event
- the received event
-
windowDeactivated
public void windowDeactivated(WindowEvent event)
Dummy implementation of this window event.- Specified by:
windowDeactivated
in interfaceWindowListener
- Parameters:
event
- the received event
-
windowDeiconified
public void windowDeiconified(WindowEvent event)
Dummy implementation of this window event.- Specified by:
windowDeiconified
in interfaceWindowListener
- Parameters:
event
- the received event
-
windowIconified
public void windowIconified(WindowEvent event)
Dummy implementation of this window event.- Specified by:
windowIconified
in interfaceWindowListener
- Parameters:
event
- the received event
-
windowClosing
public void windowClosing(WindowEvent event)
Dummy implementation of this window event.- Specified by:
windowClosing
in interfaceWindowListener
- Parameters:
event
- the received event
-
windowOpened
public void windowOpened(WindowEvent event)
The window containing the associated form was opened. This is the main initialization method. The controller has to perform some setup here.- Specified by:
windowOpened
in interfaceWindowListener
- Parameters:
event
- the event- Throws:
IllegalStateException
- if a required field is missing
-
focusGained
public void focusGained(FormFocusEvent e)
A component of the associated window was given the focus.- Specified by:
focusGained
in interfaceFormFocusListener
- Parameters:
e
- the focus event
-
focusLost
public void focusLost(FormFocusEvent e)
A component of the associated window lost the focus. We track this event to mark the field as visited. This has an influence on validation. If the visited status for this field has changed, theFieldMarker
also needs to be notified.- Specified by:
focusLost
in interfaceFormFocusListener
- Parameters:
e
- the focus event
-
actionPerformed
public void actionPerformed(FormActionEvent e)
Processes action events. This method tests whether the event was caused by the OK or the cancel button. If this is the case, the corresponding processing method is called.- Specified by:
actionPerformed
in interfaceFormActionListener
- Parameters:
e
- the event- See Also:
okButtonClicked(FormActionEvent)
,cancelButtonClicked(FormActionEvent)
-
isFieldVisited
public boolean isFieldVisited(String name)
Tests whether the field with the given name has already been visited by the user.- Parameters:
name
- the name of the field- Returns:
- a flag whether this field has already been visited
-
getBuilderData
protected BuilderData getBuilderData()
Returns the currentBuilderData
object. This object can be used for gaining access to some application global objects and the complete configuration of the builder.- Returns:
- the
BuilderData
object
-
fetchMessageOutput
protected MessageOutput fetchMessageOutput()
Returns the currentMessageOutput
object. If an output object was set explicitly using thesetMessageOutput()
method, this object will be returned. Otherwise this method obtains theMessageOutput
object from the current
object.BuilderData
- Returns:
- the
MessageOutput
object to be used
-
fetchValidationMessageFormat
protected FormValidationMessageFormat fetchValidationMessageFormat()
Obtains theFormValidationMessageFormat
object to be used. If a format object was set explicitly using thesetValidationMessageFormat()
method, this object will be returned. Otherwise this method queries the currentBeanContext
for the default format object.- Returns:
- the
FormValidationMessageFormat
object to be used
-
fetchValidationMessageBoxCaption
protected String fetchValidationMessageBoxCaption()
Returns the caption for a message box for displaying validation error messages. This method checks whether such a caption was explicitly set (using thesetValidationMessageBoxCaption()
). If this is the case, it is returned. Otherwise the resource key for the default caption is resolved.- Returns:
- the caption for the message box for validation error messages
-
okButtonClicked
protected void okButtonClicked(FormActionEvent event)
The OK button was clicked. This method performs a validation. If this is successful, the form is closed. Otherwise an error message is created using theFormValidationMessageFormat
object and displayed to the user via the currentMessageOutput
object. When the user clicks OK, he or she indicates that all fields have been properly filled in; so they are marked as visited.- Parameters:
event
- the event object that triggered this method call
-
cancelButtonClicked
protected void cancelButtonClicked(FormActionEvent event)
The cancel button was clicked. This will cause the form to be closed without a validation.- Parameters:
event
- the event object that triggered this method call
-
closeForm
protected void closeForm()
Closes the associated form. This method is called by both the action handler of the OK and the cancel button when the form can be closed. It invokes theclose()
method on the associated window object.
-
isCommitted
protected boolean isCommitted()
Returns a flag whether the form was committed. This method can be used to find out whether the form was closed using the OK button (in this case the return value is true) or whether it was canceled. Of course, calling this method makes only sense after the form was closed. It is invoked by the handler for the window closed event to find out, which command object is to be executed (if any).- Returns:
- a flag whether the form was closed using the OK button
-
fireValidationEvent
protected void fireValidationEvent(FormValidatorResults results)
Notifies all registered validation listeners about a validation operation.- Parameters:
results
- the validation results
-
fireFieldStatusEvent
protected void fireFieldStatusEvent(String fieldName)
Notifies all registered field status listeners about a change in the status of a field.- Parameters:
fieldName
- the name of the affected field
-
fireFormEvent
protected void fireFormEvent()
Notifies all registered form listeners that the form has been closed.
-
-