- 

Available since OmniFaces 1.0

Collection of utility methods for the Faces API with respect to working with FacesMessage.

Usage

Some examples:

// In a validator.
Messages.throwValidatorException("Invalid input.");
// In a converter.
throw Messages.asConverterException("Unknown input.");
// In a validator, as extra message on another component.
Messages.addError("someFormId:someInputId", "This is also invalid.");
// In a managed bean action method.
Messages.addGlobalError("Unknown login, please try again.");
// In a managed bean action method which uses Post-Redirect-Get.
Messages.addFlashGlobalInfo("New item with id {0} is successfully added.", item.getId());
return "items?faces-redirect=true";

There is also a builder which also allows you to set the message detail. Some examples:

// In a validator.
Messages.create("Invalid input.").detail("Value {0} is not expected.", value).throwValidatorException();
// In a validator, as extra message on another component.
Messages.create("This is also invalid.").error().add("someFormId:someInputId");
// In a managed bean action method.
Messages.create("Unknown login, please try again.").error().add();
// In a managed bean action method which uses Post-Redirect-Get.
Messages.create("New item with id {0} is successfully added.", item.getId()).flash().add();
return "items?faces-redirect=true";

Message resolver

It also offers the possibility to set a custom message resolver so that you can control the way how messages are been resolved. You can for example supply an implementation wherein the message is been treated as for example a resource bundle key. Here's an example:

Messages.setResolver(new Messages.Resolver() {
    private static final String BASE_NAME = "com.example.i18n.messages";
    public String getMessage(String message, Object... params) {
        ResourceBundle bundle = ResourceBundle.getBundle(BASE_NAME, Faces.getLocale());
        if (bundle.containsKey(message)) {
            message = bundle.getString(message);
        }
        return params.length > 0 ? MessageFormat.format(message, params) : message;
    }
});

There is already a default resolver which just delegates the message and the parameters straight to MessageFormat.format(String, Object...). Note that the resolver can be set only once. It's recommend to do it early during webapp's startup, for example with a ServletContextListener as WebListener, or a ServletContainerInitializer in custom JAR, or a ApplicationScoped bean, or an eagerly initialized Startup bean.

Design notice

Note that all of those shortcut methods by design only sets the message summary and ignores the message detail (it is not possible to offer varargs to parameterize both the summary and the detail). The message summary is exactly the information which is by default displayed in the <h:message(s)>, while the detail is by default only displayed when you explicitly set the showDetail="true" attribute.

To create a FacesMessage with a message detail as well, use the Messages.Message builder as you can obtain by create(String, Object...).

Feature request

If you know more useful methods/functions which you think should be added to this OmniFaces utility class so that everyone can benefit from a "standard" Faces utility library, feel free to post a feature request.

Documentation & Sources

API documentation

Java source code