...
Span | ||
---|---|---|
| ||
JAX-RS |
...
Table of Contents |
---|
Introduction
...
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
...
Check the specification or ask at the users list for more details.
...
.
...
Please check the CXF 2.7 Migration Guide for the information about all the changes affecting the JAX-RS users
Maven dependencies
CXF 3.
...
2.0
The cxf-rt-frontend-jaxrs dependency is required:
Code Block | ||||
---|---|---|---|---|
| ||||
<dependency> <groupId>org.apache.cxf</groupId> <artifactId>cxf-rt-frontend-jaxrs</artifactId> <version>3.02.0-milestone1<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.01
dependency provides JAX-RS 2.0 1 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.0.0.
CXF 2.7.0
CXF 3.1.x
The cxf-rt-frontend-jaxrs dependency is required:
Code Block | ||||
---|---|---|---|---|
| ||||
<dependency>
<groupId>org.apache.cxf</groupId>
<artifactId>cxf-rt-frontend-jaxrs</artifactId>
<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-m10
replaces javax.ws.rs/jsr311 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 23.71.x .and CXF
...
3.
...
0.x.Please check the
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.
Only in CXF 2.7.x or earlier:
A standalone JAX-RS bundle is available which may be of interest to users doing the JAX-RS work only.
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
1. javax.ws.rs/jsr311-api/1.1.1
Optional providers (including the default JSONProvider) are located in this module:
Code Block | ||||
---|---|---|---|---|
| ||||
<dependency> <groupId>org.apache.cxf</groupId> <artifactId>cxf-rt-rs-extension-providers<bundle-jaxrs</artifactId> <version>2.6.0<<version>${cxf.version}</version> </dependency> |
The Search extension is now located in
Code Block | ||
---|---|---|
xml | xml | <exclusions> <dependency><exclusion> <groupId>org.apacheeclipse.cxf<jetty</groupId> <artifactId>cxf-rt-rs-extension-search< <artifactId>jetty-server</artifactId> <version>2.6.0</version> </exclusion> </dependency> |
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.
Only in CXF 2.7.x or earlier:
A standalone JAX-RS bundle is available which may be of interest to users doing the JAX-RS work only.
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>
<exclusions>
<exclusion>
<groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-server</artifactId>
</exclusion>
</exclusions>
</dependency>
exclusions>
</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 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
What is New
- 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 for generating Swagger API documentation from JAX-RS endpoints
Getting Started with JAX-RS
Understanding the Basics
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.
...
Please see the JAX-RS Basics page for more information about new JAX-RS 2.0 filters and interceptors available in CXF 2.7.x and 3.0.0.
Service listings and WADL support
New: Swagger feature has been introduced.
CXF JAX-RS supports WADL. CXF JAX-RS service endpoints can be listed in the service listings page and users can check the WADL documents.
Please see the JAXRS Services Description page for more information.
Configuring JAX-RS services
JAX-RS services can be configured programmatically, using Blueprint, Spring or CXFNonSpringJAXRSServlet.
Please see the JAXRS Services Configuration page for more information.
Testing
JAX-RS services can be easily tested using the embedded Jetty or CXF Local Transport.
Please see the JAXRS Testing page for more information.
Debugging
One may want to use a browser to test how a given HTTP resource reacts to different HTTP Accept or Accept-Language header values and request methods. For example, if a resource class supports a "/resource" URI then one can test the resource class using one of the following queries :
> GET /resource.xml
> GET /resource.en
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>
and 3.0.0.
Service listings and WADL support
New: Swagger feature has been introduced.
CXF JAX-RS supports WADL. CXF JAX-RS service endpoints can be listed in the service listings page and users can check the WADL documents.
Please see the JAXRS Services Description page for more information.
Configuring JAX-RS services
JAX-RS services can be configured programmatically, using Blueprint, Spring or CXFNonSpringJAXRSServlet.
Please see the JAXRS Services Configuration page for more information.
Testing
JAX-RS services can be easily tested using the embedded Jetty or CXF Local Transport.
Please see the JAXRS Testing page for more information.
Debugging
One may want to use a browser to test how a given HTTP resource reacts to different HTTP Accept or Accept-Language header values and request methods. For example, if a resource class supports a "/resource" URI then one can test the resource class using one of the following queries :
> GET /resource.xml
> GET /resource.en
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:
Code Block | ||||
---|---|---|---|---|
| ||||
<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>
|
CXF also supports a _type query as an alternative to appending extensions like '.xml' to request URIs:
{{ > 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 parameter:
> GET /resource?_method=POST
Alternatively, one can specify an HTTP header X-HTTP-Method-Override:
> POST /books
> X-HTTP-Method-Override : PATCH
For example, at the moment the http-centric client API does not support arbitrary HTTP verbs except for those supported
by Java HTTPUrlConnection. When needed, X-HTTP-Method-Override can be set to overcome this limitation.
Finally, a "_ctype" query allows for overriding Content-Type.
Please see the Debugging and Logging page for more information on how to debug and log service calls in CXF.
Logging
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:
Code Block | ||||
---|---|---|---|---|
| ||||
<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 make sure the http://cxf.apache.org/core
namespace is in scope.
Starting from CXF 2.3.0 it is also possible to convert log events into Atom entries and either push them to receivers or make them available for polling
CXF also supports a _type query as an alternative to appending extensions like '.xml' to request URIs:
{{ > GET /resource?_type=xml}}
Overriding a request method is also easy:
> GET /resource?_method=POST
Alternatively, one can specify an HTTP header X-HTTP-Method-Override:
> POST /books
> X-HTTP-Method-Override : PATCH
For example, at the moment the http-centric client API does not support arbitrary HTTP verbs except for those supported
by Java HTTPUrlConnection. When needed, X-HTTP-Method-Override can be set to overcome this limitation.
Finally, a "_ctype" query allows for overriding Content-Type.
Please see the Debugging and Logging page for more information on how to debug and log service calls in CXF.
Logging
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>
.
Advanced Features
Multiparts
Multiparts can be handled in a number of ways. The CXF core runtime provides advanced support for handling attachments which CXF JAX-RS builds upon.
Please see the JAX-RS Multiparts page for more information.
Secure JAX-RS services
Transport level HTTPS security can be used to protect messages exchanged between CXF JAX-RS endpoints and providers.
Authentication and authorization can be enforced in a number of ways.
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.
Failover and Load Distribution Features
Starting from CXF 2.4.1, CXF JAX-RS proxy and WebClient consumers can be backed up by failover and load distribution features.
Please see the JAX-RS Failover page for more information.
Redirection
Starting from CXF 2.2.5 it is possible to redirect the request or response call to other servlet resources by configuring CXFServlet or using CXF JAX-RS RequestDispatcherProvider.
Please see the JAX-RS Redirection page for more information.
XSLT and XPath
XSLT and XPath are promoted and treated as first-class citizens in CXF JAX-RS. These technologies can be very powerful when generating complex data or retrieving data of interest out of complex XML fragments.
Please see the JAX-RS Advanced XML page for more information.
Complex Search Queries
Using query parameter beans provides a way to capture search requirements that can be expressed by enumerating name/value pairs, for example, a query such as '?name=CXF&version=2.3' can be captured by a bean containing setName and setVersion methods. This 'template' bean can be used in the code to compare it against all available local data.
Versions 2.3 and later of CXF JAXRS support another option for doing advanced search queries using the Feed Item Query Language(FIQL).
Please see the JAX-RS Search page for more information.
Model-View-Controller support
XSLT
Please see the JAX-RS Advanced XML page for more information. on how XSLTJaxbProvider
can be used to generate complex (X)HTML views.
JSP
With the introduction of RequestDispatcherProvider
it is now possible for JAXRS service responses be redirected to JSP pages for further processing. Please see the JAX-RS Redirection page for more information.
Combining JAX-WS and JAX-RS
CXF JAX-RS tries to make it easy for SOAP developers to experiment with JAX-RS and combine both JAX-WS and JAX-RS in the same service bean when needed.
Please see the JAX-RS and JAX-WS page for more information.
Integration with Distributed OSGi
Distributed OSGi RI is a CXF subproject. DOSGi mandates how registered Java interfaces can be exposed
and consumed as remote services. DOSGi single and multi bundle distributions contain all the OSGI bundles required for a CXF endpoint be successfully published.
CXF JAX-RS implementations has been integrated with DOSGi RI 1.1-SNAPSHOT which makes it possible to expose Java interfaces as RESTful services and consume such services using a proxy-based client API.
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.
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
Please make sure the http://cxf.apache.org/core
namespace is in scope.
Starting from CXF 2.3.0 it is also possible to convert log events into Atom entries and either push them to receivers or make them available for polling.
Please see the Debugging and Logging page for more information.
Advanced Features
Multiparts
Multiparts can be handled in a number of ways. The CXF core runtime provides advanced support for handling attachments which CXF JAX-RS builds upon.
Please see the JAX-RS Multiparts page for more information.
Secure JAX-RS services
Transport level HTTPS security can be used to protect messages exchanged between CXF JAX-RS endpoints and providers.
Authentication and authorization can be enforced in a number of ways.
Please see the Secure JAX-RS Services page for more information.
Please also check JAX-RS XML Security, JAX-RS SAML and JAX-RS OAuth2 pages for more information about the advanced security topics.
Failover and Load Distribution Features
Starting from CXF 2.4.1, CXF JAX-RS proxy and WebClient consumers can be backed up by failover and load distribution features.
Please see the JAX-RS Failover page for more information.
Redirection
Starting from CXF 2.2.5 it is possible to redirect the request or response call to other servlet resources by configuring CXFServlet or using CXF JAX-RS RequestDispatcherProvider.
Please see the JAX-RS Redirection page for more information.
XSLT and XPath
XSLT and XPath are promoted and treated as first-class citizens in CXF JAX-RS. These technologies can be very powerful when generating complex data or retrieving data of interest out of complex XML fragments.
Please see the JAX-RS Advanced XML page for more information.
Complex Search Queries
Using query parameter beans provides a way to capture search requirements that can be expressed by enumerating name/value pairs, for example, a query such as '?name=CXF&version=2.3' can be captured by a bean containing setName and setVersion methods. This 'template' bean can be used in the code to compare it against all available local data.
Versions 2.3 and later of CXF JAXRS support another option for doing advanced search queries using the Feed Item Query Language(FIQL).
Please see the JAX-RS Search page for more information.
Model-View-Controller support
XSLT
Please see the JAX-RS Advanced XML page for more information. on how XSLTJaxbProvider
can be used to generate complex (X)HTML views.
JSP
With the introduction of RequestDispatcherProvider
it is now possible for JAXRS service responses be redirected to JSP pages for further processing. Please see the JAX-RS Redirection page for more information.
Combining JAX-WS and JAX-RS
CXF JAX-RS tries to make it easy for SOAP developers to experiment with JAX-RS and combine both JAX-WS and JAX-RS in the same service bean when needed.
Please see the JAX-RS and JAX-WS page for more information.
Integration with Distributed OSGi
Distributed OSGi RI is a CXF subproject. DOSGi mandates how registered Java interfaces can be exposed
and consumed as remote services. DOSGi single and multi bundle distributions contain all the OSGI bundles required for a CXF endpoint be successfully published.
CXF JAX-RS implementations has been integrated with DOSGi RI 1.1-SNAPSHOT which makes it possible to expose Java interfaces as RESTful services and consume such services using a proxy-based client API.
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.
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.
...