Date: Tue, 19 Mar 2024 09:58:15 +0000 (UTC) Message-ID: <546084000.56049.1710842295848@cwiki-he-fi.apache.org> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_56048_151122477.1710842295848" ------=_Part_56048_151122477.1710842295848 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
JAX-RS
JAX-RS: Java API for RESTful Web Services is a Java pr= ogramming language API that provides support in creating web services accor= ding to the Representational State Transfer (REST) architectural style.
CXF supports JAX-RS 2.1 (JSR-370), 2.0 (JSR-339) and 1.1 (JSR-311).
CXF 3.2.0 supports JAX-RS 2.1. All existing JAX-RS 2.0 and 1.1 applicati= ons can be run with CXF 3.2.0.
CXF 3.1.x and 3.0.x support JAX-RS 2.0. Existing JAX-RS 1.1 applic= ations can be run with CXF 3.1.x/3.0.x.
See below for more information abou= t the compliance.
JAX-RS related demos are located under the samples/jax_rs directory.
Outstanding JAX-RS JIRA issues can be found here= .
CXF 3.2.0 has been updated to implement the JAX-RS 2.1 API=E2=80=99s as = completely as possible.
If another TCK licensee that uses CXF=E2=80=99s JAX-RS 2.1 implementatio= n in their products finds issues with CXF=E2=80=99s compliance, we are more= than happy to fix bugs that are raised.
CXF 3.1.x and CXF 3.0.x have been updated to implement the JAX-RS 2.0 AP=
I=E2=80=99s 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=E2=80=99s implementation is as com=
plete 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 offerin=
g 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=E2=80=99s JAX-RS 2.0 implementation i=
n their products finds issues with CXF=E2=80=99s compliance, we are more th=
an happy to fix bugs that are raised.
Apache CXF 2.6.x passes the final JAX-RS 1.1 TCK and is formally 1.1 com= pliant.
Please consult the TomEE documentation on the su= pport 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 applicatio= ns 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 J= AX-RS 2.0 API.
JAX-RS 2.1 is backward compatible with JAX-RS 2.0. Please see JAX-RS Basics for more inf= ormation about JAX-RS 2.1.
All the existing JAX-RS 2.0 and 1.1 applications will run on CXF 3.2.0.<= /p>
JAX-RS 2.0 is backward compatible with JAX-RS 1.1. Please see JAX-RS Basics for more inf= ormation 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.
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 si= gnature. If CXF Message is used in the existing CXF RequestHandler or Respo= nseHandler then use "org.apache.cxf.phase.PhaseInterceptorChain.getCurrentM= essage()" 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 o= ri, Response response) { } }
do
public class = CustomRequestFilter implements ContainerRequestFilter { public void filter(ContainerRequestContext context) { Message message =3D JAXRSUtils.getCurrentMessage(); ClassResourceInfo cri =3D message.getExchange().get(OperationResourc= eInfo.class).getClassResourceInfo(); // or consider using JAX-RS 2.0 ResourceInfo context // finally use context.abortWith(Response) if you need to block the= request=20 } } public class CustomResponseFilter implements ContainerResponseFilter { public void filter(ContainerRequestContext inContext, ContainerResponse= Context outContext) { Message message =3D JAXRSUtils.getCurrentMessage(); OperationResourceInfo cri =3D message.getExchange().get(OperationRe= sourceInfo.class); // or consider using JAX-RS 2.0 ResourceInfo context=20 =20 // finally, work with ContainerResponseContext to modify specific R= esponse properties } }
The above is only needed to ease the migration of the existing RequestHa= ndler or ResponseHandler implementations. Prefer writing portable JAX-RS 2.= 0 filter implementations if possible. CXF interceptors can be used to do th= e CXF specific code if needed.
2. CXF org.apache.cxf.jaxrs.ext.form.Form has been dropped, please use J= AX-RS 2.0 Form inst= ead. For example, use:
import javax.= ws.rs.core.Form; Form form =3D new Form().param("a", "b");
instead of
import org.ap= ache.cxf.jaxrs.ext.form.Form; Form form =3D new Form().set("a", "b");
3. CXF WebClient and proxy code has been moved to a new cxf-rt-rs-client=
module.
Also, jaxrs:client elements for injecting proxies have had the namespace ch=
anged from from "http://cxf.apache.org/jaxrs" to "http://cxf.apache.org/jax=
rs-client".
Please see JA= X-RS Client API page for more information.
4. WADL Auto Generator code has been moved to a new cxf-rt-rs-service-de= scription module.
5. CXF ParameterHandler has been dropped. Please use ParameterConverterProvide= r instead, it can be used both on the server and client sides.
6. JAX-RS 2.0 introduces a controversial requirement that the default bu= ilt-in JAX-RS MessageBodyWriter and JAX-RS MessageBodyReader providers are = preferred to custom providers supporting the same types un= less the custom providers are precisely typed, for example, if you have a c= ustom InputStream reader properly implementing isReadable:
public class = MyStreamProvider implements MessageBodyReader<Object> { public boolean isReadable(Class<?> cls, ...) { return InputStream.class.isAssignableFrom(cls) || Reader.class.isAs= signableFrom(cls); } // other methods }
then the runtime will ignore it and choose a default InputStream/Reader = reader because MyStreamProvider is typed on Object. This was done to deal w= ith the cases where well-known JSON/etc providers are blindly supporting al= l types in their isReadable methods by always returning 'true' and then fai= ling when asked to actually read the incoming stream into InputStream/etc d= irectly. In case of MyStreamProvider, it will need to be split into MyInput= StreamProvider and MyReaderProvider typed on InputStream and Reader respect= ively.
At CXF level, the users which depend on CXF MultipartProvider to have In= putStream or String references to multipart attachments will be affected un= less they use @Multipart annotation. For example, if we have a multipart pa= yload 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 indi= vidual part, will actually return a stream representing the complete unproc= essed 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 Respons=
e 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.
8. In some cases the matching sub-resource locators will be dropped to p= recisely meet the current JAX-RS matching algorithm text, please see CXF-5650 for more information. Use a new "keep.subre= source.candidates" property to support the existing application if needed.<= /p>
Starting from CXF 3.1.2 customMessageBodyReader (MBR), MessageBodyWriter= (MBW) and ExceptionMapper providers are sorted together with default provi= ders.
Before CXF 3.1.2 if a custom MBR or MBW matches the read or write select= ion criteria, example, if MBR Consumes matches Content-Type and its isReada= ble() returns true, then
the default providers are not even checked. The specification however do= es 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 b= y 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.
The cxf-rt-frontend-jaxrs dependency is required:
<depend= ency> <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-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.
The cxf-rt-frontend-jaxrs dependency is required:
<depend= ency> <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-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 cust= om JAX-RS 2.0 filters or interceptors use a javax.annotation.Priority annot= ation.
Existing JAX-RS 1.1 applications can run in CXF 3.1.x and CXF 3.0.x.
Note CXF JAX-RS bundle has been removed in CXF 3.0.0. Prefer depending o= n the JAX-RS frontend directly. In CXF 3.0.0 a complete CXF all-inclusive <= a class=3D"external-link" href=3D"http://svn.apache.org/repos/asf/cxf/trunk= /osgi/bundle/all/pom.xml" rel=3D"nofollow">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 Je= tty server modules. If you are using Maven and working with other servlet c= ontainers such as Tomcat then please add the following exclusion:
<depend= ency> <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>=20 </dependency>
You are encouraged to read JAX-RS 2.1 JSR-370 specif= ication to find out the information not covered by this documentation. The = specification enhances JAX-RS 2.0 by introducing a support for Reactive Cli= ent API extensions, Server Sent Events (client and server), returning Compl= etableFuture from the resource methods and the sub-resource classes (as opp= osed to instances) from the sub-resource locators.
You are also encouraged to read JAX-RS 2.0 JSR-339 s= pecification to find out the information not covered by this documentation.= The specification introduces many terms such as root resources, resource m= ethods, sub-resources and sub-resource locators, message body readers and w= riters. JAX-RS 2.0 additionally introduces filters, interceptors, new clien= t API, features, new exception classes, server-side support for asynchronou= s invocations.
Please see the JA= X-RS Basics page for more information.
JAX-RS MessageBodyReader and MessageBodyWriter can be used to create dat= a bindings for reading and writing data in a number of different formats. C= ompliant JAX-RS implementations are expected to support JAXB-annotated bean= s, JAXP Source objects, InputStreams, etc.
In addition, CXF JAX-RS lets users reuse existing CXF DataBindings for w= orking with JAXB, XBeans, Aegis and SDO.
Please see the JAX-RS Data Bindings page for more information.
Lets assume you have a web application called 'rest' (example, a 'rest.w= ar' archive). CXFServlet's url-pattern is "/test/*". Finally, jaxrs:server'= s address is "/bar".
Requests like /rest/test/bar or /rest/test/bar/baz will be delivered to = one of the resource classes in a given jaxrs:server endpoint. For the forme= r request to be handled, a resource class with @Path("/") should be availab= le, in the latter case - at least @Path("/") or a more specific @Path("/baz= ").
The same requirement can be expressed by having a CXFServlet with "/*" a= nd jaxrs:server with "/test/bar".
When both CXFServlet and jaxrs:server use "/" then it's a root resource = class which should provide a @Path with at least "/test/bar" for the above = requests to be matched.
Generally, it can be a good idea to specify the URI segments which are m= ore likely to change now and then with CXFServlets or jaxrs:server.
CXF 3.0.0 implements JAX-RS 2.0 Client API.
CXF 2.7.x or earlier provides a comprehensive support for developing RES= Tful clients by supporting 3 flavors of the client API: proxy-based, HTTP-c= entric and XML-centric. CXF-specific client API is supported alongside new = JAX-RS 2.0 Client API in CXF 3.0.0.
Please see the JAX-RS Client API page for more information.
Bean Validation 1.1 is supported since CXF 3.0.0-milestone1. Please see = the http://cxf.apache.org/docs/validationfeatur= e.html for more information.
It is possible to intercept and modify the inbound and outbound calls wi= th the help of CXF JAX-RS filters and/or CXF interceptors. Additionally, cu= stom invokers offer an option to intercept a call immediately before a serv= ice bean is invoked.
Please see the J= AX-RS Filters page for more information.
Please see the JA= X-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.
New: Swagger feature has been introduced.
CXF JAX-RS supports WADL. CXF JAX-RS service endpoints c= an be listed in the service listings page and users can check the WADL docu= ments.
Please see the JAXRS Services Description page for more information.
JAX-RS services can be configured programmatically, using Blueprint, Spr= ing or CXFNonSpringJAXRSServlet.
Please see the JAXRS Services Configuration page for more information.
JAX-RS services can be easily tested using the embedded Jetty or CXF Loc=
al Transport.
Please see the JAXRS Testing page for more informa=
tion.
One may want to use a browser to test how a given HTTP resource reacts t= o different HTTP Accept or Accept-Language header values and request method= s. 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 valu= e. For it to know the type or language value associated with a given URI su= ffix, some configuration needs to be done. Here's an example of how it can = be done with Spring:
<jaxrs:s= erver id=3D"customerService" address=3D"/"> <jaxrs:serviceBeans> <bean class=3D"org.apache.cxf.jaxrs.systests.CustomerService" />= ; </jaxrs:serviceBeans> <jaxrs:extensionMappings> <entry key=3D"json" value=3D"application/json"/> <entry key=3D"xml" value=3D"application/xml"/> </jaxrs:extensionMappings> <jaxrs:languageMappings> <entry key=3D"en" value=3D"en-gb"/> =20 </jaxrs:languageMappings> </jaxrs:server>
CXF also supports a _type query as an alternative to appending extension= s like '.xml' to request URIs:
{{ > GET /resource?_type=3Dxml}}
CXF also supports overriding request methods. However note that by defau= lt 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.over= ride" endpoint property as "true".
Two options of overriding HTTP request methods are available - via a que= ry parameter:
> GET /resource?_method=3DPOST
Alternatively, one can specify an HTTP header X-HTTP-Method-Override:
> POST /books
> X-HTTP-Method-Override : PA=
TCH
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 t=
o 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 a= nd log service calls in CXF.
Many of the existing CXF features can be applied either to jaxrs:s=
erver
or jaxrs:client
. For example, to enable logging o=
f requests and responses, simply do:
<beans xml= ns:cxf=3D"http://cxf.apache.org/core"=20 xsi:schemaLocation=3D"http://cxf.apache.org/core=20 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 A= tom entries and either push them to receivers or make them available for po= lling.
Please see the Debugging and Logging page for more information.
Multiparts can be handled in a number of ways. The CXF core runtime prov= ides advanced support for handling attachments which CXF JAX-RS builds upon= .
Please see the JAX-RS Multiparts page for more information.
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 Toke= n Authorization and JAX-RS OAuth2 pages for more information about the advanced securit= y topics.
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.
Starting from CXF 2.2.5 it is possible to redirect the request or respon= se call to other servlet resources by configuring CXFServlet or using CXF J= AX-RS RequestDispatcherProvider.
Please see the JAX-RS Redirection page for more information.
XSLT and XPath are promoted and treated as first-class citizens in CXF J= AX-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.
Using query parameter beans p= rovides a way to capture search requirements that can be expressed by enume= rating name/value pairs, for example, a query such as '?name=3DCXF&vers= ion=3D2.3' can be captured by a bean containing setName and setVersion meth= ods. 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 adv= anced search queries using the Feed I= tem Query Language(FIQL).
Please see the JA= X-RS Search page for more information.
XSLT
Please see the JAX-RS Advanced XML page for more information. on how XSLTJaxbPr=
ovider
can be used to generate complex (X)HTML views.
JSP
With the introduction of RequestDispatcherProvider
it is no=
w possible for JAXRS service responses be redirected to JSP pages for furth=
er processing. Please see the JAX-RS Redirection page for more information.
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 nee= ded.
Please see the JAX-RS and JAX-WS page for more information.
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 distribution=
s 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-SNAPSHO= T 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' pro= perties) and a greeter_rest= sample for more information. Note that this demo can be run exactly as= a SOAP-based greeter de= mo as it registers and consumes a similar (but) JAX-RS annotated GreeterService. In ad= dition, this demo shows how one can register and consume a given interface = (GreeterService2= ) without using explicit JAX-RS annotations but providing an out-of-ban= d user model description.=
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 w= ith the application specific API can respond to the filter queries, for exa= mple, 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 he= re. Effectively such a CXF endpoint becomes an OData server: all it doe= s it delegates to Olingo.= The idea is to be able to add CXF specific features and interceptors in fr= ont of Olingo.
CXF JAX-RS provides a number of advanced extensions such as the support = for the JMS transport, one-way invocations (HTTP and JMS), suspended invoca= tions (HTTP and JMS), making existing code REST-aware by applying external = user models, etc.
Please see the JAX-RS Advanced Features page for more information.
Please see the JAX-RS Maven Plugins page for more information about the Maven plu= gins and archetypes which can help with creating CXF JAX-RS applications.= p>
CXF JAX-RS applications packaged as WAR archives can be deployed into st=
andalone Servlet containers such as Tomcat or Jetty.
Please see the JAX-RS Deployment page for the =
tips on how to deploy the CXF JAX-RS applications into various Java EE and =
OSGI application servers successfully.
CXF JAX-RS implementation sits on top of the core CXF runtime and is qui= te self-contained and isolated from other CXF modules such as jaxws and sim= ple frontends.
Please check the issue list and see = if you are interested in fixing one of the issues.
If you decide to go ahead then the fastest way to start is to
mvn install -Pfastinstall
'<=
/li>
If you are about to submit a patch after building a trunk/rt/frontend/ja=
xrs, then please also run JAX-RS system tests in trunk/systests/jaxrs :
=
> mvn install
You can also check out the general Getting Involve= d web page for more information on contributing.