public final class Messages extends Object
Collection of utility methods for the JSF API with respect to working with FacesMessage
.
Some examples:
// In a validator. Messages.throwValidatorException("Invalid 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";
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.
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...)
.
Modifier and Type | Class and Description |
---|---|
static class |
Messages.Message
Faces message builder.
|
static interface |
Messages.Resolver
The message resolver allows the developers to change the way how messages are resolved.
|
Modifier and Type | Method and Description |
---|---|
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.
|
static void |
add(String clientId,
FacesMessage message)
Add the given faces message to the given client ID.
|
static void |
addError(String clientId,
String message,
Object... params)
Add an ERROR faces message to the given client ID, with the given message body which is formatted with the given
parameters.
|
static void |
addFatal(String clientId,
String message,
Object... params)
Add a FATAL faces message to the given client ID, with the given message body which is formatted with the given
parameters.
|
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.
|
static void |
addFlash(String clientId,
FacesMessage message)
Add a flash scoped faces message to the given client ID.
|
static void |
addFlashError(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 void |
addFlashFatal(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 void |
addFlashGlobal(FacesMessage message)
Add a flash scoped global faces message.
|
static void |
addFlashGlobalError(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 void |
addFlashGlobalFatal(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 void |
addFlashGlobalInfo(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 void |
addFlashGlobalWarn(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 void |
addFlashInfo(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 void |
addFlashWarn(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 void |
addGlobal(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 void |
addGlobal(FacesMessage message)
Add a global faces message.
|
static void |
addGlobalError(String message,
Object... params)
Add a global ERROR faces message, with the given message body which is formatted with the given parameters.
|
static void |
addGlobalFatal(String message,
Object... params)
Add a global FATAL faces message, with the given message body which is formatted with the given parameters.
|
static void |
addGlobalInfo(String message,
Object... params)
Add a global INFO faces message, with the given message body which is formatted with the given parameters.
|
static void |
addGlobalWarn(String message,
Object... params)
Add a global WARN faces message, with the given message body which is formatted with the given parameters.
|
static void |
addInfo(String clientId,
String message,
Object... params)
Add an INFO faces message to the given client ID, with the given message body which is formatted with the given
parameters.
|
static void |
addWarn(String clientId,
String message,
Object... params)
Add a WARN faces message to the given client ID, with the given message body which is formatted with the given
parameters.
|
static boolean |
clear(FacesMessage.Severity severity,
String... clientIds)
Clears faces messages of the given severity associated with the given client IDs.
|
static boolean |
clear(String... clientIds)
Clears faces messages associated with the given client IDs.
|
static boolean |
clearError(String... clientIds)
Clears ERROR faces messages associated with the given client IDs.
|
static boolean |
clearFatal(String... clientIds)
Clears FATAL faces messages associated with the given client IDs.
|
static boolean |
clearGlobal()
Clears global faces messages of all severities.
|
static boolean |
clearGlobal(FacesMessage.Severity severity)
Clears global faces messages of given severity.
|
static boolean |
clearGlobalError()
Clears global ERROR faces messages.
|
static boolean |
clearGlobalFatal()
Clears global FATAL faces messages.
|
static boolean |
clearGlobalInfo()
Clears global INFO faces messages.
|
static boolean |
clearGlobalWarn()
Clears global WARN faces messages.
|
static boolean |
clearInfo(String... clientIds)
Clears INFO faces messages associated with the given client IDs.
|
static boolean |
clearWarn(String... clientIds)
Clears WARN faces messages associated with the given client IDs.
|
static FacesMessage |
create(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.Message |
create(String message,
Object... params)
Create a faces message with the default INFO severity and the given message body which is formatted with the
given parameters as summary message.
|
static FacesMessage |
createError(String message,
Object... params)
Create an ERROR faces message with the given message body which is formatted with the given parameters.
|
static FacesMessage |
createFatal(String message,
Object... params)
Create a FATAL faces message with the given message body which is formatted with the given parameters.
|
static FacesMessage |
createInfo(String message,
Object... params)
Create an INFO faces message with the given message body which is formatted with the given parameters.
|
static FacesMessage |
createWarn(String message,
Object... params)
Create a WARN faces message with the given message body which is formatted with the given parameters.
|
static boolean |
isEmpty()
Returns
true if there are no faces messages, otherwise false . |
static boolean |
isEmpty(String clientId)
Returns
true if there are no faces messages for the given client ID, otherwise false . |
static boolean |
isGlobalEmpty()
Returns
true if there are no global faces messages, otherwise false . |
static void |
setResolver(Messages.Resolver resolver)
Set the custom message resolver.
|
void |
throwConverterException(String message,
Object... params)
Throw a
ConverterException with an ERROR faces message with the given message body which is formatted
with the given parameters. |
void |
throwValidatorException(String message,
Object... params)
Throw a
ValidatorException with an ERROR faces message with the given message body which is formatted
with the given parameters. |
public static void setResolver(Messages.Resolver resolver)
ServletContextListener
as WebListener
, or a
ServletContainerInitializer
in custom JAR, or a ApplicationScoped
bean, or an eagerly initialized
Startup
bean.resolver
- The custom message resolver.IllegalStateException
- When the resolver has already been set.public static Messages.Message create(String message, Object... params)
Messages.Message.detail(String, Object...)
.
To change the default INFO severity, use Messages.Message.warn()
, Messages.Message.error()
, or
Messages.Message.fatal()
. To make it a flash message, use Messages.Message.flash()
. To finally add it to the faces
context, use either Messages.Message.add(String)
to add it for a specific client ID, or Messages.Message.add()
to
add it as a global message.message
- The message body.params
- The message format parameters, if any.Messages.Message
builder.createInfo(String, Object...)
,
Messages.Resolver.getMessage(String, Object...)
public static FacesMessage create(FacesMessage.Severity severity, String message, Object... params)
ConverterException
or a
ValidatorException
.severity
- The severity of the faces message.message
- The message body.params
- The message format parameters, if any.Messages.Resolver.getMessage(String, Object...)
public static FacesMessage createInfo(String message, Object... params)
message
- The message body.params
- The message format parameters, if any.create(javax.faces.application.FacesMessage.Severity, String, Object...)
public static FacesMessage createWarn(String message, Object... params)
message
- The message body.params
- The message format parameters, if any.create(javax.faces.application.FacesMessage.Severity, String, Object...)
public static FacesMessage createError(String message, Object... params)
message
- The message body.params
- The message format parameters, if any.create(javax.faces.application.FacesMessage.Severity, String, Object...)
public static FacesMessage createFatal(String message, Object... params)
message
- The message body.params
- The message format parameters, if any.create(javax.faces.application.FacesMessage.Severity, String, Object...)
public void throwConverterException(String message, Object... params)
ConverterException
with an ERROR faces message with the given message body which is formatted
with the given parameters.message
- The message body.params
- The message format parameters, if any.ConverterException
- with the given parameters.createError(String, Object...)
public void throwValidatorException(String message, Object... params)
ValidatorException
with an ERROR faces message with the given message body which is formatted
with the given parameters.message
- The message body.params
- The message format parameters, if any.ValidatorException
- with the given parameters.createError(String, Object...)
public static void add(String clientId, FacesMessage message)
null
, it becomes a
global faces message. This can be filtered in a <h:messages globalOnly="true">
.clientId
- The client ID to add the faces message for.message
- The faces message.FacesContext.addMessage(String, FacesMessage)
public static void add(FacesMessage.Severity severity, String clientId, String message, Object... params)
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.create(javax.faces.application.FacesMessage.Severity, String, Object...)
,
add(String, FacesMessage)
public static void addInfo(String clientId, String message, Object... params)
clientId
- The client ID to add the faces message for.message
- The message body.params
- The message format parameters, if any.createInfo(String, Object...)
,
add(String, FacesMessage)
public static void addWarn(String clientId, String message, Object... params)
clientId
- The client ID to add the faces message for.message
- The message body.params
- The message format parameters, if any.createWarn(String, Object...)
,
add(String, FacesMessage)
public static void addError(String clientId, String message, Object... params)
clientId
- The client ID to add the faces message for.message
- The message body.params
- The message format parameters, if any.createError(String, Object...)
,
add(String, FacesMessage)
public static void addFatal(String clientId, String message, Object... params)
clientId
- The client ID to add the faces message for.message
- The message body.params
- The message format parameters, if any.createFatal(String, Object...)
,
add(String, FacesMessage)
public static void addGlobal(FacesMessage message)
null
.message
- The global faces message.add(String, FacesMessage)
public static void addGlobal(FacesMessage.Severity severity, String message, Object... params)
severity
- The severity of the global faces message.message
- The message body.params
- The message format parameters, if any.create(javax.faces.application.FacesMessage.Severity, String, Object...)
,
addGlobal(FacesMessage)
public static void addGlobalInfo(String message, Object... params)
message
- The message body.params
- The message format parameters, if any.createInfo(String, Object...)
,
addGlobal(FacesMessage)
public static void addGlobalWarn(String message, Object... params)
message
- The message body.params
- The message format parameters, if any.createWarn(String, Object...)
,
addGlobal(FacesMessage)
public static void addGlobalError(String message, Object... params)
message
- The message body.params
- The message format parameters, if any.createError(String, Object...)
,
addGlobal(FacesMessage)
public static void addGlobalFatal(String message, Object... params)
message
- The message body.params
- The message format parameters, if any.createFatal(String, Object...)
,
addGlobal(FacesMessage)
public static void addFlash(String clientId, FacesMessage message)
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.
clientId
- The client ID to add the flash scoped faces message for.message
- The faces message.Flash.setKeepMessages(boolean)
,
add(String, FacesMessage)
public static void addFlash(FacesMessage.Severity severity, String clientId, String message, Object... params)
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.create(javax.faces.application.FacesMessage.Severity, String, Object...)
,
addFlash(String, FacesMessage)
public static void addFlashInfo(String clientId, String message, Object... params)
clientId
- The client ID to add the faces message for.message
- The message body.params
- The message format parameters, if any.createInfo(String, Object...)
,
addFlash(String, FacesMessage)
public static void addFlashWarn(String clientId, String message, Object... params)
clientId
- The client ID to add the faces message for.message
- The message body.params
- The message format parameters, if any.createWarn(String, Object...)
,
addFlash(String, FacesMessage)
public static void addFlashError(String clientId, String message, Object... params)
clientId
- The client ID to add the faces message for.message
- The message body.params
- The message format parameters, if any.createError(String, Object...)
,
addFlash(String, FacesMessage)
public static void addFlashFatal(String clientId, String message, Object... params)
clientId
- The client ID to add the faces message for.message
- The message body.params
- The message format parameters, if any.createFatal(String, Object...)
,
addFlash(String, FacesMessage)
public static void addFlashGlobal(FacesMessage message)
null
. Use this
when you need to display the message after a redirect.message
- The global faces message.addFlash(String, FacesMessage)
public static void addFlashGlobalInfo(String message, Object... params)
message
- The message body.params
- The message format parameters, if any.createInfo(String, Object...)
,
addFlashGlobal(FacesMessage)
public static void addFlashGlobalWarn(String message, Object... params)
message
- The message body.params
- The message format parameters, if any.createWarn(String, Object...)
,
addFlashGlobal(FacesMessage)
public static void addFlashGlobalError(String message, Object... params)
message
- The message body.params
- The message format parameters, if any.createError(String, Object...)
,
addFlashGlobal(FacesMessage)
public static void addFlashGlobalFatal(String message, Object... params)
message
- The message body.params
- The message format parameters, if any.createFatal(String, Object...)
,
addFlashGlobal(FacesMessage)
public static boolean isEmpty()
true
if there are no faces messages, otherwise false
.true
if there are no faces messages, otherwise false
.FacesContext.getMessageList()
public static boolean isEmpty(String clientId)
true
if there are no faces messages for the given client ID, otherwise false
.clientId
- The client ID to check the messages for.true
if there are no faces messages for the given client ID, otherwise false
.FacesContext.getMessageList(String)
public static boolean isGlobalEmpty()
true
if there are no global faces messages, otherwise false
.true
if there are no global faces messages, otherwise false
.FacesContext.getMessageList(String)
public static boolean clear(FacesMessage.Severity severity, String... clientIds)
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.true
if at least one faces message of the given severity associated with the given client
IDs was cleared.FacesContext.getMessages()
,
FacesContext.getMessages(String)
public static boolean clear(String... clientIds)
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.true
if at least one faces message associated with the given client IDs was cleared.clear(javax.faces.application.FacesMessage.Severity, String...)
public static boolean clearInfo(String... clientIds)
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.true
if at least one INFO faces message associated with the given client IDs was cleared.clear(javax.faces.application.FacesMessage.Severity, String...)
public static boolean clearWarn(String... clientIds)
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.true
if at least one WARN faces message associated with the given client IDs was cleared.clear(javax.faces.application.FacesMessage.Severity, String...)
public static boolean clearError(String... clientIds)
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.true
if at least one ERROR faces message associated with the given client IDs was cleared.clear(javax.faces.application.FacesMessage.Severity, String...)
public static boolean clearFatal(String... clientIds)
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.true
if at least one FATAL faces message associated with the given client IDs was cleared.clear(javax.faces.application.FacesMessage.Severity, String...)
public static boolean clearGlobal(FacesMessage.Severity severity)
severity
- The severity of the faces message. If this is null, then all severities are matched.true
if at least one global faces message of given severity was cleared.clear(javax.faces.application.FacesMessage.Severity, String...)
public static boolean clearGlobal()
true
if at least one global faces message was cleared.clear(javax.faces.application.FacesMessage.Severity, String...)
public static boolean clearGlobalInfo()
true
if at least one global INFO faces message was cleared.clearInfo(String...)
public static boolean clearGlobalWarn()
true
if at least one global WARN faces message was cleared.clearWarn(String...)
public static boolean clearGlobalError()
true
if at least one global ERROR faces message was cleared.clearError(String...)
public static boolean clearGlobalFatal()
true
if at least one global FATAL faces message was cleared.clearFatal(String...)
Copyright © 2012–2020 OmniFaces. All rights reserved.