...

...

...

Introduction

JAX-RS: Java API for RESTful Web Services is a Java programming language API that provides support in creating web services according to the Representational State Transfer (REST) architectural style.

CXF supports the Java API for RESTful Web Services: JAX-RS 2.1 (JSR-370), 2.0 (JSR-339) and JAX-RS 1.1 (JSR-311).

CXF 3.02.0 completely implements supports JAX-RS 2.0 including new Client API and has been fully tested against the first 1. All existing JAX-RS 2.0 TCK which became available to Apache. Existing JAX-RS 1.and 1.1 applications can be run with CXF 3.02.0.

CXF 2.7.0 supports most of the new features introduced in 3.1.x and 3.0.x support JAX-RS 2.0 (excluding 2.0 Client API for now - but note that CXF client API has been retrofitted to support new filters, interceptors, exception classes and Response API, plus the asynchronous client invoker API).

CXF 2.6.x supports JSR-311 API 1.1 and is JAX-RS TCK 1.1 compliant.

.  Existing JAX-RS 1.1 applications can be run with CXF 3.1.x/3.0.x.

See below for more information about the compliance.

JAX-RS related demos JAX-RS related demos are located under the samples/jax_rs directory.

This documentation will refer to Outstanding JAX-RS 2.0 (JSR-339) API.

Outstanding JAX-RS JIRA issues can be found here.

Project setup and configuration

Migration

From JAX-RS 1.1 to 2.0

JAX-RS 2.0 is backward compatible with JAX-RS 1.1. Please see JAX-RS Basics for more information about JAX-RS 2.0.

From CXF 2.7.x to CXF 3.0.0

Please check the CXF 3.0.0 Migration Guide for the information about all the changes
in CXF 3.0.0. Here are more details on the changes specifically affecting JAX-RS users:

1. CXF RequestHandler and ResponseHandler filters have been removed.

These legacy CXF filters are still supported in 2.7.x but no longer in 3.0.0. Please use ContainerRequestFilter and ContainerResponseFilter instead. Also, ReaderInterceptor and WriterInterceptor can be used too.

Note, CXF filters had org.apache.cxf.message.Message available in the signature. If CXF Message is used in the existing CXF RequestHandler or ResponseHandler then use "org.apache.cxf.phase.PhaseInterceptorChain.getCurrentMessage()" or "org.apache.cxf.jaxrs.util.JAXRSUtils.getCurrentMessage()" to get a Message which has all the contextual information available.

For example, instead of

...

public class CustomRequestHandler implements RequestHandler {
    public Response handleRequest(Message message, ClassResourceInfo cri) {
    }
}

public class CustomResponseHandler implements ResponseHandler {
    public Response handleResponse(Message message, OperationResourceInfo ori, Response response) {
    }
}

JIRA issues can be found here.

JAX-RS Compliance

2.1 Final

CXF 3.2.0 has been updated to implement the JAX-RS 2.1 API’s as completely as possible.

If another TCK licensee that uses CXF’s JAX-RS 2.1 implementation in their products finds issues with CXF’s compliance, we are more than happy to fix bugs that are raised.

2.0 Final

CXF 3.1.x and CXF 3.0.x have been updated to implement the JAX-RS 2.0 API’s as completely as possible without access to the final JAX-RS 2.0 TCK.
We have done extensive testing with JAX-RS 2.0 user applications, samples, and the preliminary TCK to make sure CXF’s implementation is as complete and compatible as we can make it.
CXF makes and will continue making the best possible effort to have JAX-RS 2.0 and new JAX-RS version implementations technically complete and offering an environment for running the portable JAX-RS 2.0 applications.
If the final 2.0 TCK is made available to Apache, we will make sure CXF is updated to pass.
If another TCK licensee that uses CXF’s JAX-RS 2.0 implementation in their products finds issues with CXF’s compliance, we are more than happy to fix bugs that are raised.

1.1

Apache CXF 2.6.x passes the final JAX-RS 1.1 TCK and is formally 1.1 compliant.

Please consult the TomEE documentation on the support of Java EE related JAX-RS 1.1 options in its Apache CXF-based JAX-RS runtime.

CXF 2.7.x and CXF 3.0.0 will fully support and run JAX-RS 1.1 applications but will not pass the JAX-RS 1.1 TCK Signature tests due to

CXF 2.7.x and CXF 3.0.0 depending on 2.0-m10 and 2.0 final versions of JAX-RS 2.0 API.

Project setup and configuration

Migration

From JAX-RS 2.0 to JAX-RS 2.1

JAX-RS 2.1 is backward compatible with JAX-RS 2.0. Please see JAX-RS Basics for more information about JAX-RS 2.1.

All the existing JAX-RS 2.0 and 1.1 applications will run on CXF 3.2.0.

From JAX-RS 1.1 to 2.0

