Red Hat Training

A Red Hat training course is available for Red Hat Fuse

16.2. Configuring JAX-RS Client Endpoints

16.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 LanguageNamespace for client endpoint
Blueprinthttp://cxf.apache.org/blueprint/jaxrs-client
Springhttp://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>

16.2.2. jaxrs:client Attributes

Attributes

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

Table 16.3. JAX-RS Client Endpoint Attributes

AttributeDescription
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 Appendix C, Apache CXF Binding IDs.
busSpecifies the ID of the Spring bean configuring the bus managing the endpoint.
inheritHeadersSpecifies 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.
modelRefSpecifies 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 16.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”.
threadSafeSpecifies whether or not the client proxy is thread-safe. Default is false.
transportIdFor 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.

16.2.3. jaxrs:client Child Elements

Child elements

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

Table 16.4. JAX-RS Client Endpoint Child Elements

ElementDescription
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:propertiesSpecifies a map of properties that are passed to the endpoint.
jaxrs:providersEnables 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:modelBeansConsists 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 16.3, “Defining REST Services with the Model Schema”.
jaxrs:modelDefines a resource model directly in this endpoint (that is, a jaxrs:model element containing one or more jaxrs:resource elements). For details, see Section 16.3, “Defining REST Services with the Model Schema”.
jaxrs:headersUsed for setting headers on the outgoing message. For details, see the section called “Specifying headers”.
jaxrs:schemaLocationsSpecifies 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”.