Chapter 18. Configuring JAX-RS Endpoints

Abstract

This chapter explains how to instantiate and configure JAX-RS server endpoints in Blueprint XML and in Spring XML, and also how to instantiate and configure JAX-RS client endpoints (client proxy beans) in XML

18.1. Configuring JAX-RS Server Endpoints

18.1.1. Defining a JAX-RS Server Endpoint

Basic server endpoint definition

To define a JAX-RS server endpoint in XML, you need to specify at least the following:

A jaxrs:server element, which is used to define the endpoint in XML. Note that the jaxrs: namespace prefix maps to different namespaces in Blueprint and in Spring respectively.
The base URL of the JAX-RS service, using the address attribute of the jaxrs:server element. Note that there are two different ways of specifying the address URL, which affects how the endpoint gets deployed:
- As a relative URL—for example, /customers. In this case, the endpoint is deployed into the default HTTP container, and the endpoint’s base URL is implicitly obtained by combining the CXF servlet base URL with the specified relative URL.
  For example, if you deploy a JAX-RS endpoint to the Fuse container, the specified /customers URL would get resolved to the URL, http://Hostname:8181/cxf/customers (assuming that the container is using the default 8181 port).
- As an absolute URL — for example, http://0.0.0.0:8200/cxf/customers. In this case, a new HTTP listener port is opened for the JAX-RS endpoint (if it is not already open). For example, in the context of Fuse, a new Undertow container would implicitly be created to host the JAX-RS endpoint. The special IP address, 0.0.0.0, acts as a wildcard, matching any of the hostnames assigned to the current host (which can be useful on multi-homed host machines).
One or more JAX-RS root resource classes, which provide the implementation of the JAX-RS service. The simplest way to specify the resource classes is to list them inside a jaxrs:serviceBeans element.

Blueprint example

The following Blueprint XML example shows how to define a JAX-RS endpoint, which specifies the relative address, /customers (so that it deploys into the default HTTP container) and is implemented by the service.CustomerService resource class:

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:jaxrs="http://cxf.apache.org/blueprint/jaxrs"
    xmlns:cxf="http://cxf.apache.org/blueprint/core"
    xsi:schemaLocation="
http://www.osgi.org/xmlns/blueprint/v1.0.0 https://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd
http://cxf.apache.org/blueprint/jaxrs http://cxf.apache.org/schemas/blueprint/jaxrs.xsd
http://cxf.apache.org/blueprint/core http://cxf.apache.org/schemas/blueprint/core.xsd
">

    <cxf:bus>
        <cxf:features>
            <cxf:logging/>
        </cxf:features>
    </cxf:bus>

     <jaxrs:server id="customerService" address="/customers">
        <jaxrs:serviceBeans>
           <ref component-id="serviceBean" />
        </jaxrs:serviceBeans>
     </jaxrs:server>

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

Blueprint XML namespaces

To define a JAX-RS endpoint in Blueprint, you typically require at least the following XML namespaces:

Prefix	Namespace
(default)	`http://www.osgi.org/xmlns/blueprint/v1.0.0`
`cxf`	`http://cxf.apache.org/blueprint/core`
`jaxrs`	`http://cxf.apache.org/blueprint/jaxrs`

Spring example

The following Spring XML example shows how to define a JAX-RS endpoint, which specifies the relative address, /customers (so that it deploys into the default HTTP container) and is implemented by the service.CustomerService resource class:

<beans xmlns="http://www.springframework.org/schema/beans"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:jaxrs="http://cxf.apache.org/jaxrs"
      xsi:schemaLocation="
         http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
         http://cxf.apache.org/jaxrs http://cxf.apache.org/schemas/jaxrs.xsd">

     <jaxrs:server id="customerService" address="/customers">
        <jaxrs:serviceBeans>
           <ref bean="serviceBean"/>
        </jaxrs:serviceBeans>
     </jaxrs:server>

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

Spring XML namespaces

