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.
- Author:
- Bauke Scholtz
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic final classFaces message builder.static interfaceThe message resolver allows the developers to change the way how messages are resolved. -
Method Summary
Modifier and TypeMethodDescriptionstatic voidadd(FacesMessage.Severity severity, String clientId, String message, Object... params) Add a faces message of the given severity to the given client ID, with the given message body which is formatted with the given parameters.static voidadd(String clientId, FacesMessage message) Add the given faces message to the given client ID.static voidAdd an ERROR faces message to the given client ID, with the given message body which is formatted with the given parameters.static voidAdd a FATAL faces message to the given client ID, with the given message body which is formatted with the given parameters.static voidaddFlash(FacesMessage.Severity severity, String clientId, String message, Object... params) Add a flash scoped faces message of the given severity to the given client ID, with the given message body which is formatted with the given parameters.static voidaddFlash(String clientId, FacesMessage message) Add a flash scoped faces message to the given client ID.static voidaddFlashError(String clientId, String message, Object... params) Add a flash scoped ERROR faces message to the given client ID, with the given message body which is formatted with the given parameters.static voidaddFlashFatal(String clientId, String message, Object... params) Add a flash scoped FATAL faces message to the given client ID, with the given message body which is formatted with the given parameters.static voidaddFlashGlobal(FacesMessage message) Add a flash scoped global faces message.static voidaddFlashGlobalError(String message, Object... params) Add a flash scoped global ERROR faces message, with the given message body which is formatted with the given parameters.static voidaddFlashGlobalFatal(String message, Object... params) Add a flash scoped global FATAL faces message, with the given message body which is formatted with the given parameters.static voidaddFlashGlobalInfo(String message, Object... params) Add a flash scoped global INFO faces message, with the given message body which is formatted with the given parameters.static voidaddFlashGlobalWarn(String message, Object... params) Add a flash scoped global WARN faces message, with the given message body which is formatted with the given parameters.static voidaddFlashInfo(String clientId, String message, Object... params) Add a flash scoped INFO faces message to the given client ID, with the given message body which is formatted with the given parameters.static voidaddFlashWarn(String clientId, String message, Object... params) Add a flash scoped WARN faces message to the given client ID, with the given message body which is formatted with the given parameters.static voidaddGlobal(FacesMessage message) Add a global faces message.static voidaddGlobal(FacesMessage.Severity severity, String message, Object... params) Add a global faces message of the given severity, with the given message body which is formatted with the given parameters.static voidaddGlobalError(String message, Object... params) Add a global ERROR faces message, with the given message body which is formatted with the given parameters.static voidaddGlobalFatal(String message, Object... params) Add a global FATAL faces message, with the given message body which is formatted with the given parameters.static voidaddGlobalInfo(String message, Object... params) Add a global INFO faces message, with the given message body which is formatted with the given parameters.static voidaddGlobalWarn(String message, Object... params) Add a global WARN faces message, with the given message body which is formatted with the given parameters.static voidAdd an INFO faces message to the given client ID, with the given message body which is formatted with the given parameters.static voidAdd a WARN faces message to the given client ID, with the given message body which is formatted with the given parameters.static ConverterExceptionasConverterException(String message, Object... params) Returns aConverterExceptionwith an ERROR faces message with the given message body which is formatted with the given parameters.static ValidatorExceptionasValidatorException(String message, Object... params) Returns aValidatorExceptionwith an ERROR faces message with the given message body which is formatted with the given parameters.static booleanclear(FacesMessage.Severity severity, String... clientIds) Clears faces messages of the given severity associated with the given client IDs.static booleanClears faces messages associated with the given client IDs.static booleanclearError(String... clientIds) Clears ERROR faces messages associated with the given client IDs.static booleanclearFatal(String... clientIds) Clears FATAL faces messages associated with the given client IDs.static booleanClears global faces messages of all severities.static booleanclearGlobal(FacesMessage.Severity severity) Clears global faces messages of given severity.static booleanClears global ERROR faces messages.static booleanClears global FATAL faces messages.static booleanClears global INFO faces messages.static booleanClears global WARN faces messages.static booleanClears INFO faces messages associated with the given client IDs.static booleanClears WARN faces messages associated with the given client IDs.static FacesMessagecreate(FacesMessage.Severity severity, String message, Object... params) Create a faces message of the given severity with the given message body which is formatted with the given parameters.static Messages.MessageCreate a faces message with the default INFO severity and the given message body which is formatted with the given parameters as summary message.static FacesMessagecreateError(String message, Object... params) Create an ERROR faces message with the given message body which is formatted with the given parameters.static FacesMessagecreateFatal(String message, Object... params) Create a FATAL faces message with the given message body which is formatted with the given parameters.static FacesMessagecreateInfo(String message, Object... params) Create an INFO faces message with the given message body which is formatted with the given parameters.static FacesMessagecreateWarn(String message, Object... params) Create a WARN faces message with the given message body which is formatted with the given parameters.static booleanisEmpty()Returnstrueif there are no faces messages, otherwisefalse.static booleanReturnstrueif there are no faces messages for the given client ID, otherwisefalse.static booleanReturnstrueif there are no global faces messages, otherwisefalse.static voidsetResolver(Messages.Resolver resolver) Set the custom message resolver.static voidthrowConverterException(String message, Object... params) Throw aConverterExceptionwith an ERROR faces message with the given message body which is formatted with the given parameters.static voidthrowValidatorException(String message, Object... params) Throw aValidatorExceptionwith an ERROR faces message with the given message body which is formatted with the given parameters.
-
Method Details
-
setResolver
Set the custom message resolver. It can be set only once. It's recommend to do it early during webapp's startup, for example with aServletContextListenerasWebListener, or aServletContainerInitializerin custom JAR, or aApplicationScopedbean, or an eagerly initializedStartupbean.- Parameters:
resolver- The custom message resolver.- Throws:
IllegalStateException- When the resolver has already been set.
-
create
Create a faces message with the default INFO severity and the given message body which is formatted with the given parameters as summary message. To set the detail message, useMessages.Message.detail(String, Object...). To change the default INFO severity, useMessages.Message.warn(),Messages.Message.error(), orMessages.Message.fatal(). To make it a flash message, useMessages.Message.flash(). To finally add it to the faces context, use eitherMessages.Message.add(String)to add it for a specific client ID, orMessages.Message.add()to add it as a global message.- Parameters:
message- The message body.params- The message format parameters, if any.- Returns:
- The
Messages.Messagebuilder. - Since:
- 1.1
- See Also:
-
create
Create a faces message of the given severity with the given message body which is formatted with the given parameters. Useful when a faces message is needed to construct aConverterExceptionor aValidatorException.- Parameters:
severity- The severity of the faces message.message- The message body.params- The message format parameters, if any.- Returns:
- A new faces message of the given severity with the given message body which is formatted with the given parameters.
- See Also:
-
createInfo
Create an INFO faces message with the given message body which is formatted with the given parameters.- Parameters:
message- The message body.params- The message format parameters, if any.- Returns:
- A new INFO faces message with the given message body which is formatted with the given parameters.
- See Also:
-
createWarn
Create a WARN faces message with the given message body which is formatted with the given parameters.- Parameters:
message- The message body.params- The message format parameters, if any.- Returns:
- A new WARN faces message with the given message body which is formatted with the given parameters.
- See Also:
-
createError
Create an ERROR faces message with the given message body which is formatted with the given parameters.- Parameters:
message- The message body.params- The message format parameters, if any.- Returns:
- A new ERROR faces message with the given message body which is formatted with the given parameters.
- See Also:
-
createFatal
Create a FATAL faces message with the given message body which is formatted with the given parameters.- Parameters:
message- The message body.params- The message format parameters, if any.- Returns:
- A new FATAL faces message with the given message body which is formatted with the given parameters.
- See Also:
-
asConverterException
Returns aConverterExceptionwith an ERROR faces message with the given message body which is formatted with the given parameters.- Parameters:
message- The message body.params- The message format parameters, if any.- Returns:
- ConverterException
- Since:
- 3.8
- See Also:
-
asValidatorException
Returns aValidatorExceptionwith an ERROR faces message with the given message body which is formatted with the given parameters.- Parameters:
message- The message body.params- The message format parameters, if any.- Returns:
- ValidatorException
- Since:
- 3.8
- See Also:
-
throwConverterException
Throw aConverterExceptionwith an ERROR faces message with the given message body which is formatted with the given parameters.- Parameters:
message- The message body.params- The message format parameters, if any.- Throws:
ConverterException- The so far built message as aConverterException.- Since:
- 3.5
- See Also:
-
throwValidatorException
Throw aValidatorExceptionwith an ERROR faces message with the given message body which is formatted with the given parameters.- Parameters:
message- The message body.params- The message format parameters, if any.- Throws:
ValidatorException- The so far built message as aValidatorException.- Since:
- 3.5
- See Also:
-
add
Add the given faces message to the given client ID. When the client ID isnull, it becomes a global faces message. This can be filtered in a<h:messages globalOnly="true">.- Parameters:
clientId- The client ID to add the faces message for.message- The faces message.- See Also:
-
add
public static void add(FacesMessage.Severity severity, String clientId, String message, Object... params) Add a faces message of the given severity to the given client ID, with the given message body which is formatted with the given parameters.- Parameters:
clientId- The client ID to add the faces message for.severity- The severity of the faces message.message- The message body.params- The message format parameters, if any.- See Also:
-
addInfo
Add an INFO faces message to the given client ID, with the given message body which is formatted with the given parameters.- Parameters:
clientId- The client ID to add the faces message for.message- The message body.params- The message format parameters, if any.- See Also:
-
addWarn
Add a WARN faces message to the given client ID, with the given message body which is formatted with the given parameters.- Parameters:
clientId- The client ID to add the faces message for.message- The message body.params- The message format parameters, if any.- See Also:
-
addError
Add an ERROR faces message to the given client ID, with the given message body which is formatted with the given parameters.- Parameters:
clientId- The client ID to add the faces message for.message- The message body.params- The message format parameters, if any.- See Also:
-
addFatal
Add a FATAL faces message to the given client ID, with the given message body which is formatted with the given parameters.- Parameters:
clientId- The client ID to add the faces message for.message- The message body.params- The message format parameters, if any.- See Also:
-
addGlobal
Add a global faces message. This adds a faces message to a client ID ofnull.- Parameters:
message- The global faces message.- See Also:
-
addGlobal
Add a global faces message of the given severity, with the given message body which is formatted with the given parameters.- Parameters:
severity- The severity of the global faces message.message- The message body.params- The message format parameters, if any.- See Also:
-
addGlobalInfo
Add a global INFO faces message, with the given message body which is formatted with the given parameters.- Parameters:
message- The message body.params- The message format parameters, if any.- See Also:
-
addGlobalWarn
Add a global WARN faces message, with the given message body which is formatted with the given parameters.- Parameters:
message- The message body.params- The message format parameters, if any.- See Also:
-
addGlobalError
Add a global ERROR faces message, with the given message body which is formatted with the given parameters.- Parameters:
message- The message body.params- The message format parameters, if any.- See Also:
-
addGlobalFatal
Add a global FATAL faces message, with the given message body which is formatted with the given parameters.- Parameters:
message- The message body.params- The message format parameters, if any.- See Also:
-
addFlash
Add a flash scoped faces message to the given client ID. Use this when you need to display the message after a redirect.NOTE: the flash scope has in early Mojarra versions however some pretty peculiar problems. In older versions, the messages are remembered too long, or they are only displayed after refresh, or they are not displayed when the next request is on a different path. Only since Mojarra 2.1.14, all known flash scope problems are solved.
- Parameters:
clientId- The client ID to add the flash scoped faces message for.message- The faces message.- See Also:
-
addFlash
public static void addFlash(FacesMessage.Severity severity, String clientId, String message, Object... params) Add a flash scoped faces message of the given severity to the given client ID, with the given message body which is formatted with the given parameters. Use this when you need to display the message after a redirect.- Parameters:
clientId- The client ID to add the faces message for.severity- The severity of the faces message.message- The message body.params- The message format parameters, if any.- See Also:
-
addFlashInfo
Add a flash scoped INFO faces message to the given client ID, with the given message body which is formatted with the given parameters. Use this when you need to display the message after a redirect.- Parameters:
clientId- The client ID to add the faces message for.message- The message body.params- The message format parameters, if any.- See Also:
-
addFlashWarn
Add a flash scoped WARN faces message to the given client ID, with the given message body which is formatted with the given parameters. Use this when you need to display the message after a redirect.- Parameters:
clientId- The client ID to add the faces message for.message- The message body.params- The message format parameters, if any.- See Also:
-
addFlashError
Add a flash scoped ERROR faces message to the given client ID, with the given message body which is formatted with the given parameters. Use this when you need to display the message after a redirect.- Parameters:
clientId- The client ID to add the faces message for.message- The message body.params- The message format parameters, if any.- See Also:
-
addFlashFatal
Add a flash scoped FATAL faces message to the given client ID, with the given message body which is formatted with the given parameters. Use this when you need to display the message after a redirect.- Parameters:
clientId- The client ID to add the faces message for.message- The message body.params- The message format parameters, if any.- See Also:
-
addFlashGlobal
Add a flash scoped global faces message. This adds a faces message to a client ID ofnull. Use this when you need to display the message after a redirect.- Parameters:
message- The global faces message.- See Also:
-
addFlashGlobalInfo
Add a flash scoped global INFO faces message, with the given message body which is formatted with the given parameters. Use this when you need to display the message after a redirect.- Parameters:
message- The message body.params- The message format parameters, if any.- See Also:
-
addFlashGlobalWarn
Add a flash scoped global WARN faces message, with the given message body which is formatted with the given parameters. Use this when you need to display the message after a redirect.- Parameters:
message- The message body.params- The message format parameters, if any.- See Also:
-
addFlashGlobalError
Add a flash scoped global ERROR faces message, with the given message body which is formatted with the given parameters. Use this when you need to display the message after a redirect.- Parameters:
message- The message body.params- The message format parameters, if any.- See Also:
-
addFlashGlobalFatal
Add a flash scoped global FATAL faces message, with the given message body which is formatted with the given parameters. Use this when you need to display the message after a redirect.- Parameters:
message- The message body.params- The message format parameters, if any.- See Also:
-
isEmpty
public static boolean isEmpty()Returnstrueif there are no faces messages, otherwisefalse.- Returns:
trueif there are no faces messages, otherwisefalse.- Since:
- 2.2
- See Also:
-
isEmpty
Returnstrueif there are no faces messages for the given client ID, otherwisefalse.- Parameters:
clientId- The client ID to check the messages for.- Returns:
trueif there are no faces messages for the given client ID, otherwisefalse.- Since:
- 2.2
- See Also:
-
isGlobalEmpty
public static boolean isGlobalEmpty()Returnstrueif there are no global faces messages, otherwisefalse.- Returns:
trueif there are no global faces messages, otherwisefalse.- Since:
- 2.2
- See Also:
-
clear
Clears faces messages of the given severity associated with the given client IDs.- Parameters:
severity- The severity to clear faces message for. If this is null, then all severities are matched.clientIds- The client IDs to clear faces messages for. If this is null or empty, then all faces messages are cleared. If this contains null, then all global faces messages are cleared.- Returns:
trueif at least one faces message of the given severity associated with the given client IDs was cleared.- Since:
- 3.5
- See Also:
-
clear
Clears faces messages associated with the given client IDs.- Parameters:
clientIds- The client IDs to clear faces messages for. If this is empty, then all faces messages are cleared. If this contains null, then all global faces messages are cleared.- Returns:
trueif at least one faces message associated with the given client IDs was cleared.- Since:
- 3.5
- See Also:
-
clearInfo
Clears INFO faces messages associated with the given client IDs.- Parameters:
clientIds- The client IDs to clear INFO faces messages for. If this is empty, then all INFO faces messages are cleared. If this contains null, then all global INFO faces messages are cleared.- Returns:
trueif at least one INFO faces message associated with the given client IDs was cleared.- Since:
- 3.5
- See Also:
-
clearWarn
Clears WARN faces messages associated with the given client IDs.- Parameters:
clientIds- The client IDs to clear WARN faces messages for. If this is empty, then all WARN faces messages are cleared. If this contains null, then all global WARN faces messages are cleared.- Returns:
trueif at least one WARN faces message associated with the given client IDs was cleared.- Since:
- 3.5
- See Also:
-
clearError
Clears ERROR faces messages associated with the given client IDs.- Parameters:
clientIds- The client IDs to clear ERROR faces messages for. If this is empty, then all ERROR faces messages are cleared. If this contains null, then all global ERROR faces messages are cleared.- Returns:
trueif at least one ERROR faces message associated with the given client IDs was cleared.- Since:
- 3.5
- See Also:
-
clearFatal
Clears FATAL faces messages associated with the given client IDs.- Parameters:
clientIds- The client IDs to clear FATAL faces messages for. If this is empty, then all FATAL face messages are cleared. If this contains null, then all global FATAL faces messages are cleared.- Returns:
trueif at least one FATAL faces message associated with the given client IDs was cleared.- Since:
- 3.5
- See Also:
-
clearGlobal
Clears global faces messages of given severity.- Parameters:
severity- The severity of the faces message. If this is null, then all severities are matched.- Returns:
trueif at least one global faces message of given severity was cleared.- Since:
- 3.5
- See Also:
-
clearGlobal
public static boolean clearGlobal()Clears global faces messages of all severities.- Returns:
trueif at least one global faces message was cleared.- Since:
- 3.5
- See Also:
-
clearGlobalInfo
public static boolean clearGlobalInfo()Clears global INFO faces messages.- Returns:
trueif at least one global INFO faces message was cleared.- Since:
- 3.5
- See Also:
-
clearGlobalWarn
public static boolean clearGlobalWarn()Clears global WARN faces messages.- Returns:
trueif at least one global WARN faces message was cleared.- Since:
- 3.5
- See Also:
-
clearGlobalError
public static boolean clearGlobalError()Clears global ERROR faces messages.- Returns:
trueif at least one global ERROR faces message was cleared.- Since:
- 3.5
- See Also:
-
clearGlobalFatal
public static boolean clearGlobalFatal()Clears global FATAL faces messages.- Returns:
trueif at least one global FATAL faces message was cleared.- Since:
- 3.5
- See Also:
-