Java Platform, Enterprise Edition (Java EE) 8 The Java EE Tutorial

## 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.

Copyright © 2017, Oracle and/or its affiliates. All rights reserved.