To define a JAX-RS endpoint in Spring, you typically require at least the following XML namespaces:

Prefix	Namespace
(default)	`http://www.springframework.org/schema/beans`
`cxf`	`http://cxf.apache.org/core`
`jaxrs`	`http://cxf.apache.org/jaxrs`

Auto-discovery in Spring XML

(Spring only) Instead of specifying the JAX-RS root resource classes explicitly, Spring XML enables you to configure auto-discovery, so that specific Java packages are searched for resource classes (classes annotated by @Path) and all of the discovered resource classes are automatically attached to the endpoint. In this case, you need to specify just the address attribute and the basePackages attribute in the jaxrs:server element.

For example, to define a JAX-RS endpoint which uses all of the JAX-RS resource classes under the a.b.c Java package, you can define the endpoint in Spring XML, as follows:

<jaxrs:server address="/customers" basePackages="a.b.c"/>

The auto-discovery mechanism also discovers and installs into the endpoint any JAX-RS provider classes that it finds under the specified Java packages.

Lifecycle management in Spring XML

(Spring only) Spring XML enables you to control the lifecycle of beans by setting the scope attribute on a bean element. The following scope values are supported by Spring:

singleton: (Default) Creates a single bean instance, which is used everywhere and lasts for the entire lifetime of the Spring container.
prototype: Creates a new bean instance every time the bean is injected into another bean or when a bean is obtained by invoking getBean() on the bean registry.
request: (Only available in a Web-aware container) Creates a new bean instance for every request invoked on the bean.
session: (Only available in a Web-aware container) Creates a new bean for the lifetime of a single HTTP session.
globalSession: (Only available in a Web-aware container) Creates a new bean for the lifetime of a single HTTP session that is shared between portlets.

For more details about Spring scopes, please consult the Spring framework documentation on Bean scopes.

Note that Spring scopes do not work properly, if you specify JAX-RS resource beans through the jaxrs:serviceBeans element. If you specify the scope attribute on the resource beans in this case, the scope attribute is effectively ignored.

In order to make bean scopes work properly within a JAX-RS server endpoint, you require a level of indirection that is provided by a service factory. The simplest way to configure bean scopes is to specify resource beans using the beanNames attribute on the jaxrs:server element, as follows:

<beans ... >
  <jaxrs:server id="customerService" address="/service1"
    beanNames="customerBean1 customerBean2"/>

  <bean id="customerBean1" class="demo.jaxrs.server.CustomerRootResource1" scope="prototype"/>
  <bean id="customerBean2" class="demo.jaxrs.server.CustomerRootResource2"  scope="prototype"/>
</beans>

Where the preceding example configures two resource beans, customerBean1 and customerBean2. The beanNames attribute is specified as a space-separated list of resource bean IDs.

For the ultimate degree of flexibility, you have the option of defining service factory objects explicitly, when you configure the JAX-RS server endpoint, using the jaxrs:serviceFactories element. This more verbose approach has the advantage that you can replace the default service factory implementation with your custom implementation, thus giving you ultimate control over the bean lifecycle. The following example shows how to configure the two resource beans, customerBean1 and customerBean2, using this approach:

<beans ... >
  <jaxrs:server id="customerService" address="/service1">
    <jaxrs:serviceFactories>
      <ref bean="sfactory1" />
      <ref bean="sfactory2" />
    </jaxrs:serviceFactories>
  </jaxrs:server>

  <bean id="sfactory1" class="org.apache.cxf.jaxrs.spring.SpringResourceFactory">
     <property name="beanId" value="customerBean1"/>
  </bean>
  <bean id="sfactory2" class="org.apache.cxf.jaxrs.spring.SpringResourceFactory">
     <property name="beanId" value="customerBean2"/>
  </bean>

  <bean id="customerBean1" class="demo.jaxrs.server.CustomerRootResource1" scope="prototype"/>
  <bean id="customerBean2" class="demo.jaxrs.server.CustomerRootResource2"  scope="prototype"/>
