Class FormValidationMessageFormat


  • public class FormValidationMessageFormat
    extends Object

    A class for converting a FormValidatorResults object to text.

    If validation of a form fails, usually the corresponding error messages have to be displayed somehow to the user. This class takes a FormValidationResults object as input, iterates over the contained validation error messages and converts them to text. The result is a string that can be displayed in a message box for instance.

    The class can be configured with a number of template strings for specifying the desired output. There are four template strings that are evaluated:

    1. The class iterates over all fields in the passed in FormValidatorResults object, for which error messages are found. Whenever a new field starts the fieldHeaderTemplate is issued.
    2. Then the single validation messages available for this field are processed. To each error message the fieldErrorTemplate template is applied.
    3. After the error messages the warning messages (if available) are processed. To each warning message the fieldWarningTemplate template is applied. If the fieldWarningTemplate is not defined, the fieldErrorTemplate is used instead. The output of warning messages can be suppressed at all by setting the suppressWarnings property to true.
    4. Finally, the fieldFooterTemplate template is output.

    Templates are strings that can contain variables for the name of the current field and the current error message. When processing the templates the variables are replaced with their current values resulting in the text to be displayed. For variables the syntax ${...} is used, which should be familiar from Ant. The following table lists the supported variables:

    Variable Description
    field Will be replaced by the name of the current field. This variable is allowed in all templates.
    msgCount Will be replaced by the number of error messages for the current field. This could for instance be used in the header template to give an overview over the number of errors detected for the current input field.
    msg Will be replaced by the current error message. This variable is only supported by the fieldErrorTemplate template.
    msgIndex Will be replaced by the index of the current error message. The messages of a field are numbered from 1 up to ${msgCount}. With this variable the index can be added to the resulting text.

    The default initialization leaves the header and footer template empty and sets the following error template: ${field}: ${msg}\n. This results in output like

     Field1: Message1 for Field1
     Field2: Message1 for Field2
     Field2: Message2 for Field2
     Field3: Message1 for Field3
     
    By carefully designing the templates, more complex output can be generated as in the following example:
    • fieldHeaderTemplate = ${field} ${msgCount} error(s):\n
    • fieldErrorTemplate = - ${msg}
    • fieldFooterTemplate = \n
    In this example the output will look like the following:
     Field1 1 error(s):
     - Message1 for Field1
     Field2 2 error(s):
     - Message1 for Field2
     - Message2 for Field2
     
    Templates that are null will be ignored.

    Implementation note: This class has a mutable state and thus is not thread-safe. However if it is initialized once and the templates are not changed later, it can be shared between multiple threads.

    Version:
    $Id: FormValidationMessageFormat.java 205 2012-01-29 18:29:57Z oheger $
    Author:
    Oliver Heger
    • Constructor Detail

      • FormValidationMessageFormat

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

      • getFieldHeaderTemplate

        public String getFieldHeaderTemplate()
        Returns the template for the header of a field.
        Returns:
        the field header template
      • setFieldHeaderTemplate

        public void setFieldHeaderTemplate​(String fieldHeaderTemplate)
        Sets the template for the header of a field. This template will be processed at the beginning of a new input field with validation error messages.
        Parameters:
        fieldHeaderTemplate - the template for the header of a field
      • getFieldFooterTemplate

        public String getFieldFooterTemplate()
        Returns the template for the footer of a field.
        Returns:
        the field footer template
      • setFieldFooterTemplate

        public void setFieldFooterTemplate​(String fieldFooterTemplate)
        Sets the template for the footer of a field. This template will be processed after the error messages of an input field have been output.
        Parameters:
        fieldFooterTemplate - the template for the footer of a field
      • getFieldErrorTemplate

        public String getFieldErrorTemplate()
        Returns the template for the error messages of an input field.
        Returns:
        the error messages template
      • setFieldErrorTemplate

        public void setFieldErrorTemplate​(String fieldErrorTemplate)
        Sets the template for the error messages of an input field. For each validation error message associated with an input field this template will be processed.
        Parameters:
        fieldErrorTemplate - the field error template
      • getFieldWarningTemplate

        public String getFieldWarningTemplate()
        Returns the template for the warning messages of an input field.
        Returns:
        the warning messages template
      • setFieldWarningTemplate

        public void setFieldWarningTemplate​(String fieldWarningTemplate)
        Sets the template for the warning messages of an input field. For each validation warning message associated with an input field this template will be processed. Warning messages are only processed if the suppressWarnings property is not set. If suppressWarnings is false and no specific template for warning messages is set, the error template is used.
        Parameters:
        fieldWarningTemplate - the field warnings template
      • isSuppressWarnings

        public boolean isSuppressWarnings()
        Returns a flag whether warning messages should be suppressed.
        Returns:
        the suppress warnings flag
      • setSuppressWarnings

        public void setSuppressWarnings​(boolean suppressWarnings)
        Sets a flag whether warning messages should be suppressed. If this message is called with the parameter true, the output generated by this object contains only error messages.
        Parameters:
        suppressWarnings - the suppress warnings flag
      • format

        public String format​(FormValidatorResults res,
                             Form form)
        The main formatting method. Transforms the passed in validation result object into a text according to the values of the current templates.
        Parameters:
        res - the object with the validation results (can be null, then the result of this method is null)
        form - the current Form object; this object is used for obtaining the display names of the error fields; it can be null, then the field names are used
        Returns:
        the corresponding text
      • formatField

        public String formatField​(FormValidatorResults res,
                                  Form form,
                                  String field)
        Transforms all validation messages found in the passed FormValidatorResults object for the given field name into a text according to the values of the current templates. This method can be called to process the messages of a single field only.
        Parameters:
        res - the object with the validation results (can be null, then the result of this method is null)
        form - the current Form object; this object is used for obtaining the display names of the error fields; it can be null, then the field names are used
        field - the name of the field in question (if this field cannot be found, result is an empty string)
        Returns:
        the corresponding text
      • setUpVariablesForField

        protected void setUpVariablesForField​(Map<String,​String> vars,
                                              FormValidatorResults res,
                                              Form form,
                                              String field)
        Initializes the variables for the specified field of the validation results object. This method is invoked at the beginning of the processing of a new field.
        Parameters:
        vars - the map with the variables
        res - the results object
        form - the form object (may be null)
        field - the name of the current field
      • setUpVariablesForMessage

        protected void setUpVariablesForMessage​(Map<String,​String> vars,
                                                FormValidatorResults res,
                                                Form form,
                                                String field,
                                                String msg,
                                                int index)
        Initializes the variables for an error message. This method is invoked for each error message of a field. The passed in parameters represent the information available for the current error message. The variables for the field have already been initialized ( setUpVariablesForField() has already been called).
        Parameters:
        vars - the map with the variables
        res - the results object
        form - the form object (may be null)
        field - the name of the current field
        msg - the current validation error message
        index - the index of this message
      • processMessages

        protected void processMessages​(StringBuilder buf,
                                       org.apache.commons.lang.text.StrSubstitutor subst,
                                       FormValidatorResults res,
                                       Form form,
                                       String field,
                                       Map<String,​String> variables)
        Applies the template for the error messages to all messages available for the current field.
        Parameters:
        buf - the target buffer
        subst - the substitutor
        res - the validation results
        form - the form
        field - the current field
        variables - the map with the variables
      • fetchDisplayName

        protected String fetchDisplayName​(Form form,
                                          String field)
        Determines the display name of the given field. If a Form object is provided, it is used for resolving the display name. Otherwise the field name is returned.
        Parameters:
        form - the form
        field - the field name
        Returns:
        the display name