Documentation

Documentation

Configuring Customizing System Messages

Configuring messages for application invalid state.

System messages are notifications that indicate a major invalid state that may require restarting the application. The different types of invalid state handled by system messages are the session expired, internal error, and cookie disabled states.

When the client falls into invalid state, a notification appears in the browser that reloads the page and disappears after the user clicks on it. However, for the session expired state the default behavior is to reload the page without showing the notification.

The message and behavior are defined in the SystemMessages class.

Each invalid state has four properties: A short caption, a message, a URL to where to redirect after displaying the message, and a property indicating whether the notification is enabled. If the URL is not specified, the current page is reloaded. When the notification is disabled, the reload or redirect happens without any notification to the user. Setting both the caption and message to null has the same effect as disabling the notification.

The default values of the properties are shown below. The default values for system messages are also documented in the SystemMessages class Javadocs.

  • sessionExpiredNotificationEnabled: false

  • sessionExpiredURL: null

  • sessionExpiredCaption: Session Expired

  • sessionExpiredMessage: Take note of any unsaved data, and click here or press ESC key to continue.

  • internalErrorNotificationEnabled: true

  • internalErrorURL: null

  • internalErrorCaption: Internal error

  • internalErrorMessage: Please notify the administrator. Take note of any unsaved data, and click here or press ESC to continue.

  • cookiesDisabledNotificationEnabled: true

  • cookiesDisabledURL: null

  • cookiesDisabledCaption: Cookies disabled

  • cookiesDisabledMessage: This application requires cookies to function. Please enable cookies in your browser and click here or press ESC to try again.

The notification is disabled by default for session expired, but enabled for internal error and cookie disabled.

System messages can be overridden by setting the SystemMessagesProvider in the VaadinService. You need to implement the getSystemMessages(SystemMessagesInfo) method, which returns a SystemMessages object. The simplest way to customize the messages is to use a CustomizedSystemMessages object with the provided setter methods to configure the desired properties.

The SystemMessagesInfo parameter provided to getSystemMessages() allows access to the UI locale, so that messages can be translated in the current user language.

You can set the system message provider in the serviceInit() method of a service init listener, for example as follows:

public class CustomInitServiceListener implements VaadinServiceInitListener {
    @Override
    public void serviceInit(ServiceInitEvent event) {
        event.getSource().setSystemMessagesProvider(new SystemMessagesProvider() {
            @Override
            public SystemMessages getSystemMessages(SystemMessagesInfo systemMessagesInfo) {
                CustomizedSystemMessages messages = new CustomizedSystemMessages();
                messages.setSessionExpiredCaption("Session expired");
                messages.setSessionExpiredMessage("Take note of any unsaved data, and click here or press ESC key to continue.");
                messages.setSessionExpiredURL("session-expired.html");
                messages.setSessionExpiredNotificationEnabled(true);
                return messages;
            }
        });
    };
};