org.omnifaces.util

Class Messages

java.lang.Object

org.omnifaces.util.Messages

public final class Messages
extends Object

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

Usage

Some examples:

 // In a validator.
 throw new ValidatorException(Messages.createError("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.
 throw new ValidatorException(Messages.create("Invalid input.").detail("Value {0} is not expected.", value).get());
 

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

Author:

Bauke Scholtz

Nested Class Summary

Nested Classes

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.

Method Summary

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

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

setResolver

public static void setResolver(Messages.Resolver resolver)

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 a ServletContextListener as WebListener, or a ServletContainerInitializer in custom JAR, or a ApplicationScoped bean, or an eagerly initialized Startup bean.

Parameters:

resolver - The custom message resolver.

Throws:

IllegalStateException - When the resolver has already been set.

create

public 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. To set the detail message, use 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.

Parameters:

message - The message body.

params - The message format parameters, if any.

Returns:

The Messages.Message builder.

Since:

1.1

See Also:

createInfo(String, Object...), Messages.Resolver.getMessage(String, Object...)

create

public 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. Useful when a faces message is needed to construct a ConverterException or a ValidatorException.

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:

Messages.Resolver.getMessage(String, Object...)

createInfo

public static FacesMessage createInfo(String message,
                                      Object... params)

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:

create(javax.faces.application.FacesMessage.Severity, String, Object...)

createWarn

public static FacesMessage createWarn(String message,
                                      Object... params)

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:

create(javax.faces.application.FacesMessage.Severity, String, Object...)

createError

public static FacesMessage createError(String message,
                                       Object... params)

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:

create(javax.faces.application.FacesMessage.Severity, String, Object...)

createFatal

public static FacesMessage createFatal(String message,
                                       Object... params)

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:

create(javax.faces.application.FacesMessage.Severity, String, Object...)

add

public static void add(String clientId,
                       FacesMessage message)

Add the given faces message to the given client ID. When the client ID is null, 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:

FacesContext.addMessage(String, FacesMessage)

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:

create(javax.faces.application.FacesMessage.Severity, String, Object...), add(String, FacesMessage)

addInfo

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

Parameters:

clientId - The client ID to add the faces message for.

message - The message body.

params - The message format parameters, if any.

See Also:

createInfo(String, Object...), add(String, FacesMessage)

addWarn

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

Parameters:

clientId - The client ID to add the faces message for.

message - The message body.

params - The message format parameters, if any.

See Also:

createWarn(String, Object...), add(String, FacesMessage)

addError

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

Parameters:

clientId - The client ID to add the faces message for.

message - The message body.

params - The message format parameters, if any.

See Also:

createError(String, Object...), add(String, FacesMessage)

addFatal

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

Parameters:

clientId - The client ID to add the faces message for.

message - The message body.

params - The message format parameters, if any.

See Also:

createFatal(String, Object...), add(String, FacesMessage)

addGlobal

public static void addGlobal(FacesMessage message)

Add a global faces message. This adds a faces message to a client ID of null.

Parameters:

message - The global faces message.

See Also:

add(String, FacesMessage)

addGlobal

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

Parameters:

severity - The severity of the global faces message.

message - The message body.

params - The message format parameters, if any.

See Also:

create(javax.faces.application.FacesMessage.Severity, String, Object...), addGlobal(FacesMessage)

addGlobalInfo

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

Parameters:

message - The message body.

params - The message format parameters, if any.

See Also:

createInfo(String, Object...), addGlobal(FacesMessage)

addGlobalWarn

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

Parameters:

message - The message body.

params - The message format parameters, if any.

See Also:

createWarn(String, Object...), addGlobal(FacesMessage)

addGlobalError

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

Parameters:

message - The message body.

params - The message format parameters, if any.

See Also:

createError(String, Object...), addGlobal(FacesMessage)

addGlobalFatal

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

Parameters:

message - The message body.

params - The message format parameters, if any.

See Also:

createFatal(String, Object...), addGlobal(FacesMessage)

addFlash

public static void addFlash(String clientId,
                            FacesMessage message)

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:

Flash.setKeepMessages(boolean), add(String, FacesMessage)

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:

create(javax.faces.application.FacesMessage.Severity, String, Object...), addFlash(String, FacesMessage)

addFlashInfo

public 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. 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:

createInfo(String, Object...), addFlash(String, FacesMessage)

addFlashWarn

public 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. 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:

createWarn(String, Object...), addFlash(String, FacesMessage)

addFlashError

public 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. 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:

createError(String, Object...), addFlash(String, FacesMessage)

addFlashFatal

public 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. 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:

createFatal(String, Object...), addFlash(String, FacesMessage)

addFlashGlobal

public static void addFlashGlobal(FacesMessage message)

Add a flash scoped global faces message. This adds a faces message to a client ID of null. Use this when you need to display the message after a redirect.

Parameters:

message - The global faces message.

See Also:

addFlash(String, FacesMessage)

addFlashGlobalInfo

public 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. 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:

createInfo(String, Object...), addFlashGlobal(FacesMessage)

addFlashGlobalWarn

public 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. 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:

createWarn(String, Object...), addFlashGlobal(FacesMessage)

addFlashGlobalError

public 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. 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:

createError(String, Object...), addFlashGlobal(FacesMessage)

addFlashGlobalFatal

public 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. 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:

createFatal(String, Object...), addFlashGlobal(FacesMessage)

isEmpty

public static boolean isEmpty()

Returns true if there are no faces messages, otherwise false.

Returns:

true if there are no faces messages, otherwise false.

Since:

2.2

See Also:

FacesContext.getMessageList()

isEmpty

public static boolean isEmpty(String clientId)

Returns true if there are no faces messages for the given client ID, otherwise false.

Parameters:

clientId - The client ID to check the messages for.

Returns:

true if there are no faces messages for the given client ID, otherwise false.

Since:

2.2

See Also:

FacesContext.getMessageList(String)

isGlobalEmpty

public static boolean isGlobalEmpty()

Returns true if there are no global faces messages, otherwise false.

Returns:

true if there are no global faces messages, otherwise false.

Since:

2.2

See Also:

FacesContext.getMessageList(String)