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 Language | Namespace |
|---|---|
| Blueprint | http://cxf.apache.org/blueprint/jaxrs |
| Spring | http://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:
- Define the model schema, using the appropriate XML namespace for your chosen injection platform (Blueprint XML or Spring XML).
- 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).NoteAlternatively, it is also possible to embed a model schema directly into a JAX-RS endpoint, using the endpoint's
jaxrs:modelchild element. - Configure the endpoint to use the model schema, by setting the endpoint's
modelRefattribute to the location of the model schema on the classpath (using a classpath URL). - If necessary, instantiate the root resources explicitly, using the
jaxrs:serviceBeanselement. 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
modelRefattribute), you should set theidattribute on this element. model/resource- The
resourceelement is used to associate metadata with a specific root resource class (or with a corresponding interface). You can define the following attributes on theresourceelement:Attribute Description 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/xmlorapplication/json.producesSpecifies the content type (Internet media type) produced by this resource—for example, application/xmlorapplication/json. model/resource/operation- The
operationelement is used to associate metadata with Java methods. You can define the following attributes on anoperationelement:Attribute Description 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 theidparameter from the path.verbSpecifies the HTTP verb that maps to this method. Typically one of: GET,POST,PUT, orDELETE. 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 aresourceelement).consumesSpecifies the content type (Internet media type) consumed by this operation—for example, application/xmlorapplication/json.producesSpecifies the content type (Internet media type) produced by this operation—for example, application/xmlorapplication/json.onewayIf true, configures the operation to be oneway, meaning that no reply message is needed. Defaults tofalse. model/resource/operation/param- The
paramelement 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 aparamelement:Attribute Description 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%nnencoding). Default isfalse. For example, when extracting a parameter from the URL path,/name/Joe%20Bloggswith encoded set totrue, the parameter is injected asJoe%20Bloggs; otherwise, the parameter would be injected asJoe Bloggs.