JAX-RS 2.0 is backward compatible with JAX-RS 1.1. Please see JAX-RS Basics for more information about JAX-RS 2.0.

CXF 3.1.x and CXF 3.0.x are expected to support the existing JAX-RS 1.1 applications.

From CXF 2.7.x to CXF 3.0.x or 3.1.x

Please check the CXF 3.0.0 Migration Guide for the information about all the changes
in CXF 3.0.0. Here are more details on the changes specifically affecting JAX-RS users:

1. CXF RequestHandler and ResponseHandler filters have been removed.

These legacy CXF filters are still supported in 2.7.x but no longer in 3.0.0. Please use ContainerRequestFilter and ContainerResponseFilter instead. Also, ReaderInterceptor and WriterInterceptor can be used too.

Note, CXF filters had org.apache.cxf.message.Message available in the signature. If CXF Message is used in the existing CXF RequestHandler or ResponseHandler then use "org.apache.cxf.phase.PhaseInterceptorChain.getCurrentMessage()" or "org.apache.cxf.jaxrs.util.JAXRSUtils.getCurrentMessage()" to get a Message which has all the contextual information available.

For example, instead of

public class CustomRequestHandler implements RequestHandler {
    public Response handleRequest(Message message, ClassResourceInfo cri) {
    }
}

public class CustomResponseHandler implements ResponseHandler {
    public Response handleResponse(Message message, OperationResourceInfo ori, Response response) {
    }
}

do

public class CustomRequestFilter implements ContainerRequestFilter {
    public void filter(ContainerRequestContext context) {
        Message message = JAXRSUtils.getCurrentMessage();
       ClassResourceInfo cri = message.getExchange().get(OperationResourceInfo.class).getClassResourceInfo();

        // or consider using JAX-RS 2.0 ResourceInfo context

        // finally use context.abortWith(Response) if you need to block the request 
    }
}

public class CustomResponseFilter implements ContainerResponseFilter

do

public class CustomRequestFilter implements ContainerRequestHandler {
    public void filter(ContainerRequestContext context) {
        Message message = JAXRSUtils.getCurrentMessage();
        ClassResourceInfo cri = message.getExchange().get(OperationResourceInfo.class).getResourceClass();

        // or consider using JAX-RS 2.0 ResourceInfo context

        // finally use context.abortWith(Response) if you need to block the request 
    }
}

