16.3. Defining REST Services with the Model Schema

RESTful services without annotations

The JAX-RS model schema makes it possible to define RESTful services without annotating Java classes. That is, instead of adding annotations like @Path, @PathParam, @Consumes, @Produces, and so on, directly to a Java class (or interface), you can provide all of the relevant REST metadata in a separate XML file, using the model schema. This can be useful, for example, in cases where you are unable to modify the Java source that implements the service.

Example model schema

Example 16.1, “Sample JAX-RS Model Schema” shows an example of a model schema that defines service metadata for the BookStoreNoAnnotations root resource class.

Example 16.1. Sample JAX-RS Model Schema

<model xmlns="http://cxf.apache.org/jaxrs">
  <resource name="org.apache.cxf.systest.jaxrs.BookStoreNoAnnotations" path="bookstore"
    produces="application/json" consumes="application/json">
    <operation name="getBook" verb="GET" path="/books/{id}" produces="application/xml">
       <param name="id" type="PATH"/>
    </operation>
    <operation name="getBookChapter" path="/books/{id}/chapter">
       <param name="id" type="PATH"/>
    </operation>
    <operation name="updateBook" verb="PUT">
       <param name="book" type="REQUEST_BODY"/>
    </operation>
  </resource>
  <resource name="org.apache.cxf.systest.jaxrs.ChapterNoAnnotations">
    <operation name="getItself" verb="GET"/>
    <operation name="updateChapter" verb="PUT" consumes="application/xml">
        <param name="content" type="REQUEST_BODY"/>
    </operation>
  </resource>
</model>

Namespaces

The XML namespace that you use to define a model schema depends on whether you are defining the corresponding JAX-RS endpoint in Blueprint XML or in Spring XML. The following table shows which namespace to use for which XML language:
XML LanguageNamespace
Blueprinthttp://cxf.apache.org/blueprint/jaxrs
Springhttp://cxf.apache.org/jaxrs

How to attach a model schema to an endpoint

To define and attach a model schema to an endpoint, perform the following steps:
  1. Define the model schema, using the appropriate XML namespace for your chosen injection platform (Blueprint XML or Spring XML).
  2. Add the model schema file to your project's resources, so that the schema file is available on the classpath in the final package (JAR, WAR, or OSGi bundle file).
    Note
    Alternatively, it is also possible to embed a model schema directly into a JAX-RS endpoint, using the endpoint's jaxrs:model child element.
  3. Configure the endpoint to use the model schema, by setting the endpoint's modelRef attribute to the location of the model schema on the classpath (using a classpath URL).
  4. If necessary, instantiate the root resources explicitly, using the jaxrs:serviceBeans element. You can skip this step, if the model schema references root resource classes directly (instead of referencing base interfaces).

Configuration of model schema referencing a class

If the model schema applies directly to root resource classes, there is no need to define any root resource beans using the jaxrs:serviceBeans element, because the model schema automatically instantiates the root resource beans.
For example, given that customer-resources.xml is a model schema that associates metadata with customer resource classes, you could instantiate a customerService service endpoint as follows:
<jaxrs:server id="customerService"
              address="/customers"
              modelRef="classpath:/org/example/schemas/customer-resources.xml" />

Configuration of model schema referencing an interface

If the model schema applies to Java interfaces (which are the base interfaces of the root resources), you must instantiate the root resource classes using the jaxrs:serviceBeans element in the endpoint.
For example, given that customer-interfaces.xml is a model schema that associates metadata with customer interfaces, you could instantiate a customerService service endpoint as follows:
<jaxrs:server id="customerService"
              address="/customers"
              modelRef="classpath:/org/example/schemas/customer-interfaces.xml">
    <jaxrs:serviceBeans>
       <ref component-id="serviceBean" />
    </jaxrs:serviceBeans>
</jaxrs:server>

<bean id="serviceBean" class="service.CustomerService"/>

Model Schema Reference

A model schema is defined using the following XML elements:
model
Root element of the model schema. If you need to reference the model schema (for example, from a JAX-RS endpoint using the modelRef attribute), you should set the id attribute on this element.
model/resource
The resource element is used to associate metadata with a specific root resource class (or with a corresponding interface). You can define the following attributes on the resource element:
AttributeDescription
nameThe name of the resource class (or corresponding interface) to which this resource model is applied.
pathThe component of the REST URL path that maps to this resource.
consumesSpecifies the content type (Internet media type) consumed by this resource—for example, application/xml or application/json.
producesSpecifies the content type (Internet media type) produced by this resource—for example, application/xml or application/json.
model/resource/operation
The operation element is used to associate metadata with Java methods. You can define the following attributes on an operation element:
AttributeDescription
nameThe name of the Java method to which this element is applied.
pathThe component of the REST URL path that maps to this method. This attribute value can include parameter references, for example: path="/books/{id}/chapter", where {id} extracts the value of the id parameter from the path.
verbSpecifies the HTTP verb that maps to this method. Typically one of: GET, POST, PUT, or DELETE. If the HTTP verb is not specified, it is assumed that the Java method is a sub-resource locater, which returns a reference to a sub-resource object (where the sub-resource class must also be provided with metadata using a resource element).
consumesSpecifies the content type (Internet media type) consumed by this operation—for example, application/xml or application/json.
producesSpecifies the content type (Internet media type) produced by this operation—for example, application/xml or application/json.
onewayIf true, configures the operation to be oneway, meaning that no reply message is needed. Defaults to false.
model/resource/operation/param
The param element is used extract a value from the REST URL and inject it into one of the method parameters. You can define the following attributes on a param element:
AttributeDescription
nameThe name of the Java method parameter to which this element is applied.
typeSpecifies how the parameter value is extracted from the REST URL or message. It can be set to one of the following values: PATH, QUERY, MATRIX, HEADER, COOKIE, FORM, CONTEXT, REQUEST_BODY.
defaultValueDefault value to inject into the parameter, in case a value could not be extracted from the REST URL or message.
encodedIf true, the parameter value is injected in its URI encoded form (that is, using %nn encoding). Default is false. For example, when extracting a parameter from the URL path, /name/Joe%20Bloggs with encoded set to true, the parameter is injected as Joe%20Bloggs; otherwise, the parameter would be injected as Joe Bloggs.