Previous
6.22 router
'router' creates an org.restlet.Router. This is the central part of the whole router configuration.
The components created by the other routing configuration elements are
usually attached to a Router. An exception is that components can also be
attached as delegate to a
When attaching a component to a router, certain parameters can be specified, most importantly the URI, as shown in this example which creates a router with two resources attached to it:
builder.router {
resource(uri: "/user/{name}", ofClass: "mystuff.UserResource")
resource(uri: "/order/{orderId}", ofClass: "mystuff.OrderResource")
}
The uri parameter of the resources is not an attribute for the resources themselves, but for attaching the resource to the router. So certain parts of the router-related configuration are specified on the components nested inside the router. The main reason for explaining this is because this part of the configuration will be discussed here, rather than repeating it for each component.
By default, a router will match URI patterns in "starts" mode. This means the URI pattern will match for a given request URI if the request URI starts with the URI pattern. So a request URI of "/fooxyz" will be matched by the URI pattern "/foo". The matching mode can be changed for the router as a whole or for each individual route of a router. For the above example, it is better to change the match mode to "equals", like this:
builder.router(match: "equals") {
resource(uri: "/user/{name}", ofClass: "mystuff.UserResource")
resource(uri: "/order/{orderId}", ofClass: "mystuff.OrderResource")
}
Parameters for the router itself
|
Name |
Description |
|---|---|
|
type |
The kind of router to create. Supported values:
The default is "kauri". |
|
routingMode |
This parameter only applies when the router type is set to restlet. When the router type is kauri, it is always the first matching pattern which is used. Set this to one of: routingMode.BEST|CUSTOM|FIRST|LAST|NEXT|RANDOM |
|
match |
Sets the default matching mode for all Routes within this Router. Its value can be the string "equals" or "start". The default is "start". This can be overridden for each individual Route. |
todo: explain more is possible, see Restlet docs for full details.
Parameters for components attached to a router
The following are parameters which can be supplied to any sort of component attached to a router.
|
Name |
Description |
|---|---|
|
uri |
A URI pattern, in
|
|
postAttach |
A closure which will be executed after the component has been attached by the router. See detailed explanation below. |
|
match |
Sets the matching mode for this router. Its value can be the string "equals" or "start". The default is "start", though this default can be overridden by adding a match parameter on the router, see above. |
|
passThrough |
This parameter only applies when the router type is kauri. If this boolean parameter is set to true (default is false) and after the attached restlet has been called the response is "404 Not Found" and additionally the response carries an indication that the 404 is because the URI pattern is not recognized, then the router will continue the matching process with the routes that follow the current one, in sequence. The "special indication" is a response attribute org.kauriproject.routing.no_route with as value Boolean.TRUE. Various components created through the routing config support this: router, jaxRs, mode. This feature can be useful when the attached restlets perform (some sort of) routing themselves. For example, the following snippet delegates all requests to JAX-RS, and if there was no resource class to handle the request, goes on matching the routes that follow it. router {
jaxRs(uri: "", passThrough: true)
pages(uri: "", root: "pages")
}
|
Fine-grained configuration via postAttach
Attaching a component to a router creates a Route object, via this Route object various options can be set. In the routing configuration, this can be done by specifying a closure via the postAttach parameter. The name postAttach comes from the fact that it is a closure which will be called after (= post) the attaching of the component to the router. The closure takes one argument, the Route instance.
One of the more interesting things which can be done via postAttach is setting options on the Template contained in the Route. The Template object represents the URI template expression.
As an example, see this illustration from the
read(uri: "/resources/{path}", source: "module:/resources/{path}",
postAttach : { route ->
Variable variable = new Variable(Variable.TYPE_URI_PATH, "", true, false)
route.getTemplate().getVariables().put("path", variable)
})
For full information on all the capabilities, see the Restlet API documentation: Route class, Template class, Variable class.