public class CustomResponseFilter implements ContainerResponseFilter {
    public void filter(Message message, OperationResourceInfo ori, Response response) {
        public class CustomRequestFilter implements ContainerRequestHandler {
    public void filter(ContainerRequestContext inContext, ContainerResponseContext outContext) {
        Message message = JAXRSUtils.getCurrentMessage();
        OperationResourceInfo cri = message.getExchange().get(OperationResourceInfo.class);

        // or consider using JAX-RS 2.0 ResourceInfo context 
        
        // finally, work with ContainerResponseContext to modify specific Response properties
    }
}

...

2. CXF org.apache.cxf.jaxrs.ext.form.Form has been dropped, please use JAX-RS 2.0 Form instead. For example, use:

import javax.ws.rs.core.Form;

Form form = new Form().param("a", "b");

instead of

import org.apache.cxf.jaxrs.ext.form.Form;

Form form = new Form().set("a", "b");

...

6. JAX-RS 2.0 introduces a controversial requirement that the default built-in JAX-RS MessageBodyWriter and JAX-RS MessageBodyReader providers are preferred to custom providers supporting the same types unless the custom providers are precisely typed, for example, if you have a custom InputStream reader properly implementing isReadable:

public class MyStreamProvider implements MessageBodyReader<Object> {
    public boolean isReadable(Class<?> cls, ...) {
        return InputStream.class.isAssignableFrom(cls) || Reader.class.isAssignableFrom(cls);
    }
    // other methods
}

...

At CXF level, the users which depend on CXF MultipartProvider to have InputStream or String references to multipart attachments will be affected unless they use @Multipart annotation. For example, if we have a multipart payload with a single part/attachment only then the following code:

@POST
@Consumes("multipart/form-data")
public void upload(InputStream is) {
}

which in CXF 2.7.x or earlier will return a pointer to first/single individual part, will actually return a stream representing the complete unprocessed multipart payload. Adding a @Multipart marker will keep the existing code working as expected:

@POST
@Consumes("multipart/form-data")
public void upload(@Multipart InputStream is) {
}

Alternatively, setting a "support.type.as.multipart" contextual property will do.

7. If the custom code throws JAX-RS WebApplicationException with Response containing a non-null entity then custom WebApplicationException mappers will be bypassed - another problematic requirement, for example, the custom mappers doing the logging will miss on such exceptions.
Set CXF "support.wae.spec.optimization" property to false to disable it.

From CXF 2.6.x to CXF 2.7.x

Please check the CXF 2.7 Migration Guide for the information about all the changes affecting the JAX-RS users

Maven dependencies

CXF 3.0.0

The cxf-rt-frontend-jaxrs dependency is required:

...

   <dependency>
      <groupId>org.apache.cxf</groupId>
      <artifactId>cxf-rt-frontend-jaxrs</artifactId>
      <version>3.0.0-milestone1</version>
   </dependency>

the logging will miss on such exceptions.
Set CXF "support.wae.spec.optimization" property to false to disable it.

8. In some cases the matching sub-resource locators will be dropped to precisely meet the current JAX-RS matching algorithm text, please see CXF-5650 for more information. Use a new "keep.subresource.candidates" property to support the existing application if needed.

CXF 3.1.2 Provider Sorting Changes

Starting from CXF 3.1.2 customMessageBodyReader (MBR), MessageBodyWriter (MBW) and ExceptionMapper providers are sorted together with default providers.

Before CXF 3.1.2 if a custom MBR or MBW matches the read or write selection criteria, example, if MBR Consumes matches Content-Type and its isReadable() returns true, then

the default providers are not even checked. The specification however does let the custom providers be selected only if no higher priority matching default provider is available.

For example, suppose you have a custom StringReader which is not typed by String but by Object. In this case the default provider which is typed by String wins. To have the custom String provider winning one needs to type it by String.

Check the specification or ask at the users list for more details.

Maven dependencies

CXF 3.2.0

The cxf-rt-frontend-jaxrs dependency is required:

   <dependency>
      <groupId>org.apache.cxf</groupId>
      <artifactId>cxf-rt-frontend-jaxrs</artifactId>
      <version>3.2.0</version>
   </dependency>

This will in turn pull other CXF modules such cxf-core and cxf-rt-transports-http, check the pom for more information.

javax.ws.rs/javax.ws.rs-api/2.1 dependency provides JAX-RS 2.1 Final API.

CXF 3.1.x

The cxf-rt-frontend-jaxrs dependency is required

This will in turn pull other CXF modules such cxf-core and cxf-rt-transports-http, check the pom for more information.

javax.ws.rs/javax.ws.rs-api/2.0 dependency provides JAX-RS 2.0 Final API.

Existing JAX-RS 1.1 applications can run in CXF 3.0.0.

CXF 2.7.0

javax.ws.rs/javax.ws.rs-api/2.0-m10 replaces javax.ws.rs/jsr311-api/1.1.1. This is very close to JSR-339 Public Release API level. Users can expect very minor differences in the Final Release of API.

Existing JAX-RS 1.1 applications can run in CXF 2.7.x.

CXF 2.6.x

Please check the CXF 2.6 Migration Guide for the information about all the changes affecting the JAX-RS users. Typically adding the frontend jaxrs dependency should be enough.

1. javax.ws.rs/jsr311-api/1.1.1

Optional providers (including the default JSONProvider) are located in this module:

   <dependency>
      <groupId>org.apache.cxf</groupId>
      <artifactId>cxf-rt-frontend-jaxrs</artifactId>
      <artifactId>cxf-rt-rs-extension-providers</artifactId>
      <version>2.6.0</version>
   </dependency>

The Search extension is now located in

...

   <dependency>
      <groupId>org.apache.cxf</groupId>
      <artifactId>cxf-rt-rs-extension-search</artifactId>
      <version>2.6.0</version>
   </dependency>

<version>3.1.12</version>
   </dependency>

This will in turn pull other CXF modules such cxf-core and cxf-rt-transports-http, check the pom for more information.

javax.ws.rs/javax.ws.rs-api/2.0 dependency provides JAX-RS 2.0 Final API.

javax.annotation/javax.annotation-api/1.2 dependency is needed if custom JAX-RS 2.0 filters or interceptors use a javax.annotation.Priority annotation.

Existing JAX-RS 1.1 applications can run in CXF 3.1.x and CXF 3.0.x.

Setting up the classpath

If Maven is not used then the following JARs will need to be available at the runtime classpath.

For CXF 3.0.0:

TODO

For CXF 2.7.x:

TODO

CXF JAX-RS bundle

Note CXF JAX-RS bundle has been removed in CXF 3.0.0. Prefer depending on the JAX-RS frontend directly. In CXF 3.0.0 a complete CXF all-inclusive bundle can still be used if really needed.

...

Please note that this bundle has a transitive Maven dependency on the Jetty server modules. If you are using Maven and working with other servlet containers such as Tomcat then please add the following exclusion:

   <dependency>
      <groupId>org.apache.cxf</groupId>
      <artifactId>cxf-bundle-jaxrs</artifactId>
      <version>${cxf.version}</version>
</version>
      <exclusions>
          <exclusion>
            <groupId>org.eclipse.jetty</groupId>
         <exclusions>   <artifactId>jetty-server</artifactId>
          <exclusion></exclusion>
      </exclusions> 

     <groupId>org.eclipse.jetty</groupId>
            <artifactId>jetty-server</artifactId>
          </exclusion>
      </exclusions> 

   </dependency>

...

</dependency>

What is New

• Complete support for JAX-RS 2.1, please see JAX-RS Basics for more information
• JAX-RS NIO extension based on the early JAX-RS 2.1 API prototype.
• JAX-RS RxJava Observable support: as a standard JAX-RS 2.1 RxInvoker client provider and returning it asynchronously from the resource methods (CXF extension) 
• JAX-RS Project Reactor Support also based on the JAX-RS 2.1 RxInvoker paradigm
• Complete support for JAX-RS 2.0, please see JAX-RS Basics for more information
• Bean Validation 1.1 Support, please see http://cxf.apache.org/docs/validationfeature.html for more information
• Swagger Feature

Getting Started with JAX-RS

Understanding the Basics

• for generating Swagger API documentation from JAX-RS endpoints

Getting Started with JAX-RS

Understanding the Basics

You are encouraged to read JAX-RS 2.1 JSR-370 specification to find out the information not covered by this documentation. The specification enhances JAX-RS 2.0 by introducing a support for Reactive Client API extensions, Server Sent Events (client and server), returning CompletableFuture from the resource methods and the sub-resource classes (as opposed to instances) from the sub-resource locators.

You are also encouraged to read JAX-RS 2.0 You are encouraged to read JSR-339 specification to find out the information not covered by this documentation. The specification introduces many terms such as root resources, resource methods, sub-resources and sub-resource locators, message body readers and writers. JAX-RS 2.0 additionally introduces filters, interceptors, new client API, features, new exception classes, server-side support for asynchronous invocations.

...

Lets assume you have a web application called 'rest'' (example, a 'rest.war' archive). CXFServlet's url-pattern is "/test/*". Finally, jaxrs:server's address is "/bar".

...

The runtime will replace '.xml' or '.en' with an appropriate header value. For it to know the type or language value associated with a given URI suffix, some configuration needs to be done. Here's an example of how it can be done with Spring:

  <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:languageMappings>
       <entry key="en" value="en-gb"/>  
    </jaxrs:languageMappings>
  </jaxrs:server>

...

{{ > GET /resource?_type=xml}}

CXF also supports overriding request methods. However note that by default this is not allowed (since CXF 3.3.4) for a CXF service. To enable HTTP method overriding, specify the "org.apache.cxf.jaxrs.allow.http.method.override" endpoint property as "true".

Two options of overriding HTTP request methods are available - via a query parameterOverriding a request method is also easy:

> GET /resource?_method=POST

...

Many of the existing CXF features can be applied either to jaxrs:server or jaxrs:client. For example, to enable logging of requests and responses, simply do:

<beans xmlns:cxf="http://cxf.apache.org/core" 
   xsi:schemaLocation="http://cxf.apache.org/core 
      http://cxf.apache.org/schemas/core.xsd">
<jaxrs:server>
<jaxrs:features>
     <cxf:logging/>
</jaxrs:features>
<jaxrs:server>
</beans>

...

Please see the Secure JAX-RS Services page for more information.

Please also check JAX-RS XML Security, JAX-RS SAML, JAX-RS Token Authorization and JAX-RS OAuth2 pages for more information about the advanced security topics.

...

Please see the DOSGI Reference page ('org.apache.cxf.rs' properties) and a greeter_rest sample for more information. Note that this demo can be run exactly as a SOAP-based greeter demo as it registers and consumes a similar (but) JAX-RS annotated GreeterService. In addition, this demo shows how one can register and consume a given interface (GreeterService2) without using explicit JAX-RS annotations but providing an out-of-band user model description greeter demo as it registers and consumes a similar (but) JAX-RS annotated GreeterService. In addition, this demo shows how one can register and consume a given interface (GreeterService2) without using explicit JAX-RS annotations but providing an out-of-band user model description.

OData Support

CXF JAX-RS endpoints can support OData in two ways by relying on Apache Olingo.

First, the OData "$filter" query is supported by the Search extension where an endpoint with the application specific API can respond to the filter queries, for example, return a collection of books matching the fillter search criteria.

Second, CXF JAX-RS can be used to interpose over the Olingo, as is demoed here. Effectively such a CXF endpoint becomes an OData server: all it does it delegates to Olingo. The idea is to be able to add CXF specific features and interceptors in front of Olingo.

Other Advanced Features

CXF JAX-RS provides a number of advanced extensions such as the support for the JMS transport, one-way invocations (HTTP and JMS), suspended invocations (HTTP and JMS), making existing code REST-aware by applying external user models, etc.

...