LibraryLink ToToggle FramesPrintFeedback

Chapter 3. Using JAVA REST Annotations

While the convention-based REST mappings provide an easy way to create a service that maintains a collection of data, or looks like it does, it does not provide the flexibility to create a full range of RESTful services that require operations whose names don't fit into the CRUD format. FUSE Services Framework provides a collection of annotations that allows you to define the mapping of an operation to an HTTP verb/URI combination. The REST annotations allow you to specify which verb to use for an operation and to specify a template for creating a URI for the exposed resource.

FUSE Services Framework uses four annotations for specifying the HTTP verb that will be used for a method:

When you map your methods to HTTP verbs, you must ensure that the mapping makes sense. For example, if you map a method that is intended to submit a purchase order, you would map it to a PUT or a POST. Mapping it to a GET or a DELETE would result in unpredictable behavior.

You specify the URI of the resource using the org.codehaus.jra.HttpResource annotation. HttpResource has one required attribute, location, that specifies the location of the resource in relationship to the base URI specified when publishing the service (see Chapter 4, Publishing a RESTful Service. For example, if you specify carts as the location of the resource and the base URI is http://myexample.iona.org, the full URI for the resource will be http://myexample.iona.org/carts.

In addition to specifying hard coded resource locations, FUSE Services Framework provides a facility for creating URIs on the fly using either the method's parameters or a field from the JAXB bean in the parameter list. When providing a value for the HttpResource annotation's location parameter you provide a URI template using the syntax in Example 3.1, “URI Template Syntax”.


resourceName can be any valid string, and forms the base of the location. Each param is the name of either a method parameter or a field in the JAXB bean in the parameter list. To create the URI, FUSE Services Framework replaces param with the value of the associated parameter. For example, if you have the method shown in Example 3.2, “Using a URI Template” and wanted to access the record at id 42, you would perform a GET at http://myexample.iona.com/records/42.


[Important]Important

FUSE Services Framework only supports XML primitives in URI templates.

If you wanted to implement a system for ordering widgets out of the catalog defined by Example 2.1, “Widget Catalog CRUD Class” you may use an SEI like the one shown in Example 3.3, “SEI for a Widget Ordering Service”.


WidgetOrdering does not match any of the naming conventions outlined in Chapter 2, Using Automatic REST Mappings so the RESTful binding cannot automatically map the methods to verb/URI combinations. You will need to provide the mappings using the Java REST annotations. To do this, you need to consider what each method in the interface does and how it correlates to one of the HTTP verbs:

  • placeOrder() creates a new order on the system. Resource creation correlates with POST.

  • checkOrder() looks up an order's status and returns it to the user. Returning resources correlates with GET.

  • changeOrder() updates an order that has already been placed. Updating an existing record correlates with PUT.

  • cancelOrder() removes an order from the system. Removing a resource correlates with DELETE.

For the URI, you would use a resource name that hinted at the purpose of the resource. For this example, the resource name used is orders because it is assumed that the base URI at which the endpoint is published provides information about what is being ordered. For the methods that use orderNum to identify a particular order, URI templating is used to append the value of the parameter to the end of the URI.

Example 3.4, “WidgetOrdering with REST Annotations” shows WidgetOrdering with the required annotations.


To check the status of order number 236, you would perform a GET at baseURI/orders/236.