2.10.2 About JAX-RS in Kauri

2.10.2.1 Decentralized URI management, routing

When using JAX-RS, the URI space is built by adding @Path annotations to individual classes. This is a decentralized approach to specifying the URI space: there is no central configuration file listing all the URIs (or URI patterns). By default, Kauri will automatically scan the module jar file for all classes having @Path annotations, and make them available in the URI space. The routing towards these JAX-RS resources is, as for the static resources, configured in:

module1/src/main/kauri/router.groovy

the relevant part is:

    jaxRs(uri: "") {
        jaxRsResource(scanPackages: "*")
        jaxRsProvider(scanPackages: "*")
        jaxRsGroovyScripts(path: "groovy-jax-rs")
    }

See also the jaxRs instruction reference documentation.

2.10.2.2 About the objects returned from resource methods

In the examples above, the get() method returned either a String object or a KauriRepresentation object.

If the return object is String, then the JAX-RS system itself knows how to create the response representation from this.

But the method can in fact return any kind of object, thus also your own "business objects" like Product, Order or User. JAX-RS has a mechanism of pluggable MessageBodyWriters that know how to convert a certain kind of object to a stream of bytes. See the JAX-RS API for more information on this. Registering these writers in Kauri is done through the jaxRs instruction in the routing configuration (router.groovy).

For the template sample, we returned a KauriRepresentation object. This is a special case, as it extends from Restlet's Representation class. The JAX-RS implementation of Restlet treats these in a special way, or better does not treat them at all, it simply passes them through to Restlet.

The KauriRepresentation is a special kind of representation: in fact, it only specifies a logical name for the representation to use (in the example above, "hello"), and based upon a configuration, this logical name is mapped to the actual representation to use. By default, this name is mapped onto a template to execute. See the representation builder for more information on this system.