Class 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. A FieldMarker 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 Detail

      • FormController

        public FormController()
        Creates a new instance of FormController.
    • Method Detail

      • getComponentBuilderData

        public ComponentBuilderData getComponentBuilderData()
        Returns the ComponentBuilderData object.
        Returns:
        the object with information about all components that belong to the current form
      • setComponentBuilderData

        public void setComponentBuilderData​(ComponentBuilderData componentBuilderData)
        Sets the ComponentBuilderData 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 the WindowBuilderData object.
        Returns:
        the data object with information about the current window
      • setWindowBuilderData

        public void setWindowBuilderData​(WindowBuilderData windowBuilderData)
        Sets the WindowBuilderData 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
      • setFormValidator

        public void setFormValidator​(FormValidator formValidator)
        Sets a FormValidator for the the associated form. This method is intended to be called during a builder script. When the associated form is opened, the FormValidator is automatically installed. If this method is called later (if the window is already open and the form exists), the specified in FormValidator is directly passed to the Form object.
        Parameters:
        formValidator - the FormValidator for the associated Form
      • getFormBean

        public Object getFormBean()
        Returns the current form bean. This is a convenience method which obtains the form bean from the WindowBuilderData object.
        Returns:
        the current form bean
      • getForm

        public Form getForm()
        Returns the current form. This is a convenience method which obtains the form from the ComponentBuilderData object.
        Returns:
        the current form
      • getWindow

        public Window getWindow()
        Returns the associated window. This is the window containing the form. It is obtained from the WindowBuilderData object.
        Returns:
        the associated window
      • getMessageOutput

        public MessageOutput getMessageOutput()
        Returns the MessageOutput 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 the MessageOutput object to be used by this controller. The MessageOutput object is used for displaying validation error messages to the user. Per default the MessageOutput object defined in the BuilderData 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 - the MessageOutput object to use
        See Also:
        fetchMessageOutput()
      • setValidationMessageFormat

        public void setValidationMessageFormat​(FormValidationMessageFormat validationMessageFormat)
        Sets the FormValidationMessageFormat 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 current BeanContext).
        Parameters:
        validationMessageFormat - the FormValidationMessageFormat 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 the FormValidationTrigger.
        Returns:
        the validation trigger (can be null if none was set)
      • setValidationTrigger

        public void setValidationTrigger​(FormValidationTrigger validationTrigger)
        Sets the FormValidationTrigger. 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 a FormControllerValidationListener 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 specified FormControllerValidationListener 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 all FormControllerValidationListener objects registered at this FormController.
        Returns:
        an array with all registered FormControllerValidationListener objects
      • addFieldStatusListener

        public void addFieldStatusListener​(FormControllerFieldStatusListener l)
        Adds a FormControllerFieldStatusListener 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 specified FormControllerFieldStatusListener 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 all FormControllerFieldStatusListener objects registered at this FormController.
        Returns:
        an array with all registered FormControllerFieldStatusListener objects
      • addFormListener

        public void addFormListener​(FormControllerFormListener l)
        Adds a FormControllerFormListener 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 specified FormControllerFormListener 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 all FormControllerFormListener objects registered at this FormController.
        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 Command 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.
        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 setOkCommand(Command), but it allows to associate a 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.
        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 the FormControllerValidationListener 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 to validate(). 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 last validate() 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 interface WindowListener
        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, registered FormControllerFormListener objects are notified.
        Specified by:
        windowClosed in interface WindowListener
        Parameters:
        event - the received event
      • windowDeactivated

        public void windowDeactivated​(WindowEvent event)
        Dummy implementation of this window event.
        Specified by:
        windowDeactivated in interface WindowListener
        Parameters:
        event - the received event
      • windowDeiconified

        public void windowDeiconified​(WindowEvent event)
        Dummy implementation of this window event.
        Specified by:
        windowDeiconified in interface WindowListener
        Parameters:
        event - the received event
      • windowIconified

        public void windowIconified​(WindowEvent event)
        Dummy implementation of this window event.
        Specified by:
        windowIconified in interface WindowListener
        Parameters:
        event - the received event
      • windowClosing

        public void windowClosing​(WindowEvent event)
        Dummy implementation of this window event.
        Specified by:
        windowClosing in interface WindowListener
        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 interface WindowListener
        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 interface FormFocusListener
        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, the FieldMarker also needs to be notified.
        Specified by:
        focusLost in interface FormFocusListener
        Parameters:
        e - the focus event
      • 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 current BuilderData 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 current MessageOutput object. If an output object was set explicitly using the setMessageOutput() method, this object will be returned. Otherwise this method obtains the MessageOutput object from the current BuilderData object.
        Returns:
        the MessageOutput object to be used
      • fetchValidationMessageFormat

        protected FormValidationMessageFormat fetchValidationMessageFormat()
        Obtains the FormValidationMessageFormat object to be used. If a format object was set explicitly using the setValidationMessageFormat() method, this object will be returned. Otherwise this method queries the current BeanContext 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 the setValidationMessageBoxCaption()). 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 the FormValidationMessageFormat object and displayed to the user via the current MessageOutput 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 the close() 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.