6.3.2 The steps to introduce routing

6.3.2.1 Add the routing module to wiring.xml

In your wiring.xml file, add the following module inside the <modules> element, before any other modules where you want to make use of the routing.

<artifact id="routing"
          groupId="org.kauriproject"
          artifactId="kauri-routing-impl"/>

6.3.2.2 Import routing service in your module

Edit your module's Spring XML configuration, which can be found in the KAURI-INF/spring directory.

In your module's Spring XML configuration, add the following Java service import, which makes the RoutingService, supplied by the routing module, available within the Spring container as bean id 'routingService'.

<kauri:import-service id="routingService"
                      service="org.kauriproject.routing.RoutingService"/>

6.3.2.3 Create a router instance

We're still in your module's Spring XML configuration.

If it is not the case already, add a kauri:module tag somewhere in it. If you have already a kauri:module tag, make sure it contains at least the attributes listed below.

<kauri:module restletContext="restletContext"
              handle="module"/>

Then create the actual router by adding this:

<bean id="router" factory-bean="routingService" factory-method="createRouter">
  <constructor-arg ref="restletContext"/>
  <constructor-arg ref="module"/>
</bean>

As you can probably figure out yourself, the values of the constructor-arg's need to match the values of the attributes of the kauri:module.

6.3.2.4 Export the router as a restservice

Still in your module's Spring XML configuration:

<kauri:export-restservice name="router" ref="router"/>

6.3.2.5 Mount the exported restservice on a path

In the wiring.xml, inside the declaration of your own module, add a mount statement to mount the router on a certain URL path. Thus only the bold section should be copied in your wiring.xml file.

<artifact id="mymodule" groupId="...." artifactId="..." version="...">
  <mount name="router" path="/router"/>
</artifact>

You can of course change the "/router" path to whatever you desire, in fact "/router" is not a very good name.

6.3.2.6 Try it out

Even though we have not made an router configuration yet, you could already try out the router because a default routing configuration is used in absence of a custom one.

This default routing configuration, among other things, will make all resources in KAURI-INF/resources available on your router on the path "/resources". So suppose you create a file helloworld.txt in that resources directory, than you can already access it in your browser using the following URL:

http://localhost:8888/router/resources/helloworld.txt

Before trying this URL, you should as usual build your module (unless you're working in source mode) and restart Kauri.

6.3.2.7 Customize the routing

Now you can start customizing the routing according to your own needs. This is done by creating a file KAURI-INF/router.groovy in your module.

Here's a small example:

builder.router {
    restlet(uri: "/helloworld", handle: { request, response ->
        response.setEntity("Hello world from inside the router",
                           mediaType.TEXT_PLAIN)
    })
}

This example makes use of the ability to implement a Restlet inline in the router definition, which is not really a good and common practice (usually the restlets are implemented in separate Java classes), but is handy for this sort of examples.

The example can be accessed using:

http://localhost:8888/router/helloworld