Registering Application Messages

Application messages can include any strings displayed to the user as well as custom error messages (which are displayed by the message and messages tags) for your custom converters or validators. To make messages available at application startup time, do one of the following:

Queue an individual message onto the javax.faces.context.FacesContext instance programmatically, as described in Using FacesMessage to Create a Message
Register all the messages with your application using the application configuration resource file

Here is the section of the faces-config.xml file that registers the messages for the Duke’s Bookstore case study application:

<application>
    <resource-bundle>
        <base-name>
            javaeetutorial.dukesbookstore.web.messages.Messages
        </base-name>
        <var>bundle</var>
    </resource-bundle>
    <locale-config>
        <default-locale>en</default-locale>
        <supported-locale>es</supported-locale>
        <supported-locale>de</supported-locale>
        <supported-locale>fr</supported-locale>
    </locale-config>
</application>

This set of elements causes the application to be populated with the messages that are contained in the specified resource bundle.

The resource-bundle element represents a set of localized messages. It must contain the fully qualified path to the resource bundle containing the localized messages (in this case, dukesbookstore.web.messages.Messages). The var element defines the EL name by which page authors refer to the resource bundle.

The locale-config element lists the default locale and the other supported locales. The locale-config element enables the system to find the correct locale based on the browser’s language settings.

The supported-locale and default-locale tags accept the lowercase, two-character codes defined by ISO 639-1 (see http://www.loc.gov/standards/iso639-2/php/English_list.php). Make sure that your resource bundle actually contains the messages for the locales you specify with these tags.

To access the localized message, the application developer merely references the key of the message from the resource bundle.

You can pull localized text into an alt tag for a graphic image, as in the following example:

<h:graphicImage id="mapImage"
                name="book_all.jpg"
                library="images"
                alt="#{bundle.ChooseBook}"
                usemap="#bookMap" />

The alt attribute can accept value expressions. In this case, the alt attribute refers to localized text that will be included in the alternative text of the image rendered by this tag.

Using FacesMessage to Create a Message

Instead of registering messages in the application configuration resource file, you can access the java.util.ResourceBundle directly from managed bean code. The code snippet below locates an email error message:

String message = "";
...
message = ExampleBean.loadErrorMessage(context,
    ExampleBean.EX_RESOURCE_BUNDLE_NAME,
         "EMailError");
context.addMessage(toValidate.getClientId(context),
    new FacesMessage(message));

These lines call the bean’s loadErrorMessage method to get the message from the ResourceBundle. Here is the loadErrorMessage method:

public static String loadErrorMessage(FacesContext context,
     String basename, String key) {
    if ( bundle == null ) {
         try {
            bundle = ResourceBundle.getBundle(basename,
                 context.getViewRoot().getLocale());
        } catch (Exception e) {
            return null;
        }
    }
    return bundle.getString(key);
}

Referencing Error Messages

A JavaServer Faces page uses the message or messages tags to access error messages, as explained in Displaying Error Messages with the h:message and h:messages Tags.

The error messages these tags access include

The standard error messages that accompany the standard converters and validators that ship with the API. (see Section 2.5.2.4 of the JavaServer Faces specification for a complete list of standard error messages)
Custom error messages contained in resource bundles registered with the application by the application architect using the resource-bundle element in the configuration file

When a converter or validator is registered on an input component, the appropriate error message is automatically queued on the component.

A page author can override the error messages queued on a component by using the following attributes of the component’s tag:

converterMessage: References the error message to display when the data on the enclosing component cannot be converted by the converter registered on this component.
requiredMessage: References the error message to display when no value has been entered into the enclosing component.
validatorMessage: References the error message to display when the data on the enclosing component cannot be validated by the validator registered on this component.

All three attributes are enabled to take literal values and value expressions. If an attribute uses a value expression, this expression references the error message in a resource bundle. This resource bundle must be made available to the application in one of the following ways:

By the application architect using the resource-bundle element in the configuration file
By the page author using the f:loadBundle tag

Conversely, the resource-bundle element must be used to make available to the application those resource bundles containing custom error messages that are queued on the component as a result of a custom converter or validator being registered on the component.

The following tags show how to specify the requiredMessage attribute using a value expression to reference an error message:

<h:inputText id="ccno" size="19"
    required="true"
    requiredMessage="#{customMessages.ReqMessage}">
    ...
</h:inputText>
<h:message styleClass="error-message" for="ccno"/>

The value expression used by requiredMessage in this example references the error message with the ReqMessage key in the resource bundle customMessages.

This message replaces the corresponding message queued on the component and will display wherever the message or messages tag is placed on the page.