</beans>

Note

If you specify a non-singleton lifecycle, it is often a good idea to implement and register a org.apache.cxf.service.Invoker bean (where the instance can be registered by referencing it from a jaxrs:server/jaxrs:invoker element).

Attaching a WADL document

You can optionally associate a WADL document with the JAX-RS server endpoint using the docLocation attribute on the jaxrs:server element. For example:

<jaxrs:server address="/rest" docLocation="wadl/bookStore.wadl">
   <jaxrs:serviceBeans>
      <bean class="org.bar.generated.BookStore"/>
   </jaxrs:serviceBeans>
</jaxrs:server>

Schema validation

If you have some external XML schemas, for describing message content in JAX-B format, you can associate these external schemas with the JAX-RS server endpoint through the jaxrs:schemaLocations element.

For example, if you have associated the server endpoint with a WADL document and you also want to enable schema validation on incoming messages, you can specify associated XML schema files as follows:

<jaxrs:server address="/rest"
              docLocation="wadl/bookStore.wadl">
   <jaxrs:serviceBeans>
     <bean class="org.bar.generated.BookStore"/>
   </jaxrs:serviceBeans>
   <jaxrs:schemaLocations>
     <jaxrs:schemaLocation>classpath:/schemas/a.xsd</jaxrs:schemaLocation>
     <jaxrs:schemaLocation>classpath:/schemas/b.xsd</jaxrs:schemaLocation>
   </jaxrs:schemaLocations>
</jaxrs:server>

Alternatively, if you want to include all of the schema files, *.xsd, in a given directory, you can just specify the directory name, as follows:

<jaxrs:server address="/rest"
              docLocation="wadl/bookStore.wadl">
   <jaxrs:serviceBeans>
     <bean class="org.bar.generated.BookStore"/>
   </jaxrs:serviceBeans>
   <jaxrs:schemaLocations>
     <jaxrs:schemaLocation>classpath:/schemas/</jaxrs:schemaLocation>
   </jaxrs:schemaLocations>
</jaxrs:server>

Specifying schemas in this way is generally useful for any kind of functionality that requires access to the JAX-B schemas.

Specifying the data binding

You can use the jaxrs:dataBinding element to specify the data binding that encodes the message body in request and reply messages. For example, to specify the JAX-B data binding, you could configure a JAX-RS endpoint as follows:

<jaxrs:server id="jaxbbook" address="/jaxb">
  <jaxrs:serviceBeans>
    <ref bean="serviceBean" />
  </jaxrs:serviceBeans>
  <jaxrs:dataBinding>
    <bean class="org.apache.cxf.jaxb.JAXBDataBinding"/>
  </jaxrs:dataBinding>
</jaxrs:server>>

Or to specify the Aegis data binding, you could configure a JAX-RS endpoint as follows:

<jaxrs:server id="aegisbook" address="/aegis">
  <jaxrs:serviceBeans>
    <ref bean="serviceBean" />
  </jaxrs:serviceBeans>
  <jaxrs:dataBinding>
    <bean class="org.apache.cxf.aegis.databinding.AegisDatabinding">
      <property name="aegisContext">
        <bean class="org.apache.cxf.aegis.AegisContext">
          <property name="writeXsiTypes" value="true"/>
        </bean>
      </property>
    </bean>
  </jaxrs:dataBinding>
</jaxrs:server>

Using the JMS transport

It is possible to configure JAX-RS to use a JMS messaging library as a transport protocol, instead of HTTP. Because JMS itself is not a transport protocol, the actual messaging protocol depends on the particular JMS implementation that you configure.

For example, the following Spring XML example shows how to configure a JAX-RS server endpoint to use the JMS transport protocol:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:jms="http://cxf.apache.org/transports/jms"
       xmlns:jaxrs="http://cxf.apache.org/jaxrs"
       xsi:schemaLocation="
