Modified: websites/production/cxf/content/docs/jax-rs.html
==============================================================================
--- websites/production/cxf/content/docs/jax-rs.html (original)
+++ websites/production/cxf/content/docs/jax-rs.html Wed Sep 13 15:05:52 2017
@@ -32,8 +32,8 @@
<link type="text/css" rel="stylesheet"
href="/resources/highlighter/styles/shThemeCXF.css">
<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/shBrushJava.js'></script>
<script>
SyntaxHighlighter.defaults['toolbar'] = false;
SyntaxHighlighter.all();
@@ -121,11 +121,11 @@ Apache CXF -- JAX-RS
 </p><p> </p><p><style type="text/css">/*<![CDATA[*/
-div.rbtoc1505311247140 {padding: 0px;}
-div.rbtoc1505311247140 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1505311247140 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1505314957390 {padding: 0px;}
+div.rbtoc1505314957390 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1505314957390 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1505311247140">
+/*]]>*/</style></p><div class="toc-macro rbtoc1505314957390">
<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RS-Introduction">Introduction</a></li><li><a shape="rect"
href="#JAX-RS-JAX-RSCompliance">JAX-RS Compliance</a>
<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RS-2.1Final">2.1
Final</a></li><li><a shape="rect" href="#JAX-RS-2.0Final">2.0
Final</a></li><li><a shape="rect" href="#JAX-RS-1.1">1.1</a></li></ul>
</li><li><a shape="rect" href="#JAX-RS-Projectsetupandconfiguration">Project
setup and configuration</a>
@@ -140,7 +140,7 @@ div.rbtoc1505311247140 li {margin-left:
<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RS-Multiparts">Multiparts</a></li><li><a shape="rect"
href="#JAX-RS-SecureJAX-RSservices">Secure JAX-RS services</a></li><li><a
shape="rect" href="#JAX-RS-FailoverandLoadDistributionFeatures">Failover and
Load Distribution Features</a></li><li><a shape="rect"
href="#JAX-RS-Redirection">Redirection</a></li><li><a shape="rect"
href="#JAX-RS-XSLTandXPath">XSLT and XPath</a></li><li><a shape="rect"
href="#JAX-RS-ComplexSearchQueries">Complex Search Queries</a></li><li><a
shape="rect" href="#JAX-RS-Model-View-Controllersupport">Model-View-Controller
support</a></li><li><a shape="rect"
href="#JAX-RS-CombiningJAX-WSandJAX-RS">Combining JAX-WS and
JAX-RS</a></li><li><a shape="rect"
href="#JAX-RS-IntegrationwithDistributedOSGi">Integration with Distributed
OSGi</a></li><li><a shape="rect" href="#JAX-RS-OtherAdvancedFeatures">Other
Advanced Features</a></li></ul>
</li><li><a shape="rect" href="#JAX-RS-MavenPlugins">Maven
Plugins</a></li><li><a shape="rect"
href="#JAX-RS-Deployment">Deployment</a></li><li><a shape="rect"
href="#JAX-RS-Third-partyprojects">Third-party projects</a></li><li><a
shape="rect" href="#JAX-RS-References">References</a></li><li><a shape="rect"
href="#JAX-RS-Howtocontribute">How to contribute</a></li></ul>
</div><h1 id="JAX-RS-Introduction">Introduction</h1><p><a shape="rect"
class="external-link" href="http://en.wikipedia.org/wiki/JAX-RS";
rel="nofollow">JAX-RS</a>: 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.</p><p>CXF supports JAX-RS 2.1 (<a shape="rect" class="external-link"
href="https://www.jcp.org/en/jsr/detail?id=370"; rel="nofollow">JSR-370</a>),
2.0 (<a shape="rect" class="external-link"
href="http://jcp.org/en/jsr/detail?id=339"; rel="nofollow">JSR-339</a>) and 1.1
(<a shape="rect" class="external-link"
href="http://jcp.org/en/jsr/detail?id=311";
rel="nofollow">JSR-311</a>).</p><p>CXF 3.2.0 supports JAX-RS 2.1. All existing
JAX-RS 2.0 and 1.1 applications can be run with CXF 3.2.0.</p><p>CXF 3.1.x and
3.0.x support JAX-RS 2.0.  Existing JAX-RS 1.1 applications can be run
with CXF 3.1.x/3.0.x.</p><p>See <a shape="rect" href
="jax-rs.html">below</a> for more information about the
compliance.</p><p>JAX-RS related demos are located under the <a shape="rect"
class="external-link"
href="http://svn.apache.org/viewvc/cxf/trunk/distribution/src/main/release/samples/jax_rs/";>samples/jax_rs
</a> directory.</p><p>Outstanding JAX-RS JIRA issues can be found <a
shape="rect" class="external-link"
href="https://issues.apache.org/jira/secure/IssueNavigator.jspa?reset=true&jqlQuery=project+%3D+CXF+AND+resolution+%3D+Unresolved+AND+component+%3D+JAX-RS+ORDER+BY+priority+DESC&mode=hide";>here</a>.</p><h1
id="JAX-RS-JAX-RSCompliance">JAX-RS Compliance</h1><p><span
class="confluence-anchor-link" id="JAX-RS-2_0_FINAL"></span></p><h2
id="JAX-RS-2.1Final">2.1 Final</h2><p>CXF 3.2.0 has been updated to implement
the JAX-RS 2.1 API’s as completely as possible.</p><p>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 ha
ppy to fix bugs that are raised.</p><h2 id="JAX-RS-2.0Final">2.0
Final</h2><p>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. <br clear="none">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. <br
clear="none">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.<br
clear="none">If the final 2.0 TCK is made available to Apache, we will make
sure CXF is updated to pass.<br clear="none">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.</p><h2 id="JAX-RS-1.
1">1.1</h2><p>Apache CXF 2.6.x passes the final JAX-RS 1.1 TCK and is formally
1.1 compliant.</p><p>Please consult the <a shape="rect" class="external-link"
href="http://tomee.apache.org/apache-tomee.html";>TomEE</a> documentation on the
support of Java EE related JAX-RS 1.1 options in its Apache CXF-based JAX-RS
runtime.</p><p>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</p><p>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.</p><p> </p><h1
id="JAX-RS-Projectsetupandconfiguration">Project setup and
configuration</h1><h2 id="JAX-RS-Migration">Migration</h2><h3
id="JAX-RS-FromJAX-RS2.0toJAX-RS2.1">From JAX-RS 2.0 to JAX-RS
2.1</h3><p>JAX-RS 2.1 is backward compatible with JAX-RS 2.0. Please see <a
shape="rect" href="jax-rs-basics.html">JAX-RS Basics</a> for more information
about JAX-RS 2.1.</p><p>All the existing JAX-RS 2.0 and 1.1 applications will
run
on CXF 3.2.0.</p><h3 id="JAX-RS-FromJAX-RS1.1to2.0">From JAX-RS 1.1 to
2.0</h3><p>JAX-RS 2.0 is backward compatible with JAX-RS 1.1. Please see <a
shape="rect" href="jax-rs-basics.html">JAX-RS Basics</a> for more information
about JAX-RS 2.0.</p><p>CXF 3.1.x and CXF 3.0.x are expected to support the
existing JAX-RS 1.1 applications.</p><h3
id="JAX-RS-FromCXF2.7.xtoCXF3.0.xor3.1.x">From CXF 2.7.x to CXF 3.0.x or
3.1.x</h3><p>Please check the <a shape="rect"
href="http://cxf.apache.org/docs/30-migration-guide.html";>CXF 3.0.0 Migration
Guide</a> for the information about all the changes<br clear="none"> in CXF
3.0.0. Here are more details on the changes specifically affecting JAX-RS
users:</p><p>1. CXF RequestHandler and ResponseHandler filters have been
removed.</p><p>These legacy CXF filters are still supported in 2.7.x but no
longer in 3.0.0. Please use <a shape="rect" class="external-link"
href="https://jax-rs-spec.java.net/nonav/2.0/apidocs/javax/ws/rs/container/ContainerRequestFi
lter.html" rel="nofollow">ContainerRequestFilter</a> and <a shape="rect"
class="external-link"
href="https://jax-rs-spec.java.net/nonav/2.0/apidocs/javax/ws/rs/container/ContainerResponseFilter.html";
rel="nofollow">ContainerResponseFilter</a> instead. Also, <a shape="rect"
class="external-link"
href="https://jax-rs-spec.java.net/nonav/2.0/apidocs/javax/ws/rs/ext/ReaderInterceptor.html";
rel="nofollow">ReaderInterceptor</a> and <a shape="rect" class="external-link"
href="https://jax-rs-spec.java.net/nonav/2.0/apidocs/javax/ws/rs/ext/WriterInterceptor.html";
rel="nofollow">WriterInterceptor</a> can be used too.</p><p>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.</p><p>For exa
mple, instead of</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">public class CustomRequestHandler implements
RequestHandler {
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">public class CustomRequestHandler implements
RequestHandler {
public Response handleRequest(Message message, ClassResourceInfo cri) {
}
}
@@ -152,7 +152,7 @@ public class CustomResponseHandler imple
</pre>
</div></div><p>do</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">public class CustomRequestFilter implements
ContainerRequestFilter {
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">public class CustomRequestFilter implements
ContainerRequestFilter {
public void filter(ContainerRequestContext context) {
Message message = JAXRSUtils.getCurrentMessage();
ClassResourceInfo cri =
message.getExchange().get(OperationResourceInfo.class).getClassResourceInfo();
@@ -176,17 +176,17 @@ public class CustomResponseFilter implem
</pre>
</div></div><p>The above is only needed to ease the migration of the existing
RequestHandler or ResponseHandler implementations. Prefer writing portable
JAX-RS 2.0 filter implementations if possible. CXF interceptors can be used to
do the CXF specific code if needed.</p><p>2. CXF
org.apache.cxf.jaxrs.ext.form.Form has been dropped, please use JAX-RS 2.0 <a
shape="rect" class="external-link"
href="https://jax-rs-spec.java.net/nonav/2.0/apidocs/javax/ws/rs/core/Form.html";
rel="nofollow">Form</a> instead. For example, use:</p><div class="code panel
pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">import javax.ws.rs.core.Form;
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">import javax.ws.rs.core.Form;
Form form = new Form().param("a", "b");
</pre>
</div></div><p>instead of</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">import org.apache.cxf.jaxrs.ext.form.Form;
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">import org.apache.cxf.jaxrs.ext.form.Form;
Form form = new Form().set("a", "b");
</pre>
</div></div><p>3. CXF WebClient and proxy code has been moved to a new
cxf-rt-rs-client module. <br clear="none"> Also, jaxrs:client elements for
injecting proxies have had the namespace changed from from
"http://cxf.apache.org/jaxrs"; to
"http://cxf.apache.org/jaxrs-client";.</p><p>Please see <a shape="rect"
href="jax-rs-client-api.html">JAX-RS Client API</a> page for more
information.</p><p>4. WADL Auto Generator code has been moved to a new
cxf-rt-rs-service-description module.</p><p>5. CXF ParameterHandler has been
dropped. Please use <a shape="rect" class="external-link"
href="https://jax-rs-spec.java.net/nonav/2.0/apidocs/javax/ws/rs/ext/ParamConverterProvider.html";
rel="nofollow">ParameterConverterProvider</a> instead, it can be used both on
the server and client sides.</p><p>6. JAX-RS 2.0 introduces a controversial
requirement that the default built-in JAX-RS MessageBodyWriter and JAX-RS
MessageBodyReader providers are <strong>preferred</strong> 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:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">public class MyStreamProvider implements
MessageBodyReader<Object> {
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">public class MyStreamProvider implements
MessageBodyReader<Object> {
public boolean isReadable(Class<?> cls, ...) {
return InputStream.class.isAssignableFrom(cls) ||
Reader.class.isAssignableFrom(cls);
}
@@ -194,33 +194,33 @@ Form form = new Form().set("a", "b");
}
</pre>
</div></div><p>then the runtime will ignore it and choose a default
InputStream/Reader reader because MyStreamProvider is typed on Object. This was
done to deal with the cases where well-known JSON/etc providers are blindly
supporting all types in their isReadable methods by always returning 'true' and
then failing when asked to actually read the incoming stream into
InputStream/etc directly. In case of MyStreamProvider, it will need to be split
into MyInputStreamProvider and MyReaderProvider typed on InputStream and Reader
respectively.</p><p>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:</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">@POST
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">@POST
@Consumes("multipart/form-data")
public void upload(InputStream is) {
}
</pre>
</div></div><p>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:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">@POST
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">@POST
@Consumes("multipart/form-data")
public void upload(@Multipart InputStream is) {
}
</pre>
</div></div><p>Alternatively, setting a "support.type.as.multipart" contextual
property will do.</p><p>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.<br clear="none"> Set CXF "support.wae.spec.optimization"
property to false to disable it.</p><p>8. In some cases the matching
sub-resource locators will be dropped to precisely meet the current JAX-RS
matching algorithm text, please see <a shape="rect" class="external-link"
href="https://issues.apache.org/jira/browse/CXF-5650";>CXF-5650</a> for more
information. Use a new "keep.subresource.candidates" property to support the
existing application if needed.</p><h3
id="JAX-RS-CXF3.1.2ProviderSortingChanges">CXF 3.1.2 Provider Sorting
Changes</h3><p>Starting from CXF 3.1.2 customMessageBodyReader (MBR), MessageB
odyWriter (MBW) and ExceptionMapper providers are sorted together with default
providers.</p><p>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</p><p>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.</p><p>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.</p><p>Check the specification or ask at the users list for more
details.</p><p> </p><h2 id="JAX-RS-Mavendependencies">Maven
dependencies</h2><h3 id="JAX-RS-CXF3.2.0">CXF 3.2.0</h3><p>The
cxf-rt-frontend-jaxrs dependency is required:</p><div class="code panel pdl"
style="border-width: 1px;"><div c
lass="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"> <dependency>
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"> <dependency>
<groupId>org.apache.cxf</groupId>
<artifactId>cxf-rt-frontend-jaxrs</artifactId>
<version>3.2.0</version>
</dependency>
</pre>
</div></div><p>This will in turn pull other <a shape="rect"
href="http://cxf.apache.org/project-status.html";>CXF modules</a> such
<code>cxf-core</code> and <code>cxf-rt-transports-http</code>, check <a
shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/rt/frontend/jaxrs/pom.xml";
rel="nofollow">the pom</a> for more information.</p><p><code><a shape="rect"
class="external-link" href="http://javax.ws"; rel="nofollow">javax.ws</a>.rs/<a
shape="rect" class="external-link" href="http://javax.ws";
rel="nofollow">javax.ws</a>.rs-api/2.1</code> dependency provides JAX-RS 2.1
Final API.</p><h3 id="JAX-RS-CXF3.1.x">CXF 3.1.x</h3><p>The
cxf-rt-frontend-jaxrs dependency is required:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"> <dependency>
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"> <dependency>
<groupId>org.apache.cxf</groupId>
<artifactId>cxf-rt-frontend-jaxrs</artifactId>
<version>3.1.12</version>
</dependency>
</pre>
</div></div><p>This will in turn pull other <a shape="rect"
href="http://cxf.apache.org/project-status.html";>CXF modules</a> such
<code>cxf-core</code> and <code>cxf-rt-transports-http</code>, check <a
shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/3.1.x-fixes/rt/frontend/jaxrs/pom.xml";
rel="nofollow">the pom</a> for more
information.</p><p><code>javax.ws.rs/javax.ws.rs-api/2.0</code> dependency
provides JAX-RS 2.0 Final
API.</p><pre>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.</pre><p>Existing JAX-RS 1.1 applications can run in CXF 3.1.x and
CXF 3.0.x.</p><h2 id="JAX-RS-CXFJAX-RSbundle">CXF JAX-RS bundle</h2><p>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 <a shape="rect"
class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/osgi/bund
le/all/pom.xml">bundle</a> can still be used if really needed.</p><p>Only in
CXF 2.7.x or earlier:<br clear="none"> A standalone <a shape="rect"
class="external-link"
href="http://svn.apache.org/repos/asf/cxf/branches/2.7.x-fixes/osgi/bundle/all/pom.xml";>JAX-RS
bundle</a> is available which may be of interest to users doing the JAX-RS
work only.</p><p>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:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"> <dependency>
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"> <dependency>
<groupId>org.apache.cxf</groupId>
<artifactId>cxf-bundle-jaxrs</artifactId>
<version>${cxf.version}</version>
@@ -234,7 +234,7 @@ public void upload(@Multipart InputStrea
</dependency>
</pre>
</div></div><h1 id="JAX-RS-WhatisNew">What is New</h1><ul><li>Complete support
for JAX-RS 2.1, please see <a shape="rect" href="jax-rs-basics.html">JAX-RS
Basics</a> for more information</li><li><a shape="rect"
href="jax-rs-nio.html">JAX-RS NIO</a> extension based on the early JAX-RS 2.1
API prototype.</li><li><a shape="rect" href="jax-rs-rxjava.html">JAX-RS
RxJava</a> Observable support: as a standard JAX-RS 2.1 RxInvoker client
provider and returning it asynchronously from the resource methods (CXF
extension) </li><li>Complete support for JAX-RS 2.0, please see <a
shape="rect" href="jax-rs-basics.html">JAX-RS Basics</a> for more
information</li><li>Bean Validation 1.1 Support, please see <a shape="rect"
href="http://cxf.apache.org/docs/validationfeature.html";>http://cxf.apache.org/docs/validationfeature.html</a>
for more information</li><li><a shape="rect"
href="http://cxf.apache.org/docs/swagger2feature.html";>Swagger Feature</a> for
generating <a shape="rect" class="external
-link" href="http://swagger.io/specification/"; rel="nofollow">Swagger API</a>
documentation from JAX-RS endpoints</li></ul><h1
id="JAX-RS-GettingStartedwithJAX-RS">Getting Started with JAX-RS</h1><h2
id="JAX-RS-UnderstandingtheBasics">Understanding the Basics</h2><p>You are
encouraged to read JAX-RS 2.1 <a shape="rect" class="external-link"
href="http://jcp.org/en/jsr/detail?id=370"; rel="nofollow">JSR-370</a>
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.</p><p>You are also
encouraged to read JAX-RS 2.0 <a shape="rect" class="external-link"
href="http://jcp.org/en/jsr/detail?id=339"; rel="nofollow">JSR-339</a>
specification to find out the information not covered by this document
ation. 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.</p><p>Please see the <a shape="rect"
href="jax-rs-basics.html">JAX-RS Basics</a> page for more information.</p><h2
id="JAX-RS-SupportforDataBindings">Support for Data Bindings</h2><p>JAX-RS
MessageBodyReader and MessageBodyWriter can be used to create data bindings for
reading and writing data in a number of different formats. Compliant JAX-RS
implementations are expected to support JAXB-annotated beans, JAXP Source
objects, InputStreams, etc.</p><p>In addition, CXF JAX-RS lets users reuse
existing CXF DataBindings for working with JAXB, XBeans, Aegis and
SDO.</p><p>Please see the <a shape="rect"
href="jax-rs-data-bindings.html">JAX-RS Data Bindings</a> page for more
information.</p><h2 id="JAX-RS-HowRequestURIisMatched">How Request URI is
Matched</h2><p>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".</p><p>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 former request to be handled, a resource class
with @Path("/") should be available, in the latter case - at least @Path("/")
or a more specific @Path("/baz").</p><p>The same requirement can be expressed
by having a CXFServlet with "/*" and jaxrs:server with "/test/bar".</p><p>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.</p><p>Generally, it can be a good idea to specify the URI segments
which are more likely to change now and then with CXFServlets or jaxrs:server
.</p><h2 id="JAX-RS-ClientAPI">Client API</h2><p>CXF 3.0.0 implements JAX-RS
2.0 Client API.</p><p>CXF 2.7.x or earlier provides a comprehensive support for
developing RESTful clients by supporting 3 flavors of the client API:
proxy-based, HTTP-centric and XML-centric. CXF-specific client API is supported
alongside new JAX-RS 2.0 Client API in CXF 3.0.0.</p><p>Please see the <a
shape="rect" href="jax-rs-client-api.html">JAX-RS Client API</a> page for more
information.</p><h2 id="JAX-RS-BeanValidation">Bean Validation</h2><p>Bean
Validation 1.1 is supported since CXF 3.0.0-milestone1. Please see the <a
shape="rect"
href="http://cxf.apache.org/docs/validationfeature.html";>http://cxf.apache.org/docs/validationfeature.html</a>
for more information.</p><h2
id="JAX-RS-Filters,InterceptorsandInvokers">Filters, Interceptors and
Invokers</h2><p>It is possible to intercept and modify the inbound and outbound
calls with the help of CXF JAX-RS filters and/or CXF interceptors.
Additionally, cust
om invokers offer an option to intercept a call immediately before a service
bean is invoked.</p><p>Please see the <a shape="rect"
href="jax-rs-filters.html">JAX-RS Filters</a> page for more
information.</p><p>Please see the <a shape="rect"
href="jax-rs-basics.html">JAX-RS Basics</a> page for more information about new
JAX-RS 2.0 filters and interceptors available in CXF 2.7.x and 3.0.0.</p><h2
id="JAX-RS-ServicelistingsandWADLsupport">Service listings and WADL
support</h2><p><strong>New</strong>: Swagger feature has been
introduced.</p><p>CXF JAX-RS supports <a shape="rect" class="external-link"
href="http://www.w3.org/Submission/wadl"; rel="nofollow">WADL</a>. CXF JAX-RS
service endpoints can be listed in the service listings page and users can
check the WADL documents.</p><p>Please see the <a shape="rect"
href="jaxrs-services-description.html">JAXRS Services Description</a> page for
more information.</p><h2 id="JAX-RS-ConfiguringJAX-RSservices">Configuring
JAX-RS services</h2><p>J
AX-RS services can be configured programmatically, using Blueprint, Spring or
CXFNonSpringJAXRSServlet.</p><p>Please see the <a shape="rect"
href="jaxrs-services-configuration.html">JAXRS Services Configuration</a> page
for more information.</p><h2 id="JAX-RS-Testing">Testing</h2><p>JAX-RS services
can be easily tested using the embedded Jetty or CXF Local Transport.<br
clear="none"> Please see the <a shape="rect"
href="https://cwiki.apache.org/confluence/display/CXF20DOC/JAXRS+Testing";>JAXRS
Testing</a> page for more information.</p><h2
id="JAX-RS-Debugging">Debugging</h2><p>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 :</p><p><code>> GET /resource.xml</code> <br clear="none">
<code>> GET /resource.en</code></p><p>The runtime will replace '.xm
l' 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:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"> <jaxrs:server id="customerService" address="/">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"> <jaxrs:server id="customerService" address="/">
<jaxrs:serviceBeans>
<bean class="org.apache.cxf.jaxrs.systests.CustomerService" />
</jaxrs:serviceBeans>
@@ -248,7 +248,7 @@ public void upload(@Multipart InputStrea
</jaxrs:server>
</pre>
</div></div><p>CXF also supports a _type query as an alternative to appending
extensions like '.xml' to request URIs:</p><p>{{ > GET
/resource?_type=xml}}</p><p>Overriding a request method is also
easy:</p><p><code>> GET /resource?_method=POST</code></p><p>Alternatively,
one can specify an HTTP header X-HTTP-Method-Override:</p><p><code>> POST
/books</code> <br clear="none"> <code>> X-HTTP-Method-Override :
PATCH</code></p><p>For example, at the moment the http-centric client API does
not support arbitrary HTTP verbs except for those supported <br clear="none">
by Java HTTPUrlConnection. When needed, X-HTTP-Method-Override can be set to
overcome this limitation.</p><p>Finally, a "_ctype" query allows for overriding
Content-Type.</p><p>Please see the <a shape="rect"
href="debugging-and-logging.html">Debugging and Logging</a> page for more
information on how to debug and log service calls in CXF.</p><h2
id="JAX-RS-Logging">Logging</h2><p>Many of the existing CXF features c
an be applied either to <code>jaxrs:server</code> or
<code>jaxrs:client</code>. For example, to enable logging of requests and
responses, simply do:</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><beans xmlns:cxf="http://cxf.apache.org/core";
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><beans xmlns:cxf="http://cxf.apache.org/core";
xsi:schemaLocation="http://cxf.apache.org/core
http://cxf.apache.org/schemas/core.xsd">
<jaxrs:server>
Modified: websites/production/cxf/content/docs/jax-ws-configuration.html
==============================================================================
--- websites/production/cxf/content/docs/jax-ws-configuration.html (original)
+++ websites/production/cxf/content/docs/jax-ws-configuration.html Wed Sep 13
15:05:52 2017
@@ -32,8 +32,8 @@
<link type="text/css" rel="stylesheet"
href="/resources/highlighter/styles/shThemeCXF.css">
<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/shBrushJava.js'></script>
<script>
SyntaxHighlighter.defaults['toolbar'] = false;
SyntaxHighlighter.all();
@@ -118,7 +118,7 @@ Apache CXF -- JAX-WS Configuration
<!-- Content -->
<div class="wiki-content">
<div id="ConfluenceContent"><p>Please see the <a shape="rect"
href="configuration.html">Configuration</a> section to learn how to supply a
configuration to CXF. The following sections include just JAX-WS specific
configuration items.</p><h1
id="JAX-WSConfiguration-ConfiguringanEndpoint">Configuring an Endpoint</h1><p>A
JAX-WS Endpoint can be configured in XML in addition to using the JAX-WS APIs.
Once you've created your <a shape="rect"
href="developing-a-service.html">server implementation</a>, you simply need to
provide the class name and an address. Here is a simple example:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><beans
xmlns="http://www.springframework.org/schema/beans";
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><beans
xmlns="http://www.springframework.org/schema/beans";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
xmlns:jaxws="http://cxf.apache.org/jaxws";
xsi:schemaLocation="
@@ -136,7 +136,7 @@ http://cxf.apache.org/jaxws http://cxf.a
</beans>
</pre>
</div></div><p>Be sure to include the JAX-WS <code>schemaLocation</code>
attribute specified on the root beans element. This allows CXF to validate the
file and is required. Also note the namespace declarations at the end of the
<jaxws:endpoint/> tag--these are required because the combined
"{namespace}localName" syntax is presently not supported for this tag's
attribute values.</p><p>The <code>jaxws:endpoint</code> element (which appears
to create an <a shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/jaxws/EndpointImpl.html";>EndpointImpl</a>
under the covers) supports many additional attributes:</p><div
class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1"
rowspan="1" class="confluenceTh"><p>Name</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Value</p></th></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>endpointName</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>The endpoint name this service
is implementing, it maps to the wsdl:port@name. In the format of
"ns:ENDPOINT_NAME" where ns is a namespace prefix valid at this
scope.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>publish</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Whether the endpoint should be published now, or
whether it will be published at a later point.</p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p>serviceName</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The service name this service is
implementing, it maps to the wsdl:service@name. In the format of
"ns:SERVICE_NAME" where ns is a namespace prefix valid at this
scope.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>wsdlLocation</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>The location of the WSDL. Can be on the classpath, file
system, or be hosted remotely.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>bindingUri</p></td><
td colspan="1" rowspan="1" class="confluenceTd"><p>The URI, or ID, of the
message binding for the endpoint to use. For SOAP the binding URI(ID) is
specified by the JAX-WS specification. For other message bindings the URI is
the namespace of the WSDL extensions used to specify the
binding.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>address</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>The service publish address</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>bus</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The bus name that will be used in the jaxws
endpoint.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>implementor</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>The implementor of jaxws endpoint. You can specify the
implementor class name here, or just the ref bean name in the format of
"#REF_BEAN_NAME"</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>i
mplementorClass</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>The implementor class name, it is really useful when
you specify the implementor with the ref bean which is wrapped by using Spring
AOP</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>createdFromAPI</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>This indicates that the endpoint bean was already
created using jaxws API's thus at runtime when parsing the bean spring can use
these values rather than the default ones. It's important that when this is
true, the "name" of the bean is set to the port name of the endpoint being
created in the form "{<span
class="nolink">http://</span>service.target.namespace}
PortName".</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>publishedEndpointUrl</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The URL that is placed in the address
element of the wsdl when the wsdl is retrieved. If not specified, the address l
isted above is used. This parameter allows setting the "public" URL that may
not be the same as the URL the service is deployed on. (for example, the
service is behind a proxy of some
sort).</p></td></tr></tbody></table></div><p>It also supports many child
elements:</p><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1"
class="confluenceTh"><p>Name</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Value</p></th></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>jaxws:executor</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>A Java executor which will be used for the service.
This can be supplied using the Spring <bean class="MyExecutor"/>
syntax.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>jaxws:inInterceptors</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The incoming interceptors for this
endpoint. A list of <bean>s or <ref>s. Each should implement <a sh
ape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/interceptor/Interceptor.html";>org.apache.cxf.interceptor.Interceptor</a>
or <a shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/phase/PhaseInterceptor.html";>org.apache.cxf.phase.PhaseInterceptor</a></p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p>jaxws:inFaultInterceptors</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The incoming fault interceptors for this
endpoint. A list of <bean>s or <ref>s. Each should implement <a
shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/interceptor/Interceptor.html";>org.apache.cxf.interceptor.Interceptor</a>
or <a shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/phase/PhaseInterceptor.html";>org.apache.cxf.phase.PhaseInterceptor</a></p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p>jaxws:outInterceptors</p></td><td colspan="1"
rowspan="1" class="confluenc
eTd"><p>The outgoing interceptors for this endpoint. A list of <bean>s
or <ref>s. Each should implement <a shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/interceptor/Interceptor.html";>org.apache.cxf.interceptor.Interceptor</a>
or <a shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/phase/PhaseInterceptor.html";>org.apache.cxf.phase.PhaseInterceptor</a></p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p>jaxws:outFaultInterceptors</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The outgoing fault interceptors for this
endpoint. A list of <bean>s or <ref>s. Each should implement <a
shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/interceptor/Interceptor.html";>org.apache.cxf.interceptor.Interceptor</a>
or <a shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/phase/PhaseInterceptor.html";>org.apache.cxf.phase.PhaseInterceptor</a></p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>jaxws:handlers</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>The JAX-WS handlers for this
endpoint. A list of <bean>s or <ref>s. Each should implement <a
shape="rect" class="external-link"
href="http://java.sun.com/javase/6/docs/api/javax/xml/ws/handler/Handler.html";
rel="nofollow">javax.xml.ws.handler.Handler</a> or <a shape="rect"
class="external-link"
href="http://java.sun.com/javase/6/docs/api/javax/xml/ws/handler/soap/SOAPHandler.html";
rel="nofollow">javax.xml.ws.handler.soap.SOAPHandler</a> (Note that
<code>@HandlerChain</code> annotations on the service bean appear to be
ignored)</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>jaxws:properties</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>A properties map which should be supplied to the JAX-WS
endpoint. See below.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>jaxws:dataBinding</p></td><td colspan
="1" rowspan="1" class="confluenceTd"><p>Which <a shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/databinding/DataBinding.html";>DataBinding</a>
to use in the endpoint. This can be supplied using the Spring <bean
class="MyDataBinding"/> syntax.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>jaxws:binding</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>You can specify the BindingFactory for this endpoint to
use. This can be supplied using the Spring <bean
class="MyBindingFactory"/> syntax.</p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p>jaxws:features</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The features that hold the interceptors for
this endpoint. A list of <bean>s or <ref>s</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>jaxws:invoker</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>The invoker which will be
supplied to this endpoi
nt. This can be supplied using the Spring <bean class="MyInvoker"/>
syntax.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>jaxws:schemaLocations</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The schema locations for endpoint to use. A
list of <schemaLocation>s</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>jaxws:serviceFactory</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The service factory for this endpoint to
use. This can be supplied using the Spring <bean
class="MyServiceFactory"/> syntax</p></td></tr></tbody></table></div><p>Here
is a more advanced example which shows how to provide interceptors and
properties:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><beans
xmlns="http://www.springframework.org/schema/beans";
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><beans
xmlns="http://www.springframework.org/schema/beans";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
xmlns:jaxws="http://cxf.apache.org/jaxws";
xmlns:soap="http://cxf.apache.org/bindings/soap";
@@ -186,7 +186,7 @@ http://cxf.apache.org/jaxws http://cxf.a
</beans>
</pre>
</div></div><p>If you are a Spring user, you'll notice that the
<code>jaxws:properties</code> element follows the Spring Map syntax.</p><h1
id="JAX-WSConfiguration-ConfiguringaSpringClient(Option1)">Configuring a Spring
Client (Option 1)</h1><div class="confluence-information-macro
confluence-information-macro-information"><span class="aui-icon aui-icon-small
aui-iconfont-info confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>This technique lets you add a Web
Services client to your Spring application. You can inject it into other Spring
beans, or manually retrieve it from the Spring context for use by
non-Spring-aware client code.</p></div></div><p>The easiest way to add a Web
Services client to a Spring context is to use the
<code><jaxws:client></code> element (similar to the
<code><jaxws:endpoint></code> element used for the server side). Here's a
simple example:</p><div class="code panel pdl" style="border-width: 1px;"><div c
lass="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><?xml version="1.0" encoding="UTF-8"?>
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans";
xmlns:jaxws="http://cxf.apache.org/jaxws";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
@@ -202,7 +202,7 @@ http://cxf.apache.org/jaxws http://cxf.a
</beans>
</pre>
</div></div><p>The attributes available on <code><jaxws:client></code>
include:</p><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1"
class="confluenceTh"><p>Name</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Type</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Description</p></th></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p>id</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>String</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>A unique identified for the client, which is how other
beans in the context will reference it</p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p>address</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>URL</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>The URL to connect to in order to invoke the
service</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>serviceClass</p></td><td colspan
="1" rowspan="1" class="confluenceTd"><p>Class</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The fully-qualified name of the interface
that the bean should implement (typically, same as the service interface used
on the server side)</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>serviceName</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>QName</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>The name of the service to invoke, if this address/WSDL
hosts several. It maps to the wsdl:service@name. In the format of
"ns:SERVICE_NAME" where ns is a namespace prefix valid at this
scope.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>endpointName</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>QName</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>The name of the endpoint to invoke, if this
address/WSDL hosts several. It maps to the wsdl:port@name. In the format of
"ns:ENDPOINT_NAME" wher
e ns is a namespace prefix valid at this scope.</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>bindingId</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>URI</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The URI, or ID, of the message binding for
the endpoint to use. For SOAP the binding URI(ID) is specified by the JAX-WS
specification. For other message bindings the URI is the namespace of the WSDL
extensions used to specify the binding.</p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p>bus</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Bean Reference</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>The bus name that will be used in the jaxws endpoint
(defaults to <code>cxf</code>).</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>username</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>String</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p> </p
></td></tr><tr><td colspan="1" rowspan="1"
>class="confluenceTd"><p>password</p></td><td colspan="1" rowspan="1"
>class="confluenceTd"><p>String</p></td><td colspan="1" rowspan="1"
>class="confluenceTd"><p> </p></td></tr><tr><td colspan="1" rowspan="1"
>class="confluenceTd"><p>wsdlLocation</p></td><td colspan="1" rowspan="1"
>class="confluenceTd"><p>URL</p></td><td colspan="1" rowspan="1"
>class="confluenceTd"><p>A URL to connect to in order to retrieve the WSDL for
>the service. This is not required.</p></td></tr><tr><td colspan="1"
>rowspan="1" class="confluenceTd"><p>createdFromAPI</p></td><td colspan="1"
>rowspan="1" class="confluenceTd"><p>boolean</p></td><td colspan="1"
>rowspan="1" class="confluenceTd"><p>This indicates that the client bean was
>already created using jaxws API's thus at runtime when parsing the bean
>spring can use these values rather than the default ones. It's important that
>when this is true, the "name" of the bean is set to the port name of the
>endpoint being cr
eated in the form "{<span
class="nolink">http://</span>service.target.namespace}PortName".</p></td></tr></tbody></table></div><p>It
also supports many child elements:</p><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1"
class="confluenceTh"><p>Name</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Description</p></th></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p>jaxws:inInterceptors</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>The incoming interceptors for
this endpoint. A list of <code><bean></code> or <code><ref></code>
elements. Each should implement <a shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/interceptor/Interceptor.html";>org.apache.cxf.interceptor.Interceptor</a>
or <a shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/phase/PhaseInterceptor.html";>org.apache.cxf.phase.PhaseInterceptor</a></p></td></tr><tr><td
colspan="1" rowspan="1" c
lass="confluenceTd"><p>jaxws:inFaultInterceptors</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The incoming fault interceptors for this
endpoint. A list of <code><bean></code> or <code><ref></code>
elements. Each should implement <a shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/interceptor/Interceptor.html";>org.apache.cxf.interceptor.Interceptor</a>
or <a shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/phase/PhaseInterceptor.html";>org.apache.cxf.phase.PhaseInterceptor</a></p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p>jaxws:outInterceptors</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The outgoing interceptors for this
endpoint. A list of <code><bean></code> or <code><ref></code>
elements. Each should implement <a shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/interceptor/Interceptor.html";>org.apache.cxf.interceptor.Interceptor</a>
or <a s
hape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/phase/PhaseInterceptor.html";>org.apache.cxf.phase.PhaseInterceptor</a></p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p>jaxws:outFaultInterceptors</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The outgoing fault interceptors for this
endpoint. A list of <code><bean></code> or <code><ref></code>
elements. Each should implement <a shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/interceptor/Interceptor.html";>org.apache.cxf.interceptor.Interceptor</a>
or <a shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/phase/PhaseInterceptor.html";>org.apache.cxf.phase.PhaseInterceptor</a></p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>jaxws:features</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>The features that hold the
interceptors for this endpoint. A list of <code><bean></code> or
<code><ref>
;</code> elements</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>jaxws:handlers</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>The JAX-WS handlers for this endpoint. A list of
<code><bean></code> or <code><ref></code> elements. Each should
implement <a shape="rect" class="external-link"
href="http://java.sun.com/javase/6/docs/api/javax/xml/ws/handler/Handler.html";
rel="nofollow">javax.xml.ws.handler.Handler</a> or <a shape="rect"
class="external-link"
href="http://java.sun.com/javase/6/docs/api/javax/xml/ws/handler/soap/SOAPHandler.html";
rel="nofollow">javax.xml.ws.handler.soap.SOAPHandler</a>. These are more
portable than CXF interceptors, but may cause the full message to be loaded in
as a DOM (slower for large messages).</p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p>jaxws:properties</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>A properties map which should be supplied
to the JAX-WS endpoint. See
below.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>jaxws:dataBinding</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Which <a shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/databinding/DataBinding.html";>DataBinding</a>
to use in the endpoint. This can be supplied using the Spring <bean
class="MyDataBinding"/> syntax.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>jaxws:binding</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>You can specify the BindingFactory for this endpoint to
use. This can be supplied using the Spring <bean
class="MyBindingFactory"/> syntax.</p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p>jaxws:conduitSelector</p></td><td
colspan="1" rowspan="1"
class="confluenceTd"><p> </p></td></tr></tbody></table></div><p>Here is a
more advanced example which shows how to provide interceptors, JAX-WS handlers,
and properties:</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent
pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><?xml version="1.0" encoding="UTF-8"?>
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans";
xmlns:jaxws="http://cxf.apache.org/jaxws";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
@@ -237,7 +237,7 @@ http://cxf.apache.org/jaxws http://cxf.a
</beans>
</pre>
</div></div><h1
id="JAX-WSConfiguration-ConfiguringaSpringClient(Option2)">Configuring a Spring
Client (Option 2)</h1><div class="confluence-information-macro
confluence-information-macro-information"><span class="aui-icon aui-icon-small
aui-iconfont-info confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>Building a Client using this
configuration is only applicable for those wishing to inject a Client into
their Spring ApplicationContext.</p></div></div><p>This approach requires more
explicit Spring bean configuration than the previous option, and may require
more configuration data depending on which features are used. To configure a
client this way, you'll need to declare a proxy factory bean and also a client
bean which is created by that proxy factory. <span
class="inline-comment-marker"
data-ref="e36053fa-0a8c-4646-8de0-c06e4c7fdde7">Here is an
example</span>:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeCon
tent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><beans
xmlns="http://www.springframework.org/schema/beans";
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><beans
xmlns="http://www.springframework.org/schema/beans";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
xmlns:jaxws="http://cxf.apache.org/jaxws";
xsi:schemaLocation="
@@ -258,7 +258,7 @@ http://cxf.apache.org/jaxws http://cxf.a
</beans>
</pre>
</div></div><p>The JaxWsProxyFactoryBean in this case takes two properties.
The service class, which is the interface of the Client proxy you wish to
create. The address is the address of the service you wish to call.</p><p>The
second bean definition is for the client. In this case it implements the
HelloWorld interface and is created by the proxyFactory <bean> by calling
the create() method. You can then reference this "client" bean and inject it
anywhere into your application. Here is an example of a very simple Java class
which accesses the client bean:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">include
org.springframework.context.support.ClassPathXmlApplicationContext;
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">include
org.springframework.context.support.ClassPathXmlApplicationContext;
public final class HelloWorldClient {
@@ -278,7 +278,7 @@ public final class HelloWorldClient {
}
</pre>
</div></div><p>The JaxWsProxyFactoryBean supports many other
properties:</p><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1"
class="confluenceTh"><p>Name</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Description</p></th></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p>clientFactoryBean</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The ClientFactoryBean used in construction
of this proxy.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>password</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>The password which the transport should
use.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>username</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>The username which the transport should
use.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>wsdlURL</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>The wsdl URL the c
lient should use to configure itself.</p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p>wsdlLocation</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Appears to be the same as
wsdlURL?</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>serviceName</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>The name of the service to invoke, if this address/WSDL
hosts several. It maps to the wsdl:service@name. In the format of
"ns:SERVICE_NAME" where ns is a namespace prefix valid at this
scope.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>endpointName</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>The name of the endpoint to invoke, if this
address/WSDL hosts several. It maps to the wsdl:port@name. In the format of
"ns:ENDPOINT_NAME" where ns is a namespace prefix valid at this
scope.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>inInterceptors</p></td><td colspan="1" rowspan=
"1" class="confluenceTd"><p>The incoming interceptors for this endpoint. A
list of <code><bean></code> or <code><ref></code> elements. Each
should implement <a shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/interceptor/Interceptor.html";>org.apache.cxf.interceptor.Interceptor</a>
or <a shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/phase/PhaseInterceptor.html";>org.apache.cxf.phase.PhaseInterceptor</a></p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p>inFaultInterceptors</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>The incoming fault interceptors for this endpoint. A
list of <code><bean></code> or <code><ref></code> elements. Each
should implement <a shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/interceptor/Interceptor.html";>org.apache.cxf.interceptor.Interceptor</a>
or <a shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/phase/PhaseIn
terceptor.html">org.apache.cxf.phase.PhaseInterceptor</a></p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>outInterceptors</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>The outgoing interceptors for
this endpoint. A list of <code><bean></code> or <code><ref></code>
elements. Each should implement <a shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/interceptor/Interceptor.html";>org.apache.cxf.interceptor.Interceptor</a>
or <a shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/phase/PhaseInterceptor.html";>org.apache.cxf.phase.PhaseInterceptor</a></p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p>outFaultInterceptors</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The outgoing fault interceptors for this
endpoint. A list of <code><bean></code> or <code><ref></code>
elements. Each should implement <a shape="rect"
href="http://cxf.apache.org/javadoc/latest/or
g/apache/cxf/interceptor/Interceptor.html">org.apache.cxf.interceptor.Interceptor</a>
or <a shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/phase/PhaseInterceptor.html";>org.apache.cxf.phase.PhaseInterceptor</a></p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>features</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>The features that hold the
interceptors for this endpoint. A list of <code><bean></code> or
<code><ref></code> elements</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>handlers</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>A list of <code><bean></code> or
<code><ref></code> elements pointing to JAX-WS handler classes to be used
for this client. Each should implement <a shape="rect" class="external-link"
href="http://java.sun.com/javase/6/docs/api/javax/xml/ws/handler/Handler.html";
rel="nofollow">javax.xml.ws.handler.Handler</a> or <a shape="rect" class="extern
al-link"
href="http://java.sun.com/javase/6/docs/api/javax/xml/ws/handler/soap/SOAPHandler.html";
rel="nofollow">javax.xml.ws.handler.soap.SOAPHandler</a>. These are more
portable than CXF interceptors, but may cause the full message to be loaded in
as a DOM (slower for large messages).</p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p>bindingConfig</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p> </p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p>bindingId</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The URI, or ID, of the message binding for
the endpoint to use. For SOAP the binding URI(ID) is specified by the JAX-WS
specification. For other message bindings the URI is the namespace of the WSDL
extensions used to specify the binding.</p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p>bus</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>A reference to a CXF bus bean. Must be provided i
f, for example, handlers are used. May require additional Spring context
imports (e.g. to bring in the default CXF bus bean).</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>conduitSelector</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p> </p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>dataBinding</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Which <a shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/databinding/DataBinding.html";>DataBinding</a>
to use in the endpoint. This can be supplied using the Spring <bean
class="MyDataBinding"/> syntax.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>properties</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>A properties map which should be supplied to the JAX-WS
endpoint.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>serviceFactory</p></td><td colspan="1" rowspan="1"
class="confluenceTd"
><p> </p></td></tr></tbody></table></div><p>Using some of the properties
>will require additional configuration in the Spring context. For instance,
>using JAX-WS handlers requires that you explicitly import several CXF Spring
>configurations, and assign the "bus" property of the JaxWsProxyFactory bean
>like this:</p><div class="code panel pdl" style="border-width: 1px;"><div
>class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><import resource="classpath:META-INF/cxf/cxf.xml"
/>
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><import resource="classpath:META-INF/cxf/cxf.xml"
/>
<import resource="classpath:META-INF/cxf/cxf-extension-soap.xml" />
<import resource="classpath:META-INF/cxf/cxf-extension-http.xml" />
@@ -289,7 +289,7 @@ public final class HelloWorldClient {
</bean>
</pre>
</div></div><h1
id="JAX-WSConfiguration-ConfiguringanEndpoint/ClientProxyUsingCXFAPIs">Configuring
an Endpoint/Client Proxy Using CXF APIs</h1><p>JAX-WS endpoints and client
proxies are implemented on top of CXF's frontend-neutral endpoint API. You can
therefore use CXF APIs to enhance the functionality of a JAX-WS endpoint or
client proxy, for example by adding interceptors.</p><p>To cast a client proxy
to a CXF client:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">GreeterService gs = new GreeterService();
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">GreeterService gs = new GreeterService();
Greeter greeter = gs.getGreeterPort();
org.apache.cxf.endpoint.Client client =
@@ -298,7 +298,7 @@ org.apache.cxf.endpoint.Endpoint cxfEndp
cxfEndpoint.getOutInterceptors().add(...);
</pre>
</div></div><p>To cast a JAX-WS endpoint to a CXF server:</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">javax.xml.ws.Endpoint jaxwsEndpoint =
javax.xml.ws.Endpoint.publish(
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">javax.xml.ws.Endpoint jaxwsEndpoint =
javax.xml.ws.Endpoint.publish(
"http://localhost:9020/SoapContext/GreeterPort";, new GreeterImpl());
org.apache.cxf.jaxws.EndpointImpl jaxwsEndpointImpl =
(org.apache.cxf.jaxws.EndpointImpl)jaxwsEndpoint;
@@ -309,7 +309,7 @@ org.apache.cxf.service.Service cxfServic
cxfService.getOutInterceptors().add(...);
</pre>
</div></div><h1
id="JAX-WSConfiguration-ConfiguretheJAXWSServer/ClientUsingSpring">Configure
the JAXWS Server/Client Using Spring</h1><p>CXF provides <jaxws:server>,
<jaxws:client> to configure the server/client side endpoint. Here are
some examples:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><beans
xmlns="http://www.springframework.org/schema/beans";
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><beans
xmlns="http://www.springframework.org/schema/beans";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
xmlns:jaxws="http://cxf.apache.org/jaxws";
xmlns:soap="http://cxf.apache.org/bindings/soap";
@@ -360,7 +360,7 @@ cxfService.getOutInterceptors().add(...)
</beans>
</pre>
</div></div><p>Since JAX-WS frontend server and client spring configuration
parser are inherited from the simple frontend, please see <a shape="rect"
href="simple-frontend-configuration.html">Simple Frontend Configuration</a> for
the attribute and element definitions.</p><p> </p><h1
id="JAX-WSConfiguration-ConfiguretheJAXWSServerUsingSpringBoot">Configure the
JAXWS Server Using SpringBoot</h1><p>Here is an example:</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Confluence"
style="font-size:12px;">import org.apache.cxf.Bus;
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">import org.apache.cxf.Bus;
import org.apache.cxf.jaxws.EndpointImpl;
import org.apache.cxf.transport.servlet.CXFServlet;
import org.springframework.beans.factory.annotation.Autowired;
Modified: websites/production/cxf/content/docs/jax-ws-dispatch-api.html
==============================================================================
--- websites/production/cxf/content/docs/jax-ws-dispatch-api.html (original)
+++ websites/production/cxf/content/docs/jax-ws-dispatch-api.html Wed Sep 13
15:05:52 2017
@@ -32,8 +32,8 @@
<link type="text/css" rel="stylesheet"
href="/resources/highlighter/styles/shThemeCXF.css">
<script src='/resources/highlighter/scripts/shCore.js'></script>
-<script src='/resources/highlighter/scripts/shBrushJava.js'></script>
<script src='/resources/highlighter/scripts/shBrushBash.js'></script>
+<script src='/resources/highlighter/scripts/shBrushJava.js'></script>
<script>
SyntaxHighlighter.defaults['toolbar'] = false;
SyntaxHighlighter.all();
@@ -193,7 +193,7 @@ Apache CXF -- JAX-WS Dispatch API
<p>To create a <code>Dispatch</code> object do the following:</p>
<ol><li>Create a <code>Service</code> object to represent the
<code>wsdl:service</code> element defining the service on which the
<code>Dispatch</code> object will make invocations.</li><li>Create the
<code>Dispatch</code> object using the <code>Service</code> object's
<code>createDispatch()</code> method.
<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">
public Dispatch<T> createDispatch(QName portName,
java.lang.Class<T> type, Service.Mode mode)
throws WebServiceException;
</pre>
@@ -201,7 +201,7 @@ throws WebServiceException;
<div class="confluence-information-macro
confluence-information-macro-note"><span class="aui-icon aui-icon-small
aui-iconfont-warning confluence-information-macro-icon"></span><div
class="confluence-information-macro-body">
<p>If you are using JAXB objects the method signature for
<code>createDispatch()</code> is:</p>
<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">
public Dispatch<T> createDispatch(QName portName,
javax.xml.bind.JAXBContext context, Service.Mode mode)
throws WebServiceException;
</pre>
@@ -214,7 +214,7 @@ throws WebServiceException;
<p>The code below creates a <code>Dispatch</code> object that works with
<code>DOMSource</code> objects in payload mode.</p>
<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">
package com.mycompany.demo;
import javax.xml.namespace.QName;
@@ -253,7 +253,7 @@ public class Client {
<p>For consumers that make synchronous invocations that generate a response,
you use the <code>Dispatch</code> object's <code>invoke()</code> method shown
bellow.</p>
<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">
T invoke(T msg) throws WebServiceException;
</pre>
</div></div>
@@ -262,7 +262,7 @@ T invoke(T msg) throws WebServiceExcepti
<p>When using JAXB objects, the response and the request can be of any type
the provided <code>JAXBContext</code> object can marshal and unmarshal. Also,
the response and the request can be different JAXB objects.</p></div></div>
<p>The code bellow makes a synchronous invocation on a remote service using a
<code>DOMSource</code> object.</p>
<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">
// Creating a DOMSource Object for the request
DocumentBuilder db = DocumentBuilderFactory.newDocumentBuilder();
Document requestDoc = db.newDocument();
@@ -281,14 +281,14 @@ DOMSource response = disp.invoke(request
<p>When using the polling approach the <code>invokeAsync()</code> method
returns a <code>Response<t></code> object that can be periodically polled
to see if the response has arrived.</p>
<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">
Response <T> invokeAsync(T msg) throws WebServiceException;
</pre>
</div></div>
<p>When using the callback approach the <code>invokeAsync()</code> method
takes an <code>AsyncHandler</code> implementation that processes the response
when it is returned.</p>
<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">
Future<?> invokeAsync(T msg, AsyncHandler<T> handler) throws
WebServiceException;
</pre>
</div></div>
@@ -300,7 +300,7 @@ Future<?> invokeAsync(T msg, Async
<p>When a request does not generate a response, you make remote invocations
using the <code>Dispatch</code> object's <code>invokeOneWay()</code>.</p>
<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">
void invokeOneWay(T msg) throws WebServiceException;
</pre>
</div></div>
@@ -309,7 +309,7 @@ void invokeOneWay(T msg) throws WebServi
<p>When using JAXB objects, the response and the request can be of any type
the provided <code>JAXBContext</code> object can marshal and unmarshal. Also,
the response and the request can be different JAXB objects.</p></div></div>
<p>The code bellow makes a one way invocation on a remote service using a JAXB
object.</p>
<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">
// Creating a JAXBContext and an Unmarshaller for the request
JAXBContext jbc = JAXBContext.newInstance("com.mycompany.StockExample");
Unmarshaller u = jbc.createUnmarshaller();
Modified: websites/production/cxf/content/docs/jaxb.html
==============================================================================
--- websites/production/cxf/content/docs/jaxb.html (original)
+++ websites/production/cxf/content/docs/jaxb.html Wed Sep 13 15:05:52 2017
@@ -117,7 +117,7 @@ Apache CXF -- JAXB
<!-- Content -->
<div class="wiki-content">
<div id="ConfluenceContent"><h1
id="JAXB-Introduction">Introduction</h1><p>JAXB is the default data binding for
CXF. If you don't specify one of the other data bindings in your Spring
configuration or through the API, you will get JAXB. Releases of CXF since
2.3.x have used the JDK7 default of JAXB 2.2, however Maven users running on
JDK 6 will need to use the <a shape="rect" class="external-link"
href="http://docs.oracle.com/javase/6/docs/technotes/guides/standards/";
rel="nofollow">Java endorsed override mechanism</a> to use JAXB 2.2 instead of
JAXB 2.1.</p><p>JAXB uses Java annotation combined with files found on the
classpath to build the mapping between XML and Java. JAXB supports both
code-first and schema-first programming. The schema-first support the ability
to create a client proxy, dynamically, at runtime. See the CXF
DynamicClientFactory class.</p><p>CXF uses the JAXB reference implementation.
To learn more about annotating your classes or how to generate beans from a sch
ema, please read the <a shape="rect" class="external-link"
href="https://jaxb.dev.java.net/guide/"; rel="nofollow">JAXB user's
guide</a>.</p><h1 id="JAXB-JAXBversusJAX-WS(orotherfront-ends)">JAXB versus
JAX-WS (or other front-ends)</h1><p>There are some pitfalls in the interaction
between the front end and the data binding. If you need detailed control over
the XML that travels on the wire, you may want to avoid the 'wrapped'
alternative, and stick with 'bare'. When you use the wrapped parameter style or
the RPC binding, the front ends construct more or less elaborate XML
representations for your operations. You have less control over those
constructs than you do over JAXB's mappings. In particular, developers with
detailed requirements to control the XML Schema 'elementFormDefault' or the use
or non-use of XML namespace prefixes often become frustrated because the JAXB
annotations for these options don't effect mappings that are purely the work of
the front-end. The safest course is
to use Document/Literal/Bare.</p><h1 id="JAXB-ConfiguringJAXB">Configuring
JAXB</h1><p>CXF allows you to configure JAXB in two ways.</p><h2
id="JAXB-JAXBProperties">JAXB Properties</h2><p>JAXB allows the application to
specify two sets of properties that modify its behavior: <em>context</em>
properties and <em>marshaller</em> properties. CXF allows applications to add
to these properties. <strong>Take care.</strong> In some cases, CXF sets these
properties for its own use.</p><p>You can add items to both of these property
sets via the JAXBDataBinding class. The 'contextProperties' and
'marshallerProperties' <em>properties</em> (in the Spring sense) of
JAXBDataBinding each store a Map<String, Object>. Whatever you put in the
map, CXF will pass along to JAXB. See the JAXB documentation for
details.</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>Example
of Configuring a Context Property</b></
div><div class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Confluence"
style="font-size:12px;"><jaxws:server id="bookServer"
+<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><jaxws:server id="bookServer"
serviceClass="org.myorg.mytypes.AnonymousComplexTypeImpl"
address="http://localhost:8080/act";
bus="cxf">
@@ -143,7 +143,7 @@ Apache CXF -- JAXB
</jaxws:server>
</pre>
</div></div><h2
id="JAXB-ActivatingJAXBValidationofSOAPrequestsandresponses">Activating JAXB
Validation of SOAP requests and responses</h2><p>Please see the <a shape="rect"
href="http://cxf.apache.org/faq.html#FAQ-HowcanIturnonschemavalidationforjaxwsendpoint?";>FAQ</a>.</p><h2
id="JAXB-NamespacePrefixManagement">Namespace Prefix Management</h2><p>The
JAXB reference implementation allows the application to provide an object that
in turn maps namespace URI's to prefixes. You can create such an object and
supply it via the marshaller properties. However, CXF provides an easier
process. The namespaceMap property of the JAXBDataBinding accepts a
Map<String, String>. Think of it as a map from namespace URI to namespace
prefix. If you load up this map, CXF will set up the necessary marshaller
property for you.</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width:
1px;"><b>Example of Configuring a Namespace Mappin
g</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Confluence"
style="font-size:12px;"><jaxws:server id="bookServer"
+<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><jaxws:server id="bookServer"
serviceClass="org.myorg.mytypes.AnonymousComplexTypeImpl"
address="http://localhost:8080/act";
bus="cxf">
