- 

Available since OmniFaces 1.0

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

Usage

Here are 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";

For a full list, check the method summary.

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

MessagesLocal

Note that there's normally a minor overhead in obtaining the thread local FacesContext. In case client code needs to call methods in this class multiple times it's expected that performance will be slightly better if instead the FacesContext is obtained once and the required methods are called on that, although the difference is practically negligible when used in modern server hardware.

In such case, consider using MessagesLocal instead. The difference with Messages is that no one method of MessagesLocal obtains the FacesContext from the current thread by FacesContext.getCurrentInstance(). This job is up to the caller.

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