Routing

The most routing is done by naming convention of the Controllers, but it is also possible to add some custom routing mappings.

Custom routing

As with other configurations, routing is placed in a reserved class named app.config.RouteConfig.java.

public class RouteConfig extends AbstractRouteConfig {
    @Override
    public void init(AppContext appContext) {
        route("/movie/id/{id}").action("single").to(MovieController.class);
        route("/else").to(SomeController.class);
        route("/{action}/hello/{name}").to(IndexController.class);
    }
}

Routing is based on segments in the URL, which are split on forward slash '/'. The following has three segments:

/say/hello/Martin-Fowler

This would be mapped to the route: /{action}/hello/{name}, which is configured to be handled by IndexController.

Types of segments

There currently are three types of segments in the URL:

• Built-in
• Static
• User-defined

Built-in segments

These segments are provided by the framework and cannot be overridden. They are:

• {controller}
• {action}
• {id}
• {lang}

This means, you can reorder the combination of standard routing as desired.

If the {lang} is put into the route it can be retrieved in the controller action with language(). This is a convenient way of making a single page localisation aware, when the whole application need not be. See more on localisation.

Static segments

These are just plain text in the URL. As they are mapped directly one-to-one, the URL needs to be exact before it can be matched to a route.

// "/hello" is the static segment here
route("/{action}/hello/{name}").to(IndexController.class);

User-defined segments

These are dynamic segments defined by the user, which means everything in curly brackets not being the built-in segments:

// here "/{name}" is the dynamic user-defined segment
route("/{action}/hello/{name}").to(IndexController.class);

These segments can be fetched in an action as though they were regular parameters:

public void getName() {
	respond().text("Hello {0}", param("name"));
}

Wild card routing

Sometimes longer segments are needed and to adhere to general REST-principles, these segments might need some forward slashes, which would clash with the breakdown of segments by the router.

In such cases a wild card can be used:

route("/language/{lang}/*long_id").get().action("lang").to(SomeController.class);

Notice the build up of the route. It points to the action getLang() because of .get().action("lang"). It could also be .post().action("lang") which only would be routed if the HTTP method was POST and the action was postLang(). Read more about HTTP method handling.

If the following URL was submitted it would be catched by the stated route:

/language/British/2011/12/24-some-long-post-title

If the controller action looked like this:

public class SomeController extends ApplicationController {
    public void getLang() {
        respond().text("language is {0} - param id: {1}", language(), param("long_id"));
    }
}

The output would be:

language is British - param id: 2011/12/24-some-long-post-title

Ignore routes

The automated excluding mechanism of static content described in static content is just one way to ignore certain routes.

It is also possible to explicit state certain routes to be ignored and thus be handled by some other dispatcher in the filter chain:

ignore("/some/route").exceptIn("development");

This example shows the option to only ignore some routes in production. This might come in handy when testing some new functionality or restricting access.