http://cxf.apache.org/transports/jms http://cxf.apache.org/schemas/configuration/jms.xsd
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
http://cxf.apache.org/jaxrs http://cxf.apache.org/schemas/jaxrs.xsd">

    <bean class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer"/>
    <bean id="ConnectionFactory" class="org.apache.activemq.ActiveMQConnectionFactory">
        <property name="brokerURL" value="tcp://localhost:${testutil.ports.EmbeddedJMSBrokerLauncher}" />
    </bean>

    <jaxrs:server xmlns:s="http://books.com"
    	serviceName="s:BookService"
    	transportId= "http://cxf.apache.org/transports/jms"
    	address="jms:queue:test.jmstransport.text?replyToName=test.jmstransport.response">
        <jaxrs:serviceBeans>
            <bean class="org.apache.cxf.systest.jaxrs.JMSBookStore"/>
        </jaxrs:serviceBeans>
    </jaxrs:server>

</beans>

Note the following points about the preceding example:

JMS implementation—the JMS implementation is provided by the ConnectionFactory bean, which instantiates an Apache ActiveMQ connection factory object. After you instantiate the connection factory, it is automatically installed as the default JMS implementation layer.
JMS conduit or destination object—Apache CXF implicitly instantiates a JMS conduit object (to represent a JMS consumer) or a JMS destination object (to represent a JMS provider). This object must be uniquely identified by a QName, which is defined through the attribute setttings xmlns:s="http://books.com" (defining the namespace prefix) and serviceName="s:BookService" (defining the QName).
Transport ID—to select the JMS transport, the transportId attribute must be set to http://cxf.apache.org/transports/jms.
JMS address—the jaxrs:server/@address attribute uses a standardized syntax to specify the JMS queue or JMS topic to send to. For details of this syntax, see https://tools.ietf.org/id/draft-merrick-jms-uri-06.txt.

Extension mappings and language mappings

A JAX-RS server endpoint can be configured so that it automatically maps a file suffix (appearing in the URL) to a MIME content type header, and maps a language suffix to a language type header. For example, consider a HTTP request of the following form:

GET /resource.xml

You can configure the JAX-RS server endpoint to map the .xml suffix automatically, as follows:

<jaxrs:server id="customerService" address="/">
  <jaxrs:serviceBeans>
    <bean class="org.apache.cxf.jaxrs.systests.CustomerService" />
  </jaxrs:serviceBeans>
  <jaxrs:extensionMappings>
    <entry key="json" value="application/json"/>
    <entry key="xml" value="application/xml"/>
  </jaxrs:extensionMappings>
</jaxrs:server>

When the preceding server endpoint receives the HTTP request, it automatically creates a new content type header of type, application/xml, and strips the .xml suffix from the resource URL.

For the language mapping, consider a HTTP request of the following form:

GET /resource.en

You can configure the JAX-RS server endpoint to map the .en suffix automatically, as follows:

<jaxrs:server id="customerService" address="/">
  <jaxrs:serviceBeans>
    <bean class="org.apache.cxf.jaxrs.systests.CustomerService" />
  </jaxrs:serviceBeans>
  <jaxrs:languageMappings>
     <entry key="en" value="en-gb"/>
  </jaxrs:languageMappings>
</jaxrs:server>

When the preceding server endpoint receives the HTTP request, it automatically creates a new accept language header with the value, en-gb, and strips the .en suffix from the resource URL.

18.1.2. jaxrs:server Attributes

Attributes

Table 18.1, “JAX-RS Server Endpoint Attributes” describes the attributes available on the jaxrs:server element.

