Earthly Powers

The UriTemplate annotation

URI templates are a fundamental part of RESTful API in SWDP.

The UriTemplate annotation enables the developer to declare what POJOs are Web resources, for example:

@UriTemplate("/feed/{entry}")
class EntryResource {
    @HttpMethod("GET")
    Representation<Entry> getEntry(@UriParam("entry") int entry) {
        ...
    }
} 

The POJO, EntryResource, is annotated with the URI template "/feed/{entry}", thus HTTP requests with URI paths that match this template, such as  "/feed/myentry" or  "/feed/1234" will be dispatched to this POJO.

However, not all paths will be accepted as it depends on how the URI template value obtained from the URI template variable, "{entry}", is processed. In this example a matching HTTP GET request, to be dispatched to the getEntry method, results in the conversion of the template value from a String to an int, as declared by the UriParam annotation on the method parameter entry. So a path of "/feed/myentry" will result in the runtime automatically responding with a 400 (Bad Request) status code. Conversion of template values can be customized by using a Java class that has either a constructor that takes a single String parameter or a static method valueOf  that returns the an instance of the Java class and takes a single String parameter.

How do all those POJOs with URI templates get deployed? If you look at the ant build script of an example, e.g. the build script of SimpleConsole example, you will notice a pre-compile target that invokes an Annotation Processor for processing POJOs with URI templates. This processor generates a Java class , in a specified package, that contains references to all the POJOs. The Main.java of the SimpleConsole example passes in that package name when creating the HTTP handler:

HttpHandler handler = 
    HttpHandlerFactory.create("com.sun.ws.rest.samples.console.resources");

The factory will instantiate that generated Java class and obtain all the POJOs to be deployed.

Posted at 03:13PM Mar 19, 2007 by Paul Sandoz in REST  |  Comments[0]