java - Routing template format for undertow

Question

Is there any documentation about routing template format for undertow. I want to setup handlers like this:

/ or /index.html -> Use handler 1
Anything else -> Use handler 2

I tried this one, bu did not work:

Handlers.routing()
        .add("GET", "/", handler1)
        .add("GET", "/index.html", handler1)
        .add("GET", "/*", handler2)

Any idea?

Answer 1

There are a couple of ways to achieve this:

1) Basic approach: PathHandler

Handlers.path()
    .addExactPath("/path1", handler1)
    .addPrefixPath("/path2", handler2);

The handler1 will match only on /path1 (or /path1/).

The handler2 will match on /path2, /path2/ and everything else that starts with /path2/.

2) Route approach: RoutingHandler

If you use a RoutingHandler, you have the option to easily extract variables from the paths. That's convenient for building REST APIs for example (note the usage of the convenience get method on the RoutingHandler).

Handlers.routing().get("/{test}/*", exchange -> {
    PathTemplateMatch pathMatch = exchange.getAttachment(PathTemplateMatch.ATTACHMENT_KEY);
    String itemId1 = pathMatch.getParameters().get("test"); // or exchange.getQueryParameters().get("test")
    String itemId2 = pathMatch.getParameters().get("*"); // or exchange.getQueryParameters().get("*")
}))

The * parameter can match anything (like a path for instance a/b/c). In order to use the * parameter, you need an actual named parameter defined before in the route template (test in my example).

Note that the parameters defined in your route template will be available together with the query parameters (exchange.getQueryParameters()). This is default behavior. If you do not want it, you can create your routing handler like this: Handlers.routing(false).get(...) and then retrieve the parameters from the exchange's attachments.

For any route that is not matched by your routing handler, you can use the fallbackHandler available in the RoutingHandler.

Handlers.routing()
      .get("/", handler1)
      .get("/index.html", handler1)
      .setFallbackHandler(handler2);

By default the fallbackHandler simply returns an empty response body with a 404 status code. The handler2 will be matching any other requests, not only GET requests.

Comprehensive Example

You can of course combine PathHandler and RoutingHandler to fit your needs.

Here is a small example of a more realistic setup:

Undertow.builder().addHttpListener(8080, "0.0.0.0")
    .setHandler(Handlers.path()

        // REST API path
        .addPrefixPath("/api", Handlers.routing()
            .get("/customers", exchange -> {...})
            .delete("/customers/{customerId}", exchange -> {...})
            .setFallbackHandler(exchange -> {...}))

        // Redirect root path to /static to serve the index.html by default
        .addExactPath("/", Handlers.redirect("/static"))

        // Serve all static files from a folder
        .addPrefixPath("/static", new ResourceHandler(
            new PathResourceManager(Paths.get("/path/to/www/"), 100))
            .setWelcomeFiles("index.html"))

    ).build().start();

This application also serves static files from your file system. This is handy to serve a javascript application or static html files for instance.