Table 18.1. JAX-RS Server Endpoint Attributes
Attribute	Description
`id`	Specifies a unique identifier that other configuration elements can use to refer to the endpoint.
`address`	Specifies the address of an HTTP endpoint. This value will override the value specified in the services contract.
`basePackages`	(Spring only) Enables auto-discovery, by specifying a comma-separated list of Java packages, which are searched to discover JAX-RS root resource classes and/or JAX-RS provider classes.
`beanNames`	Specifies a space-separated list of bean IDs of JAX-RS root resource beans. In the context of Spring XML, it is possible to define a root resource beans' lifecycle by setting the `scope` attribute on the root resource `bean` element.
`bindingId`	Specifies the ID of the message binding the service uses. A list of valid binding IDs is provided in Chapter 23, Apache CXF Binding IDs.
`bus`	Specifies the ID of the Spring bean configuring the bus used to manage the service endpoint. This is useful when configuring several endpoints to use a common set of features.
`docLocation`	Specifies the location of an external WADL document.
`modelRef`	Specifies a model schema as a classpath resource (for example, a URL of the form `classpath:/path/to/model.xml`). For details of how to define a JAX-RS model schema, see Section 18.3, “Defining REST Services with the Model Schema”.
`publish`	Specifies if the service should be automatically published. If set to `false`, the developer must explicitly publish the endpoint.
`publishedEndpointUrl`	Specifies the URL base address, which gets inserted into the `wadl:resources/@base` attribute of the auto-generated WADL interface.
`serviceAnnotation`	(Spring only) Specifies the service annotation class name for auto-discovery in Spring. When used in combination with the `basePackages` property, this option restricts the collection of auto-discovered classes to include only the classes that are annotated by this annotation type. guess!! Is this correct?
`serviceClass`	Specifies the name of a JAX-RS root resource class (which implements a JAX-RS service). In this case, the class is instantiated by Apache CXF, not by Blueprint or Spring. If you want to instantiate the class in Blueprint or Spring, use the `jaxrs:serviceBeans` child element instead.
`serviceName`	Specifies the service QName (using the format `ns:name`) for the JAX-RS endpoint in the special case where a JMS transport is used. For details, see the section called “Using the JMS transport”.
`staticSubresourceResolution`	If `true`, disables dynamic resolution of static sub-resources. Default is `false`.
`transportId`	For selecting a non-standard transport layer (in place of HTTP). In particular, you can select the JMS transport by setting this property to `http://cxf.apache.org/transports/jms`. For details, see the section called “Using the JMS transport”.
`abstract`	(Spring only) Specifies if the bean is an abstract bean. Abstract beans act as parents for concrete bean definitions and are not instantiated. The default is `false`. Setting this to `true` instructs the bean factory not to instantiate the bean.
`depends-on`	(Spring only) Specifies a list of beans that the endpoint depends on being instantiated before the endpoint can be instantiated.

18.1.3. jaxrs:server Child Elements

Child elements

Table 18.2, “JAX-RS Server Endpoint Child Elements” describes the child elements of the jaxrs:server element.

