Author: buildbot
Date: Thu Aug 30 15:56:58 2018
New Revision: 1034539
Log:
Production update by buildbot for cxf
Modified:
websites/production/cxf/content/cache/docs.pageCache
websites/production/cxf/content/docs/jaxrs-services-configuration.html
Modified: websites/production/cxf/content/cache/docs.pageCache
==============================================================================
Binary files - no diff available.
Modified: websites/production/cxf/content/docs/jaxrs-services-configuration.html
==============================================================================
--- websites/production/cxf/content/docs/jaxrs-services-configuration.html
(original)
+++ websites/production/cxf/content/docs/jaxrs-services-configuration.html Thu
Aug 30 15:56:58 2018
@@ -34,7 +34,6 @@
<script src='/resources/highlighter/scripts/shCore.js'></script>
<script src='/resources/highlighter/scripts/shBrushJava.js'></script>
<script src='/resources/highlighter/scripts/shBrushXml.js'></script>
-<script src='/resources/highlighter/scripts/shBrushBash.js'></script>
<script>
SyntaxHighlighter.defaults['toolbar'] = false;
SyntaxHighlighter.all();
@@ -118,15 +117,15 @@ Apache CXF -- JAXRS Services Configurati
<td height="100%">
<!-- Content -->
<div class="wiki-content">
-<div
id="ConfluenceContent"><p> </p><p> </p><p> </p><p> <span
style="font-size:2em;font-weight:bold">JAX-RS : Services Configuration</span>
+<div id="ConfluenceContent"><p>  <span
style="font-size:2em;font-weight:bold">JAX-RS : Services Configuration</span>
- </p><p> </p><p> </p><p> </p><p><style
type="text/css">/*<![CDATA[*/
-div.rbtoc1524513438191 {padding: 0px;}
-div.rbtoc1524513438191 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1524513438191 li {margin-left: 0px;padding-left: 0px;}
+ </p><p><br clear="none"></p><p><style type="text/css">/*<![CDATA[*/
+div.rbtoc1535644577944 {padding: 0px;}
+div.rbtoc1535644577944 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1535644577944 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1524513438191">
+/*]]>*/</style></p><div class="toc-macro rbtoc1535644577944">
<ul class="toc-indentation"><li><a shape="rect"
href="#JAXRSServicesConfiguration-ConfiguringJAX-RSservicesprogrammatically">Configuring
JAX-RS services programmatically</a></li><li><a shape="rect"
href="#JAXRSServicesConfiguration-OSGI">OSGI</a>
<ul class="toc-indentation"><li><a shape="rect"
href="#JAXRSServicesConfiguration-Blueprint">Blueprint</a></li><li><a
shape="rect" href="#JAXRSServicesConfiguration-Spring">Spring</a></li></ul>
</li><li><a shape="rect" href="#JAXRSServicesConfiguration-SpringBoot">Spring
Boot</a></li><li><a shape="rect"
href="#JAXRSServicesConfiguration-ConfiguringJAX-RSendpointsprogrammaticallywithoutSpring">Configuring
JAX-RS endpoints programmatically without Spring</a></li><li><a shape="rect"
href="#JAXRSServicesConfiguration-BlueprintWeb">Blueprint Web</a>
@@ -145,7 +144,7 @@ div.rbtoc1524513438191 li {margin-left:
<ul class="toc-indentation"><li><a shape="rect"
href="#JAXRSServicesConfiguration-Spring.1">Spring</a></li></ul>
</li><li><a shape="rect"
href="#JAXRSServicesConfiguration-ServletandApplicationContainerConfiguration">Servlet
and Application Container Configuration</a></li></ul>
</div><h1
id="JAXRSServicesConfiguration-ConfiguringJAX-RSservicesprogrammatically">Configuring
JAX-RS services programmatically</h1><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">import org.apache.cxf.jaxrs.JAXRSServerFactoryBean;
+<pre class="brush: java; gutter: false; theme: Default">import
org.apache.cxf.jaxrs.JAXRSServerFactoryBean;
...
JAXRSServerFactoryBean sf = new JAXRSServerFactoryBean();
@@ -154,17 +153,17 @@ sf.setAddress("http://localhost:9000/";);
sf.create();
</pre>
</div></div><p>Some things to note:</p><ul><li>The JAXRSServerFactoryBean
creates a Server inside CXF which starts listening for requests on the URL
specified.</li><li>Check the <a shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/jaxrs/JAXRSServerFactoryBean.html";>JAXRSServerFactoryBean
API</a> for methods for adding multiple root
resources</li><li>setResourceClasses() is for root resources only, use
setProvider() or setProviders() for @Provider-annotated classes.</li><li><p>By
default, the JAX-RS runtime is responsible for the lifecycle of resource
classes, default lifecycle is per-request. You can set the lifecycle to
singleton by using following line:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">sf.setResourceProvider(BookStore.class, new
SingletonResourceProvider(new BookStore()));
+<pre class="brush: java; gutter: false; theme:
Default">sf.setResourceProvider(BookStore.class, new
SingletonResourceProvider(new BookStore()));
</pre>
</div></div></li><li><p>If you prefer not to let the JAX-RS runtime handle the
resource class lifecycle for you (for example, it might be the case that your
resource class is created by other containers such as Spring), you can do the
following:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">JAXRSServerFactoryBean sf = new
JAXRSServerFactoryBean();
+<pre class="brush: java; gutter: false; theme: Default">JAXRSServerFactoryBean
sf = new JAXRSServerFactoryBean();
CustomerService cs = new CustomerService();
sf.setServiceBeans(cs);
sf.setAddress("http://localhost:9080/";);
sf.create();
</pre>
</div></div></li></ul><h1 id="JAXRSServicesConfiguration-OSGI">OSGI</h1><h2
id="JAXRSServicesConfiguration-Blueprint">Blueprint</h2><p>The following
example shows how to configure a JAX-RS endpoint in OSGI containers supporting
Blueprint:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><blueprint
xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0";
+<pre class="brush: java; gutter: false; theme: Default"><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";
@@ -190,7 +189,7 @@ sf.create();
</blueprint>
</pre>
</div></div><h2 id="JAXRSServicesConfiguration-Spring">Spring</h2><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><beans
xmlns="http://www.springframework.org/schema/beans";
+<pre class="brush: java; gutter: false; theme: Default"><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="
@@ -208,7 +207,7 @@ sf.create();
</pre>
</div></div><h1 id="JAXRSServicesConfiguration-SpringBoot">Spring
Boot</h1><p>Please see CXF <a shape="rect"
href="http://cxf.apache.org/docs/springboot.html#SpringBoot-SpringBootCXFJAX-RSStarter";>SpringBoot</a> documentation. </p><p>Please
see <a shape="rect" class="external-link"
href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/spring_boot";
rel="nofollow">JAX-RS Spring Boot</a> and <a shape="rect"
class="external-link"
href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/spring_boot_scan/application";
rel="nofollow">JAX-RS Spring Boot Scan</a> demos.</p><p>Please see <a
shape="rect" href="jaxrsclientspringboot.html">JAXRSClientSpringBoot</a>
documentation on how CXF <a shape="rect" href="jax-rs-client-api.html">JAX-RS
Clients</a> can be used in a SpringBoot Application. </p><p> </p><h1
id="JAXRSServicesConfiguration-ConfiguringJAX-RSendpointsprogrammaticallywithoutSprin
g">Configuring JAX-RS endpoints programmatically without Spring</h1><p>Note
that even though no Spring is explicitly used in the previous section, it is
still used by default to have various CXF components registered with the bus
such as transport factories. If no Spring libraries are available on the
classpath then please follow the following example :</p><div class="code panel
pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">JAXRSServerFactoryBean sf = new
JAXRSServerFactoryBean();
+<pre class="brush: java; gutter: false; theme: Default">JAXRSServerFactoryBean
sf = new JAXRSServerFactoryBean();
sf.setResourceClasses(CustomerService.class);
sf.setResourceProvider(CustomerService.class, new
SingletonResourceProvider(new CustomerService()));
sf.setAddress("http://localhost:9000/";);
@@ -219,28 +218,28 @@ manager.registerBindingFactory(JAXRSBind
sf.create();
</pre>
</div></div><h1 id="JAXRSServicesConfiguration-BlueprintWeb">Blueprint
Web</h1><p>This section describes how CXF JAX-RS endpoints can be bootstrapped
with CXFBlueprintServlet and Blueprint contexts.</p><p>This approach is
recommended for developers building CXF JAX-RS endpoints to be deployed in OSGI
and which will do RequestDispatcher-based forwards.</p><p>Additionally it
allows to reuse the same Blueprint contexts between OSGI and non-OSGI
deployments.</p><p>Both options below work with CXF 3.1.3:</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><dependency>
+<pre class="brush: java; gutter: false; theme: Default"><dependency>
<groupId>org.apache.cxf</groupId>
<artifactId>cxf-rt-frontend-jaxrs</artifactId>
<version>3.1.3</version>
</dependency>
</pre>
</div></div><p> </p><h2
id="JAXRSServicesConfiguration-Mavendependencies">Maven dependencies</h2><h3
id="JAXRSServicesConfiguration-OSGI.1">OSGI</h3><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><dependency>
+<pre class="brush: java; gutter: false; theme: Default"><dependency>
<groupId>org.apache.aries.blueprint</groupId>
<artifactId>org.apache.aries.blueprint.webosgi</artifactId>
<version>1.0.1</version>
</dependency>
</pre>
</div></div><p>In OSGI (Karaf) one should also install a 'war' feature.</p><h3
id="JAXRSServicesConfiguration-ServletContainer">Servlet Container</h3><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><dependency>
+<pre class="brush: java; gutter: false; theme: Default"><dependency>
<groupId>org.apache.aries.blueprint</groupId>
<artifactId>org.apache.aries.blueprint.web</artifactId>
<version>1.1.1</version>
</dependency>
</pre>
</div></div><p> </p><h2
id="JAXRSServicesConfiguration-Commonexample">Common
example</h2><p> </p><p>This <a shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/systests/jaxrs/src/test/resources/jaxrs_soap_blueprint/WEB-INF/web.xml";
rel="nofollow">web.xml</a> shows how to setup CXFBlueprintServlet which
processes <a shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/systests/jaxrs/src/test/resources/jaxrs_soap_blueprint/WEB-INF/beans.xml";
rel="nofollow">this Blueprint context.</a> It works exactly the same way in
OSGI and non-OSGI environments.</p><h1
id="JAXRSServicesConfiguration-ConfiguringJAX-RSservicesincontainerwithSpringconfigurationfile.">Configuring
JAX-RS services in container with Spring configuration file.</h1><h2
id="JAXRSServicesConfiguration-web.xml">web.xml</h2><p>In web.xml one needs to
register one or more CXFServlet(s) and link to an application context
configuration.</p><h3 id="JAXRSServicesC
onfiguration-UsingSpringContextLoaderListener">Using Spring
ContextLoaderListener</h3><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><?xml version="1.0" encoding="ISO-8859-1"?>
+<pre class="brush: java; gutter: false; theme: Default"><?xml version="1.0"
encoding="ISO-8859-1"?>
<!DOCTYPE web-app
PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
@@ -273,7 +272,7 @@ sf.create();
</web-app>
</pre>
</div></div><p>The application context configuration is shared between all the
CXFServlets</p><h3
id="JAXRSServicesConfiguration-UsingCXFServletinitparameters">Using CXFServlet
init parameters</h3><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><?xml version="1.0" encoding="ISO-8859-1"?>
+<pre class="brush: java; gutter: false; theme: Default"><?xml version="1.0"
encoding="ISO-8859-1"?>
<!DOCTYPE web-app
PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
@@ -285,40 +284,39 @@ sf.create();
<servlet-class>
org.apache.cxf.transport.servlet.CXFServlet
</servlet-class>
- <init-param>
- <param-name>config-location</param-name>
- <param-value>/WEB-INF/beans1.xml</param-value>
- </init-param>
+ <init-param>
+ <param-name>config-location</param-name>
+ <param-value>/WEB-INF/beans1.xml</param-value>
+ </init-param>
<load-on-startup>1</load-on-startup>
</servlet>
- <servlet>
+ <servlet>
<servlet-name>CXFServlet2</servlet-name>
<display-name>CXF Servlet2</display-name>
<servlet-class>
org.apache.cxf.transport.servlet.CXFServlet
</servlet-class>
- <init-param>
- <param-name>config-location</param-name>
- <param-value>/WEB-INF/beans2.xml</param-value>
- </init-param>
+ <init-param>
+ <param-name>config-location</param-name>
+ <param-value>/WEB-INF/beans2.xml</param-value>
+ </init-param>
<load-on-startup>1</load-on-startup>
</servlet>
-
<servlet-mapping>
<servlet-name>CXFServlet1</servlet-name>
<url-pattern>/1/*</url-pattern>
</servlet-mapping>
- <servlet-mapping>
+ <servlet-mapping>
<servlet-name>CXFServlet2</servlet-name>
<url-pattern>/2/*</url-pattern>
</servlet-mapping>
</web-app>
</pre>
</div></div><p>Each CXFServlet can get a unique application context
configuration. Note, no Spring ContextLoaderListener is registered in web.xml
in this case.</p><h2
id="JAXRSServicesConfiguration-beans.xml">beans.xml</h2><div class="code panel
pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><?xml version="1.0" encoding="UTF-8"?>
+<pre class="brush: java; gutter: false; theme: Default"><?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:jaxrs="http://cxf.apache.org/jaxrs";
@@ -343,7 +341,7 @@ http://cxf.apache.org/schemas/jaxrs.xsd";
</beans>
</pre>
</div></div><p>In the above configuration all resources will be configured as
singletons, see <a shape="rect"
href="jaxrs-services-configuration.html">below</a> for information on creating
per-request resources.</p><h1
id="JAXRSServicesConfiguration-ConfiguringJAX-RSservicesusingexplicitbeanconfiguration">Configuring
JAX-RS services using explicit bean configuration</h1><p>Note that
jaxrs:server (and jaxrs:client) declarations depend on
'http://cxf.apache.org/jaxrs' Spring NamespaceHandler be available on
classpath. Sometimes, due to classloading restrictions or bugs in underlying
containers which are exposed during complex deployments or due to multiple
Spring libraries interfering with each other, NamespaceHandler can not be
located and thus jaxrs endpoints can not be created. <br clear="none"> Please
report such issues to the team working on developing the container
itself.</p><p>If you need to do Spring configuration and get an error to do
with a missing NamespaceHandler then, a
s a workaround, consider configuring jaxrs endpoints using CXF beans which
actually handle the creation of jaxrs:server endpoints. This is marginally more
complex, but overall, the configuration ends up being quite similar, for
example, the above jaxrs:server endpoint can be configured like this
instead:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><?xml version="1.0" encoding="UTF-8"?>
+<pre class="brush: java; gutter: false; theme: Default"><?xml version="1.0"
encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
xsi:schemaLocation="
@@ -365,7 +363,7 @@ http://www.springframework.org/schema/be
</pre>
</div></div><h1 id="JAXRSServicesConfiguration-SpringAOP">Spring
AOP</h1><p>CXF JAX-RS is capable of working with AOP interceptors applied to
resource classes from Spring.<br clear="none"> For example:</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><beans xmlns:jaxrs="http://cxf.apache.org/jaxrs";
xmlns:aop="http://www.springframework.org/schema/aop";
+<pre class="brush: java; gutter: false; theme: Default"><beans
xmlns:jaxrs="http://cxf.apache.org/jaxrs";
xmlns:aop="http://www.springframework.org/schema/aop";
xsi:schemaLocation=" http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/aop
@@ -399,7 +397,7 @@ http://www.springframework.org/schema/be
</pre>
</div></div><p>Note that some AOP configuration is applied to two JAX-RS
resource classes. By default Spring uses JDK dynamic proxies if a class to be
proxified implements at least one interface or CGLIB proxies
otherwise.</p><p>For example, here's how
org.apache.cxf.systest.jaxrs.BookStoreWithInterface looks like:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">public interface BookInterface {
+<pre class="brush: java; gutter: false; theme: Default">public interface
BookInterface {
@GET
@Path("/thosebooks/{bookId}/")
@Produces("application/xml")
@@ -422,10 +420,10 @@ public class BookStoreWithInterface exte
}
</pre>
</div></div><p>In this case Spring will use a JDK dynamic proxy to wrap a
BookStoreWithInterface class. As such it is important that the method which
needs to be invoked such as getThatBook(...) will be part of the
interface.</p><p>The other method, getTheBook() can not be dispatched to by a
JAX-RS runtime as it's not possible to discover it through a JDK proxy. If this
method also needs to be invoked then this method should either be added to the
interface or CGLIB proxies have to be explicitly enabled (consult Spring AOP
documentation for more details). For example:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><aop:config proxy-target-class="true"/>
+<pre class="brush: java; gutter: false; theme: Default"><aop:config
proxy-target-class="true"/>
</pre>
</div></div><h1
id="JAXRSServicesConfiguration-ConfiguringJAX-RSservicesincontainerwithoutSpring">Configuring
JAX-RS services in container without Spring</h1><p>If you prefer, you can
register JAX-RS endpoints without depending on Spring with the help of
CXFNonSpringJaxrsServlet :</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><servlet>
+<pre class="brush: java; gutter: false; theme: Default"><servlet>
<servlet-name>CXFServlet</servlet-name>
<display-name>CXF Servlet</display-name>
<servlet-class>
@@ -487,7 +485,7 @@ public class BookStoreWithInterface exte
</servlet>
</pre>
</div></div><p>When service classes and providers are registered this way, the
default life-cycle is 'singleton'. You can override it by setting a
"jaxrs.scope" parameter with the value of 'prototype' (equivalent to
per-request). <br clear="none"> By default, the endpoint address is "/". One
can provide a more specific value using a "jaxrs.address" parameter.</p><p>Note
that multiple service  or providers class names are separated by a comma.
Users may want to use a "class.parameter.split.char" servlet parameter with the
value "space" when</p><p>migrating from the older CXF versions were the space
was used to separate multiple class names.</p><p>If the referenced service
classes are not annotated with JAX-RS annotations then an external user model
can also be linked to :</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><servlet>
+<pre class="brush: java; gutter: false; theme: Default"><servlet>
<servlet-name>CXFServlet</servlet-name>
<display-name>CXF Servlet</display-name>
<servlet-class>
@@ -510,7 +508,7 @@ public class BookStoreWithInterface exte
</servlet>
</pre>
</div></div><p>A more portable way to register resource classes and providers
with CXFNonSpringJaxrsServlet is to use a JAX-RS Application <a shape="rect"
class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/systests/jaxrs/src/test/java/org/apache/cxf/systest/jaxrs/BookApplication.java";>implementation</a>
:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><servlet>
+<pre class="brush: java; gutter: false; theme: Default"><servlet>
<servlet-name>CXFServlet</servlet-name>
<display-name>CXF Servlet</display-name>
<servlet-class>
@@ -534,7 +532,7 @@ public class BookStoreWithInterface exte
</servlet>
</pre>
</div></div><p>Note that Application.getClasses() method returns a set of
per-request resource class names. Application.getSingletons() returns a list of
singleton resource and provider classes.</p><p>Starting from CXF
2.3.7/2.4.3/2.5.0 it is possible to simple properties for resource and
Application classes, providers and interceptors:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><servlet>
+<pre class="brush: java; gutter: false; theme: Default"><servlet>
<servlet-name>CXFServlet</servlet-name>
<display-name>CXF Servlet</display-name>
<servlet-class>
@@ -551,7 +549,7 @@ public class BookStoreWithInterface exte
</servlet>
</pre>
</div></div><p>In the above example,
org.apache.cxf.systest.jaxrs.BookApplication is expected to have setName and
setId setters, with a single primitive or List parameter
type.</p><p><strong>Note</strong> that having the web-app_2_3.dtd DTD
referenced from web.xml will likely prevent 'param-value' containing spaces and
make it difficult to specify multiple providers like this:</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"> <init-param>
+<pre class="brush: java; gutter: false; theme: Default"> <init-param>
<param-name>jaxrs.providers</param-name>
<param-value>
mypackage.Provider1
@@ -562,7 +560,7 @@ public class BookStoreWithInterface exte
</servlet>
</pre>
</div></div><p>In such cases consider moving to the web-app 2.5 schema or
extending CXFNonSpringJaxrsProviders or introducing an Application.</p><h2
id="JAXRSServicesConfiguration-AttachingJAXRSendpointstoanexistingJettyserver">Attaching
JAXRS endpoints to an existing Jetty server</h2><p>Here is a code fragment
showing how it can be done with the help of CxfNonSpringJaxrsServlet :</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">CXFNonSpringJAXRSServlet cxf = new
CXFNonSpringJaxrsServlet();
+<pre class="brush: java; gutter: false; theme:
Default">CXFNonSpringJAXRSServlet cxf = new CXFNonSpringJaxrsServlet();
...
@@ -574,7 +572,7 @@ root.addServlet(servlet, "/*");
</pre>
</div></div><h1
id="JAXRSServicesConfiguration-JAX-RSRuntimeDelegateandApplications">JAX-RS
RuntimeDelegate and Applications</h1><p>If you have a JAX-RS Application
implementation available and would like to minimize the interaction with the
CXF JAX-RS specific API, you may want to use the JAX-RS RuntimeDelegate
:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">import javax.ws.rs.ext.RuntimeDelegate;
+<pre class="brush: java; gutter: false; theme: Default">import
javax.ws.rs.ext.RuntimeDelegate;
import org.apache.cxf.endpoint.Server;
import org.apache.cxf.jaxrs.JAXRSServerFactoryBean;
@@ -593,7 +591,7 @@ server.stop();
</pre>
</div></div><p>Note that the above code makes sure an @ApplicationPath value
(if CustomApplication has this annotation) is taken into account.</p><h1
id="JAXRSServicesConfiguration-ConfiguringJAX-RSservicesprogrammaticallywithSpringconfigurationfile.">Configuring
JAX-RS services programmatically with Spring configuration file.</h1><p>When
using Spring explicitly in your code, you may want to follow this example
:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">ClassPathXmlApplicationContext ctx = new
ClassPathXmlApplicationContext(new String[]
+<pre class="brush: java; gutter: false; theme:
Default">ClassPathXmlApplicationContext ctx = new
ClassPathXmlApplicationContext(new String[]
{"/org/apache/cxf/jaxrs/spring/servers.xml"});
// 'simple' is the id of the jaxrs server bean
@@ -601,13 +599,13 @@ JAXRSServerFactoryBean sfb = (JAXRSServe
sfb.create();
</pre>
</div></div><p>Note that in in this case your Spring configuration file should
import cxf-extension-http-jetty.xml instead of cxf-servlet.xml :</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><!--
+<pre class="brush: java; gutter: false; theme: Default"><!--
<import resource="classpath:META-INF/cxf/cxf-servlet.xml" />
-->
<import resource="classpath:META-INF/cxf/cxf-extension-http-jetty.xml" />
</pre>
</div></div><h1 id="JAXRSServicesConfiguration-Lifecyclemanagement">Lifecycle
management</h1><h2 id="JAXRSServicesConfiguration-FromSpring">From
Spring</h2><p>By default, the service beans which are referenced directly from
the jaxrs:server endpoint declarations are treated by the runtime as singleton
JAX-RS root resources. For example:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><beans>
+<pre class="brush: java; gutter: false; theme: Default"><beans>
<jaxrs:server id="customerService" address="/service1">
<jaxrs:serviceBeans>
<ref bean="customerBean" />
@@ -622,7 +620,7 @@ sfb.create();
</beans>
</pre>
</div></div><p>Spring instantiates and injects the customerBean reference and
the runtime will access this reference directly afterwards. Effectively, the
scope attribute which may be present on the customerBean bean declaration is
ignored in this case, <strong>unless the Spring AOP is used to enforce the
required scope</strong> (see below for more information).</p><p>The
'serviceFactories' element or beanNames attribute has to be used for a
'prototype', 'request' and other Spring bean scopes be supported.</p><p>For
example, the serviceFactories element can reference one or more beans of type
'org.apache.cxf.jaxrs.spring.SpringResourceFactory' which in turn reference the
actual service beans.</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><beans>
+<pre class="brush: java; gutter: false; theme: Default"><beans>
<jaxrs:server id="customerService" address="/service1">
<jaxrs:serviceFactories>
<ref bean="sfactory1" />
@@ -642,7 +640,7 @@ sfb.create();
</beans>
</pre>
</div></div><p>In this example, the jaxrs:server endpoint has two JAX-RS root
resources (customerBean1 and customerBean2) with the Spring 'prototype'
scope.<br clear="none"> Other scopes can also be supported.</p><p>If using the
jaxrs:serviceFactories element seems a bit verbose then the 'beanNames'
attribute can be used instead:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><beans>
+<pre class="brush: java; gutter: false; theme: Default"><beans>
<jaxrs:server id="customerService" address="/service1"
beanNames="customerBean1 customerBean2"/>
@@ -651,7 +649,7 @@ sfb.create();
</beans>
</pre>
</div></div><p>The beanNames attribute lists the names/ids of service beans
separated by space. The jaxrs:serviceFactories element has to be used when
users register custom CXF JAX-RS <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/lifecycle/ResourceProvider.java";>ResourceProvider</a>
implementations.</p><p>Another approach toward supporting complex scopes in
Spring is to use Spring AOP. For example, the following fragment shows how to
have the Spring "request" scope supported:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><beans
+<pre class="brush: java; gutter: false; theme: Default"><beans
xmlns="http://www.springframework.org/schema/beans";
xmlns:aop="http://www.springframework.org/schema/aop";
xmlns:jaxrs="http://cxf.apache.org/jaxrs";
@@ -676,12 +674,12 @@ sfb.create();
</beans>
</pre>
</div></div><p>in addition, the following servlet listener has to be added to
the web.xml:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><listener>
+<pre class="brush: java; gutter: false; theme: Default"><listener>
<listener-class>org.springframework.web.context.request.RequestContextListener</listener-class>
</listener>
</pre>
</div></div><p>The request-scoped service bean instances (example,
org.apache.cxf.systest.jaxrs.CustomerService instances) are not actually
available at the initialization time thus one limitation of the above
configuration is that it is not possible to inject JAX-RS contexts into these
service beans. This is not a show-stopper because contexts such as UriInfo can
be passed in as resource method parameters. However, if the injection into the
fields or via method setters is required then a little customization of the
org.apache.cxf.jaxrs.spring.SpringResourceFactory will do the trick.
Particularly, the Spring ApplicationContext reports that a request-scoped bean
is a singleton but the JAX-RS runtime can not inject thread-local proxies given
that the actual instance is not available as explained above; in fact, the
request-scoped beans are not really JAX-RS singletons. Thus a simple custom
factory like <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/tru
nk/systests/jaxrs/src/test/java/org/apache/cxf/systest/jaxrs/RequestScopeResourceFactory.java">this
one</a> is needed and it has to be used the following way:</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><beans>
+<pre class="brush: java; gutter: false; theme: Default"><beans>
<jaxrs:server id="customerService" address="/service1">
<jaxrs:serviceFactories>
<bean
class="org.apache.cxf.systest.jaxrs.RequestScopeResourceFactory">
@@ -694,20 +692,20 @@ sfb.create();
</beans>
</pre>
</div></div><p>The above configuration makes sure that the CXF JAX-RS runtime
injects the values at the request time given that the customerBean bean is not
seen as a JAX-RS singleton. This approach is only needed if the injection of
contexts is required.</p><h2
id="JAXRSServicesConfiguration-WithCXFNonSpringJaxrsServlet">With
CXFNonSpringJaxrsServlet</h2><p>CXFNonSpringJaxrsServlet uses 'Singleton' as a
default scope for service classes specified by a "jaxrs.serviceClasses" servlet
parameter. It can be overridden by setting a "jaxrs.scope" parameter to a
"prototype" value or by not using the "jaxrs.serviceClasses" parameter at all
and registering a JAXRS Application implementation instead. Please see the
section describing CXFNonSpringJaxrsServlet for more
details.</p><p>CXFNonSpringJaxrsServlet can support singleton scopes for
classes with constructors expecting JAXRS contexts, at the moment it can only
inject ServletContext or ServletConfig contexts :</p><div class="code panel pd
l" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">@Path("/")
+<pre class="brush: java; gutter: false; theme: Default">@Path("/")
public class SingletonResourceClass {
public SingletonResourceClass(@Context ServletContext context, @Context
ServletConfig context2) {}
}
</pre>
</div></div><h2
id="JAXRSServicesConfiguration-Programmatically">Programmatically</h2><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">JAXRSServerFactoryBean sf = new
JAXRSServerFactoryBean();
+<pre class="brush: java; gutter: false; theme: Default">JAXRSServerFactoryBean
sf = new JAXRSServerFactoryBean();
sf.setResourceClass(CustomerService.class);
sf.setResourceProvider(new SingletonResourceProvider(new CustomerService()));
sf.setResourceClass(CustomerService2.class);
sf.setResourceProvider(new PerRequestResourceProvider(CustomerService.class));
</pre>
</div></div><h2
id="JAXRSServicesConfiguration-PostConstructandPreDestroy">PostConstruct and
PreDestroy</h2><p>Bean methods annotated with @PostConstruct and @PreDestroy
annotations will be called as expected by the scope rules. <br clear="none">
Singleton beans will have their postconstruct method called when the endpoint
is created. If a given singleton resource instance was created by Spring then
its predestroy method will also be called after, for example, the web
application which uses it is about to be unloaded. At the moment singletons
created by CXFNonSpringJaxrsServlet or programmatically will only have their
postconstruct method (if any) called.</p><p>Prototype beans will have their
postconstruct and predestroy method called before a resource method is invoked
and immediately after the invocation has returned but before the response has
actually been serialized. You can indicate that the predestroy method has to be
called after the request has completely gone out of scope
(that is after the response body if any has been written to the output stream)
by adding an "org.apache.cxf.service.scope" property with the value set to
"request".</p><p>You can also register a custom Spring resource factory by
extending org.apache.cxf.jaxrs.spring.SpringResourceFactory or providing a more
sophisticated implementation.</p><h1
id="JAXRSServicesConfiguration-Locatingcustomresourcesinwebapplications">Locating
custom resources in web applications</h1><p>Resources like schemas, custom
XSLT templates and user models are typically referenced using a classpath:
prefix. Thus one can add them to a WEB-INF/classes folder in a given web
application.<br clear="none"> Since CXF 2.2.3 one can put them directly under
WEB-INF, for example into WEB-INF/xslt, WEB-INF/schemas, WEB-INF/model and
referencing them like 'classpath:/WEB-INF/xslt/template.xsl'.</p><h1
id="JAXRSServicesConfiguration-Multipleendpointsandresourceclasses">Multiple
endpoints and resource classes</h1><p>One can c
onfigure as many jaxrs:server endpoints as needed for a given application,
with every endpoint possibly providing an alternative path to a single resource
bean. Every endpoint can employ as many shared or unique resource classes as
needed, and have common or different providers.</p><h1
id="JAXRSServicesConfiguration-Sharingprovidersbetweenmultipleendpoints">Sharing
providers between multiple endpoints</h1><p>One way to share multiple
providers between multiple endpoints is to refer to the same provider bean from
within jaxrs:provider sections:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><beans>
+<pre class="brush: java; gutter: false; theme: Default"><beans>
<jaxrs:server id="customerService" address="/service1">
<jaxrs:serviceBeans>
<bean class="org.apache.cxf.systest.jaxrs.CustomerService"/>
@@ -732,7 +730,7 @@ sf.setResourceProvider(new PerRequestRes
</pre>
</div></div><p>Starting from CXF 2.7.2 it is possible to register provider
directly on the bus as the bus properties and share them between all the
providers using this bus:</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><beans>
+<pre class="brush: java; gutter: false; theme: Default"><beans>
<cxf:bus>
<cxf:properties>
@@ -757,7 +755,7 @@ sf.setResourceProvider(new PerRequestRes
</beans>
</pre>
</div></div><p>Note a global exception mapper has been registered using the
name of interface, "javax.ws.rs.ext.ExceptionMapper", which all the exception
mappers have to implement.</p><p>Note that once can register global per-bus
providers using "javax.ws.rs.ext.ExceptionMapper",
"javax.ws.rs.ext.MessageBodyReader" or "javax.ws.rs.ext.MessageBodyWriter" bus
properties with the registered providers expected to implement either of these
interfaces.</p><p>Alternatively, one can have all the providers (JAX-RS and
CXF-specific) registered with a bus using "org.apache.cxf.jaxrs.bus.providers"
list property:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><beans
xmlns:util="http://www.springframework.org/schema/util">
+<pre class="brush: java; gutter: false; theme: Default"><beans
xmlns:util="http://www.springframework.org/schema/util">
<cxf:bus>
<cxf:properties>
@@ -790,7 +788,7 @@ sf.setResourceProvider(new PerRequestRes
</beans>
</pre>
</div></div><h1
id="JAXRSServicesConfiguration-DynamicservletsandasingleJAX-RSendpoint">Dynamic
servlets and a single JAX-RS endpoint</h1><p>Note: this is not required by
default starting from CXF 3.0.0-milestone1</p><p>In some advanced cases you may
want to dynamically add new servlets (CXFServlet or CXFNonSpringJaxrsServlet)
with all of them serving the same JAX-RS endpoints. In this case you most
likely want to configure servlets so that the CXF endpoint address is not
overridden :</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">{code:xml}
+<pre class="brush: java; gutter: false; theme: Default">{code:xml}
<servlet>
<servlet-name>CXFServlet</servlet-name>
<display-name>CXF Servlet</display-name>
@@ -808,10 +806,8 @@ sf.setResourceProvider(new PerRequestRes
<load-on-startup>1</load-on-startup>
</servlet>
</pre>
-</div></div><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"> </pre>
</div></div><h1
id="JAXRSServicesConfiguration-Auto-discoveryofrootresourcesandproviders">Auto-discovery
of root resources and providers</h1><p>Starting from CXF 3.0.0 it is possible
to enable the auto-discovery of JAX-RS roots and providers with the regular CXF
JAX-RS endpoint declarations done in XML . Currently it is only possible with
Spring. Patch supporting it for Blueprint is available and will be dealt with
asap.</p><pre> </pre><h2
id="JAXRSServicesConfiguration-Spring.1">Spring</h2><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><beans
xmlns="http://www.springframework.org/schema/beans";
+<pre class="brush: java; gutter: false; theme: Default"><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="
@@ -836,7 +832,7 @@ sf.setResourceProvider(new PerRequestRes
</pre>
</div></div><p>Note the above does not require Spring annotations such
as @Component added to JAX-RS provider or resources.</p><p>If you prefer
doing a pure Spring-based auto-discovery you can have @Component added to
JAX-RS application classes and do</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><beans
xmlns="http://www.springframework.org/schema/beans";
+<pre class="brush: java; gutter: false; theme: Default"><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="
