Routing

🚧

Work in progress

This section of the documentation is incomplete and is being frequently updated.

In this section we will cover how Veronica applications tackle the problem of routing. We are going to explore how does the application core relate to the application routes, and how does a Veronica application establish which route handles a given http request.

As you might recall from reading the documentation about the application structure, the application's Router is designed to provide this functionality. In fact, the Router holds a reference to all the Route objects of the application, and when it receives a Request object, it is responsible for finding a Route that handles the specified Request. In fact the application Router holds the reference to two objects:

1. An ordered set of Route objects, which contains all of the application routes. When the Router receives a Request, it traverses the set of routes until it finds a Route that can handle a given Request.
2. An additional special route, called the Fallback Route, which is used when no Route object in the routes' set can handle the request.

But how does the Router establish whether a specific Route can handle a given Request?
Quite simply, each route holds a reference to a Request Matcher object, which is an object that has the role of establishing whether a given Request object meets certain criteria. Therefore, each Route declares what Request objects it can handle via its Request Matcher.

We are now going to show a practical example of how we can design the routing structure of an example application. Suppose that we want to develop a website with two pages:

1. A homepage at /home
2. A contacts page at /contact

Therefore, we are going to design two routes, one for each of the pages. The homepage route will have a RequestMatcher that matches the requests to the /home path, and the contacts page route will have an analogous /contact RequestMatcher.

Java

Route<Request, Response> homepageRoute = ...;
Route<Request, Response> contactsRoute = ...;
        
homepageRoute.setRequestMatcher(request -> request.getUri().equals("/home"));
contactsRoute.setRequestMatcher(request -> request.getUri().equals("/contacts"));

Moreover, we realize that we want our routes to match only against Http GET requests. Instead of manually writing a more complex RequestMatcher, we can use the helper methods from the CommonRequestMatchers utilities class:

Java

homepageRoute.setRequestMatcher(get("/home"));
contactsRoute.setRequestMatcher(get("/contacts"));

Our routing setup is almost complete. The only part that is missing is a fallback route, that handles requests that do not match against any other Route in our Router. However, for this special Route we do not need to specify a RequestMatcher, since our Router is always going to default to this Route when no other Route matches against a specific Request.

🚧

Warning

When no RequestMatcher is specified, routes will use a default RequestMatcher that never returns true. Therefore, these routes will never be reachable by any request.