Table 18.2. JAX-RS Server Endpoint Child Elements
Element	Description
`jaxrs:executor`	Specifies a Java `Executor` (thread pool implementation) that is used for the service. This is specified using an embedded bean definition.
`jaxrs:features`	Specifies a list of beans that configure advanced features of Apache CXF. You can provide either a list of bean references or a list of embedded beans.
`jaxrs:binding`	Not used.
`jaxrs:dataBinding`	Specifies the class implementing the data binding used by the endpoint. This is specified using an embedded bean definition. For more details, see the section called “Specifying the data binding”.
`jaxrs:inInterceptors`	Specifies a list of interceptors that process inbound requests. For more information see Part VII, “Developing Apache CXF Interceptors”.
`jaxrs:inFaultInterceptors`	Specifies a list of interceptors that process inbound fault messages. For more information see Part VII, “Developing Apache CXF Interceptors”.
`jaxrs:outInterceptors`	Specifies a list of interceptors that process outbound replies. For more information see Part VII, “Developing Apache CXF Interceptors”.
`jaxrs:outFaultInterceptors`	Specifies a list of interceptors that process outbound fault messages. For more information see Part VII, “Developing Apache CXF Interceptors”.
`jaxrs:invoker`	Specifies an implementation of the org.apache.cxf.service.Invoker interface used by the service. ^[a]
`jaxrs:serviceFactories`	Provides you with the maximum degree of control over the lifecycle of the JAX-RS root resources associated with this endpoint. The children of this element (which must be instances of `org.apache.cxf.jaxrs.lifecycle.ResourceProvider` type) are used to create JAX-RS root resource instances.
`jaxrs:properties`	Specifies a Spring map of properties that are passed along to the endpoint. These properties can be used to control features like enabling MTOM support.
`jaxrs:serviceBeans`	The children of this element are instances of (`bean` element) or references to (`ref` element) JAX-RS root resources. Note that in this case the `scope` attribute (Spring only), if present in the `bean` element, is ignored.
`jaxrs:modelBeans`	Consists of a list of references to one or more `org.apache.cxf.jaxrs.model.UserResource` beans, which are the basic elements of a resource model (corresponding to `jaxrs:resource` elements). For details, see Section 18.3, “Defining REST Services with the Model Schema”.
`jaxrs:model`	Defines a resource model directly in this endpoint (that is, this `jaxrs:model` element can contain one or more `jaxrs:resource` elements). For details, see Section 18.3, “Defining REST Services with the Model Schema”.
`jaxrs:providers`	Enables you to register one or more custom JAX-RS providers with this endpoint. The children of this element are instances of (`bean` element) or references to (`ref` element) JAX-RS providers.
`jaxrs:extensionMappings`	When the URL of a REST invocation ends in a file extension, you can use this element to associate it automatically with a particular content type. For example, the `.xml` file extension could be associated with the `application/xml` content type. For details, see the section called “Extension mappings and language mappings”.
`jaxrs:languageMappings`	When the URL of a REST invocation ends in a language suffix, you can use this element to map this to a particular language. For example, the `.en` language suffix could be associated with the `en-GB` language. For details, see the section called “Extension mappings and language mappings”.
`jaxrs:schemaLocations`	Specifies one or more XML schemas used for validating XML message content. This element can contain one or more `jaxrs:schemaLocation` elements, each specifying the location of an XML schema file (usually as a `classpath` URL). For details, see the section called “Schema validation”.
`jaxrs:resourceComparator`	Enables you to register a custom resource comparator, which implements the algorithm used to match an incoming URL path to a particular resource class or method.
`jaxrs:resourceClasses`	(Blueprint only) Can be used instead of the `jaxrs:server/@serviceClass` attribute, if you want to create multiple resources from class names. The children of `jaxrs:resourceClasses` must be `class` elements with a `name` attribute set to the name of the resource class. In this case, the classes are instantiated by Apache CXF, not by Blueprint or Spring.
^[a] The Invoker implementation controls how a service is invoked. For example, it controls whether each request is handled by a new instance of the service implementation or if state is preserved across invocations.

18.2. Configuring JAX-RS Client Endpoints

18.2.1. Defining a JAX-RS Client Endpoint

Injecting client proxies

The main point of instantiating a client proxy bean in an XML language (Blueprint XML or Spring XML) is in order to inject it into another bean, which can then use the client proxy to invoke the REST service. To create a client proxy bean in XML, use the jaxrs:client element.

Namespaces

The JAX-RS client endpoint is defined using a different XML namespace from the server endpoint. The following table shows which namespace to use for which XML language:

XML Language	Namespace for client endpoint
Blueprint	`http://cxf.apache.org/blueprint/jaxrs-client`
Spring	`http://cxf.apache.org/jaxrs-client`

Basic client endpoint definition

The following example shows how to create a client proxy bean in Blueprint XML or Spring XML:

<jaxrs:client id="restClient"
       address="http://localhost:8080/test/services/rest"
       serviceClass="org.apache.cxf.systest.jaxrs.BookStoreJaxrsJaxws"/>

Where you must set the following attributes to define the basic client endpoint:

