Router Exception Handling

There is special support for navigation targets that are activated for an unhandled exception thrown during navigation to show an “error view” to the user.

These targets generally work in the same way as regular navigation targets, although they do typically not have any specific @Route as they are shown for arbitrary URLs.

Error navigation is resolved to a target based on the exception type thrown during navigation.

At startup all classes implementing the interface HasErrorParameter<T extends Exception> will be collected to be used as exception targets during navigation.

For instance here is the default target for the NotFoundException that will be shown when there is no target for the given url.

RouteNotFoundError for NotFoundException during routing

@Tag(Tag.DIV)
public class RouteNotFoundError extends Component
        implements HasErrorParameter<NotFoundException> {
    @Override
    public int setErrorParameter(BeforeEnterEvent event,
            ErrorParameter<NotFoundException> parameter) {
        getElement().setText("Could not navigate to '"
                    + event.getLocation().getPath() + "'");
        return HttpServletResponse.SC_NOT_FOUND;
    }
}

This will return an http response of 404 and show the set text to the user.

Exception matching will run first by exception cause and then by exception super type.

Default exceptions that are implemented are RouteNotFoundError for NotFoundException with a 404 and InternalServerError for java.lang.Exception with a 500.

The default exception handlers can be overridden by extending them like:

Custom route not found that is using our application layout

@ParentLayout(MainLayout.class)
public class CustomNotFoundTarget extends RouteNotFoundError {
    @Override
    public int setErrorParameter(BeforeEnterEvent event,
            ErrorParameter<NotFoundException> parameter) {
        getElement().setText("My custom not found class!");
        return HttpServletResponse.SC_NOT_FOUND;
    }
}

As a more complex sample we could have a Dashboard that collects and shows widgets to the user and can have widgets that should not be shown for unauthenticated users. For some reason a ProtectedWidget is loaded for an un-authenticated user.

The collection should have caught the protected widget, but for some reason instantiates it, but luckily the widget checks authentication on creation and throws and AccessDeniedException.

This unhandled exception propagates during navigation and is handled by the AccessDeniedExceptionHandler that still keeps the MainLayout with its menu bar, but displays information that an exception has happened.

Access denied exception sample when protected widget is loaded by mistake

@Route(value = "dashboard", layout = MainLayout.class)
@Tag(Tag.DIV)
public class Dashboard extends Component {
    public Dashboard() {
        init();
    }
    private void init() {
        getWidgets().forEach(this::addWidget);
    }
    public void addWidget(Widget widget) {
        // Implementation omitted
    }
    private Stream<Widget> getWidgets() {
        // Implementation omitted, gets faulty state widget
        return Stream.of(new ProtectedWidget());
    }
}
public class ProtectedWidget extends Widget {
    public ProtectedWidget() {
        if (!AccessHandler.getInstance().isAuthenticated()) {
            throw new AccessDeniedException("Unauthorized widget access");
        }
        // Implementation omitted
    }
}
@Tag(Tag.DIV)
public abstract class Widget extends Component {
    public boolean isProtected() {
        // Implementation omitted
        return true;
    }
}
@Tag(Tag.DIV)
@ParentLayout(MainLayout.class)
public class AccessDeniedExceptionHandler extends Component
        implements HasErrorParameter<AccessDeniedException> {
    @Override
    public int setErrorParameter(BeforeEnterEvent event,
            ErrorParameter<AccessDeniedException> parameter) {
        getElement().setText(
            "Tried to navigate to a view without correct access rights");
        return HttpServletResponse.SC_FORBIDDEN;
    }
}

Rerouting to an error view

It is possible to reroute to an error view registered for an exception from the BeforeEnterEvent and BeforeLeaveEvent.

The rerouting is done by using one of the overloads for rerouteToError with only the exception class to target or with an added custom error message.

Reroute to error view

public class AuthenticationHandler implements BeforeEnterObserver {
    @Override
    public void beforeEnter(BeforeEnterEvent event) {
        Class<?> target = event.getNavigationTarget();
        if (!currentUserMayEnter(target)) {
            event.rerouteToError(AccessDeniedException.class);
        }
    }
    private boolean currentUserMayEnter(Class<?> target) {
        // implementation omitted
        return false;
    }
}

Blog sample error view with a custom message

@Tag(Tag.DIV)
public class BlogPost extends Component implements HasUrlParameter<Long> {
    @Override
    public void setParameter(BeforeEvent event, Long parameter) {
        removeAll();
        Optional<BlogRecord> record = getRecord(parameter);
        if (!record.isPresent()) {
            event.rerouteToError(IllegalArgumentException.class,
                    getTranslation("blog.post.not.found",
                            event.getLocation().getPath()));
        } else {
            displayRecord(record.get());
        }
    }
    private void removeAll() {
        // NO-OP
    }
    private void displayRecord(BlogRecord record) {
        // NO-OP
    }
    public Optional<BlogRecord> getRecord(Long id) {
        // Implementation omitted
        return Optional.empty();
    }
}
@Tag(Tag.DIV)
public class FaultyBlogPostHandler extends Component
        implements HasErrorParameter<IllegalArgumentException> {
    @Override
    public int setErrorParameter(BeforeEnterEvent event,
            ErrorParameter<IllegalArgumentException> parameter) {
        Label message = new Label(parameter.getCustomMessage());
        getElement().appendChild(message.getElement());
        return HttpServletResponse.SC_NOT_FOUND;
    }
}