FormValidationMessageFormat (JGUIraffe BOM 1.3.1 API)

java.lang.Object
- net.sf.jguiraffe.gui.forms.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:

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.
Then the single validation messages available for this field are processed. To each error message the fieldErrorTemplate template is applied.
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.
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

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`DEF_ERRORS_TEMPLATE` Constant for the default field errors template.
`static String`	`VAR_FIELD` Constant for the field variable.
`static String`	`VAR_MSG` Constant for the msg variable.
`static String`	`VAR_MSG_COUNT` Constant for the msgCount variable.
`static String`	`VAR_MSG_INDEX` Constant for the msgIndex variable.

Constructor Summary

Constructors
Constructor and Description

FormValidationMessageFormat()
Creates a new instance of FormValidationMessageFormat.

Constructors
Constructor and Description
`FormValidationMessageFormat()` Creates a new instance of `FormValidationMessageFormat`.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`protected String`	`fetchDisplayName(Form form, String field)` Determines the display name of the given field.
`String`	`format(FormValidatorResults res, Form form)` The main formatting method.
`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.
`String`	`getFieldErrorTemplate()` Returns the template for the error messages of an input field.
`String`	`getFieldFooterTemplate()` Returns the template for the footer of a field.
`String`	`getFieldHeaderTemplate()` Returns the template for the header of a field.
`String`	`getFieldWarningTemplate()` Returns the template for the warning messages of an input field.
`boolean`	`isSuppressWarnings()` Returns a flag whether warning messages should be suppressed.
`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.
`void`	`setFieldErrorTemplate(String fieldErrorTemplate)` Sets the template for the error messages of an input field.
`void`	`setFieldFooterTemplate(String fieldFooterTemplate)` Sets the template for the footer of a field.
`void`	`setFieldHeaderTemplate(String fieldHeaderTemplate)` Sets the template for the header of a field.
`void`	`setFieldWarningTemplate(String fieldWarningTemplate)` Sets the template for the warning messages of an input field.
`void`	`setSuppressWarnings(boolean suppressWarnings)` Sets a flag whether warning messages should be suppressed.
`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.
`protected void`	`setUpVariablesForMessage(Map<String,String> vars, FormValidatorResults res, Form form, String field, String msg, int index)` Initializes the variables for an error message.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - DEF_ERRORS_TEMPLATE
```
public static final String DEF_ERRORS_TEMPLATE
```
    Constant for the default field errors template.
    
    See Also:
    
    Constant Field Values
  - VAR_FIELD
```
public static final String VAR_FIELD
```
    Constant for the field variable.
    
    See Also:
    
    Constant Field Values
  - VAR_MSG
```
public static final String VAR_MSG
```
    Constant for the msg variable.
    
    See Also:
    
    Constant Field Values
  - VAR_MSG_COUNT
```
public static final String VAR_MSG_COUNT
```
    Constant for the msgCount variable.
    
    See Also:
    
    Constant Field Values
  - VAR_MSG_INDEX
```
public static final String VAR_MSG_INDEX
```
    Constant for the msgIndex variable.
    
    See Also:
    
    Constant Field Values
- 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

Class FormValidationMessageFormat

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEF_ERRORS_TEMPLATE

VAR_FIELD

VAR_MSG

VAR_MSG_COUNT

VAR_MSG_INDEX

Constructor Detail

FormValidationMessageFormat

Method Detail

getFieldHeaderTemplate

setFieldHeaderTemplate

getFieldFooterTemplate

setFieldFooterTemplate

getFieldErrorTemplate

setFieldErrorTemplate

getFieldWarningTemplate

setFieldWarningTemplate

isSuppressWarnings

setSuppressWarnings

format

formatField

setUpVariablesForField

setUpVariablesForMessage

processMessages

fetchDisplayName