id: The bean ID of the client proxy can be used to inject the client proxy into other beans in your XML configuration.
address: The address attribute specifies the base URL of the REST invocations.
serviceClass: The serviceClass attribute provides a description of the REST service by specifying a root resource class (annotated by @Path). In fact, this is a server class, but it is not used directly by the client. The specified class is used only for its metadata (through Java reflection and JAX-RS annotations), which is used to construct the client proxy dynamically.

Specifying headers

You can add HTTP headers to the client proxy’s invocations using the jaxrs:headers child elements, as follows:

<jaxrs:client id="restClient"
       address="http://localhost:8080/test/services/rest"
       serviceClass="org.apache.cxf.systest.jaxrs.BookStoreJaxrsJaxws"
       inheritHeaders="true">
       <jaxrs:headers>
           <entry key="Accept" value="text/xml"/>
       </jaxrs:headers>
</jaxrs:client>

18.2.2. jaxrs:client Attributes

Attributes

Table 18.3, “JAX-RS Client Endpoint Attributes” describes the attributes available on the jaxrs:client element.

Table 18.3. JAX-RS Client Endpoint Attributes
Attribute	Description
`address`	Specifies the HTTP address of the endpoint where the consumer will make requests. This value overrides the value set in the contract.
`bindingId`	Specifies the ID of the message binding the consumer uses. A list of valid binding IDs is provided in Chapter 23, Apache CXF Binding IDs.
`bus`	Specifies the ID of the Spring bean configuring the bus managing the endpoint.
`inheritHeaders`	Specifies whether the headers set for this proxy will be inherited, if a subresource proxy is created from this proxy. Default is `false`.
`username`	Specifies the username used for simple username/password authentication.
`password`	Specifies the password used for simple username/password authentication.
`modelRef`	Specifies a model schema as a classpath resource (for example, a URL of the form `classpath:/path/to/model.xml`). For details of how to define a JAX-RS model schema, see Section 18.3, “Defining REST Services with the Model Schema”.
`serviceClass`	Specifies the name of a service interface or a resource class (that is annotated with `@PATH`), re-using it from the JAX-RS server implementation. In this case, the specified class is not invoked directly (it is actually a server class). The specified class is used only for its metadata (through Java reflection and JAX-RS annotations), which is used to construct the client proxy dynamically.
`serviceName`	Specifies the service QName (using the format `ns:name`) for the JAX-RS endpoint in the special case where a JMS transport is used. For details, see the section called “Using the JMS transport”.
`threadSafe`	Specifies whether or not the client proxy is thread-safe. Default is `false`.
`transportId`	For selecting a non-standard transport layer (in place of HTTP). In particular, you can select the JMS transport by setting this property to `http://cxf.apache.org/transports/jms`. For details, see the section called “Using the JMS transport”.
`abstract`	(Spring only) Specifies if the bean is an abstract bean. Abstract beans act as parents for concrete bean definitions and are not instantiated. The default is `false`. Setting this to `true` instructs the bean factory not to instantiate the bean.
`depends-on`	(Spring only) Specifies a list of beans that the endpoint depends on being instantiated before it can be instantiated.

18.2.3. jaxrs:client Child Elements

Child elements

Table 18.4, “JAX-RS Client Endpoint Child Elements” describes the child elements of the jaxrs:client element.

