MessageService

Allows domain objects to raise information, warning or error messages.

These messages can either be simple strings, or can be translated.

API

MessageService.java

interface MessageService {
  void informUser(String message)     (1)
  String informUser(TranslatableString message, Class<?> contextClass, String contextMethod)     (2)
  String informUser(TranslatableString message, TranslationContext translationContext)     (3)
  void warnUser(String message)     (4)
  String warnUser(TranslatableString message, Class<?> contextClass, String contextMethod)     (5)
  String warnUser(TranslatableString message, TranslationContext translationContext)     (6)
  void raiseError(String message)     (7)
  String raiseError(TranslatableString message, Class<?> contextClass, String contextMethod)     (8)
  String raiseError(TranslatableString message, TranslationContext translationContext)     (9)
  void setError(String message)     (10)
}

1	informUser(String) Make the specified message available to the user, intended to be useful but optional information, for a viewer to display typically in a transitory manner.
2	informUser(TranslatableString, Class, String) As #informUser(String) , but with the message translated (if possible) to user’s java.util.Locale .
3	informUser(TranslatableString, TranslationContext) Override of MessageService#informUser(TranslatableString, Class, String) , but with an arbitrary translation context (rather than inferred from the context class and method).
4	warnUser(String) Warn the user about a situation with the specified message.
5	warnUser(TranslatableString, Class, String) As #warnUser(String) , but with the message translated (if possible) to user’s java.util.Locale .
6	warnUser(TranslatableString, TranslationContext) Override of MessageService#warnUser(TranslatableString, Class, String) , but with an arbitrary translation context (rather than inferred from the context class and method).
7	raiseError(String) Notify the user of an application error with the specified message.
8	raiseError(TranslatableString, Class, String) As #raiseError(String) , but with the message translated (if possible) to user’s java.util.Locale .
9	raiseError(TranslatableString, TranslationContext) Override of MessageService#raiseError(TranslatableString, Class, String) , but with an arbitrary translation context (rather than inferred from the context class and method).
10	setError(String) Sets a new application error message. Similar to #raiseError(String) , but without throwing a RecoverableException .

Members

informUser(String)

Make the specified message available to the user, intended to be useful but optional information, for a viewer to display typically in a transitory manner.

In the Wicket viewer this is implemented as a "toast" message that automatically disappears after a period of time.

informUser(TranslatableString, Class, String)

As #informUser(String) , but with the message translated (if possible) to user’s java.util.Locale .

More precisely, the locale is as provided by the configured org.apache.causeway.applib.services.i18n.LanguageProvider service. This should be the java.util.Locale of the user making the current request.

informUser(TranslatableString, TranslationContext)

Override of MessageService#informUser(TranslatableString, Class, String) , but with an arbitrary translation context (rather than inferred from the context class and method).

warnUser(String)

Warn the user about a situation with the specified message.

The viewer should guarantee to display this warning to the user, and will typically require acknowledgement.

In the Wicket viewer this is implemented as a "toast" message that must be explicitly closed by the user.

warnUser(TranslatableString, Class, String)

As #warnUser(String) , but with the message translated (if possible) to user’s java.util.Locale .

warnUser(TranslatableString, TranslationContext)

Override of MessageService#warnUser(TranslatableString, Class, String) , but with an arbitrary translation context (rather than inferred from the context class and method).

raiseError(String)

Notify the user of an application error with the specified message.

Note this will probably be displayed in an prominent fashion, so is only suitable for errors. The user will typically be required to perform additional steps after the error..

In the Wicket viewer this is implemented as a toast (with a different colour) that must be closed by the end-user.

raiseError(TranslatableString, Class, String)

As #raiseError(String) , but with the message translated (if possible) to user’s java.util.Locale .

raiseError(TranslatableString, TranslationContext)

Override of MessageService#raiseError(TranslatableString, Class, String) , but with an arbitrary translation context (rather than inferred from the context class and method).

setError(String)

Sets a new application error message. Similar to #raiseError(String) , but without throwing a RecoverableException .

Implementation

The core framework provides a default implementation of this service, o.a.c.core.runtimeservices.message.MessageServiceDefault.

Example Usage

For example:

public Order addItem(Product product, @ParameterLayout(named="Quantity") int quantity) {
    if(productRepository.stockLevel(product) == 0) {
        messageService.warnUser(
            product.getDescription() + " out of stock; order fulfillment may be delayed");
    }
    ...
}

i18n

Messages and warnings can optionally be translated according to the locale of the current user.

The contextClass and contextMethod parameters provided by the framework are used to create a context string for translation, eg "com.mycompany.Customer#placeOrder".

For the "big picture" and further details on the framework’s i18n support, can be found in a chapter in the user guide.