4.7. Handling Errors

All components have a built-in error indicator that can be set explicitly with setComponentError() or can be turned on implicitly if validating the component fails. As with component caption, the placement of the indicator is managed by the layout in which the component is contained. Usually, the error indicator is placed right of the caption text. Hovering the mouse pointer over the field displays the error message.

The following example shows how you can set the component error explicitly. The example essentially validates field value without using an actual validator.

// Create a field.
final TextField textfield = new TextField("Enter code");
main.addComponent(textfield);

// Let the component error be initially clear. (It actually is by default.)
textfield.setComponentError(null);

// Have a button right of the field (and align it properly).
final Button button = new Button("Ok!");
main.addComponent(button);
((VerticalLayout)main.getLayout()).setComponentAlignment(button, Alignment.BOTTOM_LEFT);

// Handle button clicks
button.addListener(new Button.ClickListener() {
    public void buttonClick(ClickEvent event) {
        // If the field value is bad, set its error.
        // (Here the content must be only alphanumeric characters.)
        if (! ((String) textfield.getValue()).matches("^\\w*$")) {
            // Put the component in error state and set the error message.
            textfield.setComponentError(new UserError("Must be letters and numbers"));
        } else {
            // Otherwise clear it.
            textfield.setComponentError(null);
        }
    }
});

The Form component handles and displays also the errors of its contained fields so that it displays both the error indicator and the message in a special error indicator area. See Section 5.17, “Form” and Section 5.17.3, “Validating Form Input” for details on the Form component and validation of form input.

Notifications are error or information boxes that appear typically at the center of the screen. A notification box has a caption and optional description and icon. The box stays on the screen either for a defined time or until the user clicks it. The notification type defines the default appearance and behaviour of a notification.

Notifications are always associated with a window object, which can be a child window (the positioning is always relative to the entire browser view). The Window class provides a showNotification() method for displaying notifications. The method takes the caption and an optional description and notification type as parameters. The method also accepts a notification object of type Window.Notification, as described further below.

mainwindow.showNotification("This is the caption",
                            "This is the description");

The caption and description are, by default, written on the same line. If you want to have a line break between them, use the XHTML line break markup "<br/>". You can use any XHTML markup in the caption and description of a notification.

main.showNotification("This is a warning",
                            "<br/>This is the <i>last</i> warning",
                            Window.Notification.TYPE_WARNING_MESSAGE);

The notification type defines the overall default style and behaviour of a notification. If no notification type is given, the "humanized" type is used as the default. The notification types, listed below, are defined in the Window.Notification class.

All of the features of specific notification types can be controlled with the attributes of Window.Notification. You can pass an explicitly created notification object to the showNotification() method.

// Create a notification with the default settings for a warning.
Window.Notification notif = new Window.Notification(
        "Be warned!", "This message lurks in the top-left corner!",
        Window.Notification.TYPE_WARNING_MESSAGE);

// Set the position.
notif.setPosition(Window.Notification.POSITION_TOP_LEFT);

// Let it stay there until the user clicks it
notif.setDelayMsec(-1);

// Show it in the main window.
main.showNotification(notif);

The setPosition() method allows setting the positioning of the notification. The method takes as its parameter any of the constants:

The setDelayMSec() allows you to set the time in milliseconds for how long the notification is displayed. Parameter value -1 means that the message is displayed until the user clicks the message box. It also prevents interaction with other parts of the application window, as is default behaviour for error messages. It does not, however, add a close box that the error notification has.

Most of the actual application logic is event driven. Mouse and keyboard events in client initiates event listeners on server side and that is how most of application logic gets run. Unchecked exceptions in Toolkit applications usually happen on these client initiated events. RuntimeExceptions that happen in those call chains are caught by terminal and passed to the error listener of Application instance. These exceptions can happen in the actual framework code or the application logic. Application by default does not throw them forward. This is because we want to handle all variable changes in the request. Without this somewhat awkward behavior, it would be very common to get client and server side component states inconsistent with each other and that way put the entire application into a non-functional state.

The default Terminal.ErrorListener in Application prints the error to console. It also tries to find out a related component where the error happened. This is most commonly the component where the event listener was attached to. If the related component is found, the error handler puts a component error to it. In UI the component error is shown with a small red "!" -sign (in default theme).

The behavior of terminal error handling can be changed easily by overriding the terminalError(Terminal.ErrorEvent event) method in Application or by setting a custom error listener with setErrorHandler method. You can safely discard the default handling or extend its usage with your custom error handling or logging system. In the example code below the exceptions are also reported as notifications on main window.

    @Override
    public void terminalError(
            com.itmill.toolkit.terminal.Terminal.ErrorEvent event) {
        super.terminalError(event);
        if (getMainWindow() != null) {
            getMainWindow().showNotification("An unchecked exception occured!",
                    event.getThrowable().toString(),
                    Notification.TYPE_ERROR_MESSAGE);
        }
    }

Other exception handling works as it commonly does in Servlets. Unchecked exceptions are finally caught and handled by server.