Table 18.4. JAX-RS Client Endpoint Child Elements
Element	Description
`jaxrs:executor`
`jaxrs:features`	Specifies a list of beans that configure advanced features of Apache CXF. You can provide either a list of bean references or a list of embedded beans.
`jaxrs:binding`	Not used.
`jaxrs:dataBinding`	Specifies the class implementing the data binding used by the endpoint. This is specified using an embedded bean definition. For more details, see the section called “Specifying the data binding”.
`jaxrs:inInterceptors`	Specifies a list of interceptors that process inbound responses. For more information see Part VII, “Developing Apache CXF Interceptors”.
`jaxrs:inFaultInterceptors`	Specifies a list of interceptors that process inbound fault messages. For more information see Part VII, “Developing Apache CXF Interceptors”.
`jaxrs:outInterceptors`	Specifies a list of interceptors that process outbound requests. For more information see Part VII, “Developing Apache CXF Interceptors”.
`jaxrs:outFaultInterceptors`	Specifies a list of interceptors that process outbound fault messages. For more information see Part VII, “Developing Apache CXF Interceptors”.
`jaxrs:properties`	Specifies a map of properties that are passed to the endpoint.
`jaxrs:providers`	Enables you to register one or more custom JAX-RS providers with this endpoint. The children of this element are instances of (`bean` element) or references to (`ref` element) JAX-RS providers.
`jaxrs:modelBeans`	Consists of a list of references to one or more `org.apache.cxf.jaxrs.model.UserResource` beans, which are the basic elements of a resource model (corresponding to `jaxrs:resource` elements). For details, see Section 18.3, “Defining REST Services with the Model Schema”.
`jaxrs:model`	Defines a resource model directly in this endpoint (that is, a `jaxrs:model` element containing one or more `jaxrs:resource` elements). For details, see Section 18.3, “Defining REST Services with the Model Schema”.
`jaxrs:headers`	Used for setting headers on the outgoing message. For details, see the section called “Specifying headers”.
`jaxrs:schemaLocations`	Specifies one or more XML schemas used for validating XML message content. This element can contain one or more `jaxrs:schemaLocation` elements, each specifying the location of an XML schema file (usually as a `classpath` URL). For details, see the section called “Schema validation”.

18.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 18.1, “Sample JAX-RS Model Schema” shows an example of a model schema that defines service metadata for the BookStoreNoAnnotations root resource class.

Example 18.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).
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.
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).
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:

Attribute	Description +
`name`	The name of the resource class (or corresponding interface) to which this resource model is applied. +
`path`	The component of the REST URL path that maps to this resource. +
`consumes`	Specifies the content type (Internet media type) consumed by this resource—for example, `application/xml` or `application/json`. +
`produces`	Specifies 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:

Attribute	Description +
`name`	The name of the Java method to which this element is applied. +
`path`	The 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. +
`verb`	Specifies 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). +
`consumes`	Specifies the content type (Internet media type) consumed by this operation—for example, `application/xml` or `application/json`. +
`produces`	Specifies the content type (Internet media type) produced by this operation—for example, `application/xml` or `application/json`. +
`oneway`	If `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:

Attribute	Description +
`name`	The name of the Java method parameter to which this element is applied. +
`type`	Specifies 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`. +
`defaultValue`	Default value to inject into the parameter, in case a value could not be extracted from the REST URL or message. +
`encoded`	If `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`. +

Chapter 18. Configuring JAX-RS Endpoints

18.1. Configuring JAX-RS Server Endpoints

18.1.1. Defining a JAX-RS Server Endpoint

Basic server endpoint definition

Blueprint example

Blueprint XML namespaces

Spring example

Spring XML namespaces

Auto-discovery in Spring XML

Lifecycle management in Spring XML

Attaching a WADL document

Schema validation

Specifying the data binding

Using the JMS transport

Extension mappings and language mappings

18.1.2. jaxrs:server Attributes

Attributes

18.1.3. jaxrs:server Child Elements

Child elements

18.2. Configuring JAX-RS Client Endpoints

18.2.1. Defining a JAX-RS Client Endpoint

Injecting client proxies

Namespaces

Basic client endpoint definition

Specifying headers

18.2.2. jaxrs:client Attributes

Attributes

18.2.3. jaxrs:client Child Elements

Child elements

18.3. Defining REST Services with the Model Schema

RESTful services without annotations

Example model schema

Namespaces

How to attach a model schema to an endpoint

Configuration of model schema referencing a class

Configuration of model schema referencing an interface

Model Schema Reference

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Red Hat legal and privacy links

Red Hat legal and privacy links