Module org.omnifaces
Package org.omnifaces.util

Class Messages

  • public final class Messages
extends Object

    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

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class 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

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method 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 message)
      Add a global faces message.
      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 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 ConverterException asConverterException​(String message, Object... params)
      Returns a ConverterException with an ERROR faces message with the given message body which is formatted with the given parameters.
      static ValidatorException asValidatorException​(String message, Object... params)
      Returns a ValidatorException with an ERROR faces message 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.
      static 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.
      static 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.

    • Method Detail

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

      • asConverterException

        public static ConverterException asConverterException​(String message,
                                                      Object... params)
        Returns a ConverterException with 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:
        createError(String, Object...)

      • asValidatorException

        public static ValidatorException asValidatorException​(String message,
                                                      Object... params)
        Returns a ValidatorException with 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:
        createError(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)

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

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

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

      • clear

        public static boolean clear​(FacesMessage.Severity severity,
                            String... clientIds)
        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:
        true if at least one faces message of the given severity associated with the given client IDs was cleared.
        Since:
        3.5
        See Also:
        FacesContext.getMessages(), FacesContext.getMessages(String)

      • clear

        public static boolean clear​(String... clientIds)
        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:
        true if at least one faces message associated with the given client IDs was cleared.
        Since:
        3.5
        See Also:
        clear(jakarta.faces.application.FacesMessage.Severity, String...)

      • clearInfo

        public static boolean clearInfo​(String... clientIds)
        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:
        true if at least one INFO faces message associated with the given client IDs was cleared.
        Since:
        3.5
        See Also:
        clear(jakarta.faces.application.FacesMessage.Severity, String...)

      • clearWarn

        public static boolean clearWarn​(String... clientIds)
        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:
        true if at least one WARN faces message associated with the given client IDs was cleared.
        Since:
        3.5
        See Also:
        clear(jakarta.faces.application.FacesMessage.Severity, String...)

      • clearError

        public static boolean clearError​(String... clientIds)
        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:
        true if at least one ERROR faces message associated with the given client IDs was cleared.
        Since:
        3.5
        See Also:
        clear(jakarta.faces.application.FacesMessage.Severity, String...)

      • clearFatal

        public static boolean clearFatal​(String... clientIds)
        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:
        true if at least one FATAL faces message associated with the given client IDs was cleared.
        Since:
        3.5
        See Also:
        clear(jakarta.faces.application.FacesMessage.Severity, String...)

      • clearGlobalInfo

        public static boolean clearGlobalInfo()
        Clears global INFO faces messages.
        Returns:
        true if at least one global INFO faces message was cleared.
        Since:
        3.5
        See Also:
        clearInfo(String...)

      • clearGlobalWarn

        public static boolean clearGlobalWarn()
        Clears global WARN faces messages.
        Returns:
        true if at least one global WARN faces message was cleared.
        Since:
        3.5
        See Also:
        clearWarn(String...)

      • clearGlobalError

        public static boolean clearGlobalError()
        Clears global ERROR faces messages.
        Returns:
        true if at least one global ERROR faces message was cleared.
        Since:
        3.5
        See Also:
        clearError(String...)

      • clearGlobalFatal

        public static boolean clearGlobalFatal()
        Clears global FATAL faces messages.
        Returns:
        true if at least one global FATAL faces message was cleared.
        Since:
        3.5
        See Also:
        clearFatal(String...)