Vaadin

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.
textfield.setComponentError(null); // (actually the default)
// 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.
        // (Allow 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);
        }
    }
});

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

For example, in the following code excerpt, we throw an error in an event listener but do not catch it, so it falls to the framework.

final Button button = new Button ("Fail Me");
button.addListener(new Button.ClickListener() {
    public void buttonClick(ClickEvent event) {
        // Throw some exception.
        throw new RuntimeException("You can't catch this.");
    }
});

Any such exceptions that occur in the call chain, but are not caught at any other level, are eventually caught by the terminal adapter in ApplicationServlet, the lowest-level component that receives client requests. The terminal adapter passes all such caught exceptions as events to the error listener of the Application instance through the Terminal.ErrorListener interface. The Application class does not, by default, throw such exceptions forward.

The reason for this error-handling logic lies in the logic that handles component state synchronization between the client and the server. We want to handle all the serialized variable changes in the client request, because otherwise the client-side and server-side component states would become unsynchronized very easily, which could put the entire application in an invalid state.

The default implementation of the Terminal.ErrorListener interface in the Application class simply prints the error to console. It also tries to find out a component related to the error. If the exception occurred in a listener attached to a component, that component is considered as the component related to the exception. If a related component is found, the error handler sets the component error for it, the same attribute which you can set with setComponentError().

You can change the logic of handling the terminal errors easily by overriding the terminalError() method in your application class (the one that inherits Application) or by setting a custom error listener with the 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 in the main window.

@Override
public void terminalError(Terminal.ErrorEvent event) {
    // Call the default implementation.
    super.terminalError(event);
    // Some custom behaviour.
    if (getMainWindow() != null) {
        getMainWindow().showNotification(
                "An unchecked exception occured!",
                event.getThrowable().toString(),
                Notification.TYPE_ERROR_MESSAGE);
    }
}

Handling other exceptions works in the usual way for Java Servlets. Uncaught exceptions are finally caught and handled by the application server.