Modified: websites/production/cxf/content/docs/jax-rs-advanced-xml.html
==============================================================================
--- websites/production/cxf/content/docs/jax-rs-advanced-xml.html (original)
+++ websites/production/cxf/content/docs/jax-rs-advanced-xml.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,16 +121,16 @@ Apache CXF -- JAX-RS Advanced XML
</p><p></p><p> </p><p> </p><p> </p><p><style
type="text/css">/*<![CDATA[*/
-div.rbtoc1505311208788 {padding: 0px;}
-div.rbtoc1505311208788 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1505311208788 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1505314904350 {padding: 0px;}
+div.rbtoc1505314904350 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1505314904350 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1505311208788">
+/*]]>*/</style></p><div class="toc-macro rbtoc1505314904350">
<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RSAdvancedXML-XPathsupport">XPath support</a>
<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RSAdvancedXML-Introduction">Introduction</a></li><li><a shape="rect"
href="#JAX-RSAdvancedXML-UsingXMLSourceandXPathProviderintheapplicationcode">Using
XMLSource and XPathProvider in the application code</a></li></ul>
</li><li><a shape="rect" href="#JAX-RSAdvancedXML-XSLTsupport">XSLT
support</a></li><li><a shape="rect"
href="#JAX-RSAdvancedXML-XMLProcessingInstructions">XML Processing
Instructions</a></li><li><a shape="rect"
href="#JAX-RSAdvancedXML-XSLTTransform">XSLTTransform</a></li><li><a
shape="rect" href="#JAX-RSAdvancedXML-XSISchemaLocation">XSI Schema
Location</a></li></ul>
</div><h1 id="JAX-RSAdvancedXML-XPathsupport">XPath support</h1><p>XPath is
supported on the server and client sides with the help of <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/ext/xml/XMLSource.java";>XMLSource</a>
utility and <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/provider/XPathProvider.java";>XPathProvider</a>
provider classes. The difference between the two is that XPathProvider allows
for specifying the XPath expressions in the external configuration.</p><h2
id="JAX-RSAdvancedXML-Introduction">Introduction</h2><p>XMLSource allows for
converting matched XML DOM element, attribute and text nodes into typed complex
and primitive classes. DOM Node and Element classes as well as JAXP Source and
DOMSource can also be used. A single XMLSource instance can be used to query
the same input source
multiple times if the buffering mode is enabled.</p><p>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;">InputStream is = new
ByteArrayInputStream("<foo><bar
attr=\"3\">barValue</bar></foo>".getBytes());
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">InputStream is = new
ByteArrayInputStream("<foo><bar
attr=\"3\">barValue</bar></foo>".getBytes());
XMLSource xp = new XMLSource(is);
xp.setBuffering(true);
// query 1
@@ -146,7 +146,7 @@ Node node = xp.getNode("/foo/bar/@attr",
assertEquals("3", node.getTextValue());
</pre>
</div></div><p>In the above example a primitive attribute node is accessed in
a number of ways, using the same XMLSource instance. <br clear="none"> Matched
XML complex (element) nodes can be converted in a similar way:</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 Bar {
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">public class Bar {
@XmlAttribute
private String attr;
public String getAttribute() {
@@ -167,7 +167,7 @@ String value = xp.getValue("/foo/bar");
assertEquals("<bar attr=\"3\">barValue</bar>", value);
</pre>
</div></div><p>Note that JAXB is used internally to convert the matched XML
element into a class like Bar which does not have to have an @XmlRootElement
annotation. The 2nd query in the above example how a String representation of
the matched complex node can be captured.</p><p>XMLSource also provides methods
for capturing multiple nodes, 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;">InputStream is = new
ByteArrayInputStream("<foo><bar
attr=\"3\">value1</bar><bar
attr=\"4\">value2</bar></foo>".getBytes());
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">InputStream is = new
ByteArrayInputStream("<foo><bar
attr=\"3\">value1</bar><bar
attr=\"4\">value2</bar></foo>".getBytes());
XMLSource xp = new XMLSource(is);
xp.setBuffering(true);
// query 1
@@ -184,7 +184,7 @@ assertEquals(4, intValues[1]);
Bar[] nodes = xp.getNodes("/foo/bar", Bar.class);
</pre>
</div></div><p>All the above examples have been simplified in that no
namespaces have been used. Most real XML instances will have plenty of them and
XMLSource has methods accepting optional maps containing prefixes as keys and
namespaces as values:</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;">InputStream is = new ByteArrayInputStream("<foo
xmlns=\"http://foo\"><ns1:bar xmlns:ns1=\"http://bar\";
attr=\"3\">barValue</bar></foo>".getBytes());
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">InputStream is = new ByteArrayInputStream("<foo
xmlns=\"http://foo\"><ns1:bar xmlns:ns1=\"http://bar\";
attr=\"3\">barValue</bar></foo>".getBytes());
XMLSource xp = new XMLSource(is);
xp.setBuffering(true);
@@ -195,7 +195,7 @@ Bar foo = xp.getNode("/ps2:bar", Collect
assertNotNull(foo);
</pre>
</div></div><p>In the above example, a default "http://foo"; namespace
qualifies the root "foo" element while its 'bar' children are qualified with
the <br clear="none"> "http://bar"; namespace. Note that XMLSource is configured
to make sure these namespaces are checked but the prefixes used do not have to
match the ones in the actual XML instance which may not even have them at all,
for example, when default namespaces are used.</p><p>XMLSource also provides
few methods for capturing attribute or text values representing the HTTP
links:</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;">String xmlString = "<customers
xmlns=\"http://customers\">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">String xmlString = "<customers
xmlns=\"http://customers\">
+ "<customer id="1"
homepage=\"http://customers/1\"/>";
+ "</customers>";
InputStream is = new ByteArrayInputStream(xmlString.getBytes());
@@ -207,7 +207,7 @@ WebClient client = WebClient.create(home
// access the home page
</pre>
</div></div><p>In the above example the link to the home page of the customer
with id equal to '1' is retrieved and is used to create a WebClient
instance.</p><p>In some cases, the links are relative. In such cases the base
URI is already either known to the application code or it may be specified as
the value of the <a shape="rect" class="external-link"
href="http://www.w3.org/TR/xmlbase/"; rel="nofollow">xml:base</a> attribute. In
the latter case XMLSource makes it easy to get this base URI:</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;">String xmlString = "<customers
xmlns=\"http://customers\"; xml:base="http://customers">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">String xmlString = "<customers
xmlns=\"http://customers\"; xml:base="http://customers">
+ "<customer id="1"/><customer id="2"/>"
+ "</customers>";
InputStream is = new ByteArrayInputStream(xmlString.getBytes());
@@ -227,7 +227,7 @@ for (URI uri: relativeURIs) {
}
</pre>
</div></div><p>In the last example, a customer id also represents a relative
URI, with xml:base attribute pointing to a base URI.<br clear="none"> XMLSource
is used to get all the relative URIs, creates a WebClient with the base URI and
then iterates using individual relative URIs.</p><h2
id="JAX-RSAdvancedXML-UsingXMLSourceandXPathProviderintheapplicationcode">Using
XMLSource and XPathProvider in the application code</h2><p>Please see <a
shape="rect"
href="http://cxf.apache.org/docs/jax-rs-client-api.html#JAX-RSClientAPI-XMLcentricclients";>this
section</a> on how http-centric WebClients can use XPath, and here is an
example for the server side:</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;">@Path("/root")
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">@Path("/root")
public class Root {
@POST
public void post(XMLSource source) {
@@ -236,13 +236,13 @@ public class Root {
}
</pre>
</div></div><p>Users have an option to hide XPath expressions, by registering
an XPathProvider which is a JAX-RS MessageBodyReader, either on the client or
server sides. For 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;">XPathProvider provider = new XPathProvider();
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">XPathProvider provider = new XPathProvider();
provider.setGlobalExpression("/books/book[position() = 1]");
WebClient wc = WebClient.create("http://aggregated/data";,
Collections.singletonList(provider));
Book b = wc.get(Book.class);
</pre>
</div></div><h1 id="JAX-RSAdvancedXML-XSLTsupport">XSLT support</h1><p>XSLT is
currently supported by <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/provider/XSLTJaxbProvider.java";>XSLTJaxbProvider</a>.
This provider works relies on JAXB to initiate the transformation process and
can be used to produce pretty much any format, including non-XML ones.
Likewise, it can be used to extract XML data out of incoming XML fragments.
This provider can be used on the server and client sides.</p><p>Please see this
<a shape="rect" class="external-link"
href="http://sberyozkin.blogspot.com/2009/05/mvc-xml-way-with-cxf-jax-rs.html";
rel="nofollow">blog entry</a> for an overview of how this provider can help
with separating the presentation logic from the main application
code.</p><p>XSLTJaxbProvider can be configured to handle input or output data,
scoped by media types if needed. For example, one may config
ure it such that one template handles "application/xml" formats only while the
other one handles "application/json" writes only.</p><p>XSLTJaxbProvider uses
an injected JAX-RS UriInfo to inject all the usual JAX-RS information like
template or query parameters into a given XSLT template. These parameters will
be injected with the names equal to corresponding @PathParam, QueryParam, etc
values. Additionally, an absolute, base and relative path URIs will be injected
as "absolute.path", "base.path" and "relative.path" parameters. Finally, custom
inParameters and outParameters map properties can also be injected and they
will be added to all the XSLT template instances.</p><p>For example, given this
resource method definition:</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;">@Path("/root")
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">@Path("/root")
public class Root {
@GET
@Path("{id}")
@@ -253,7 +253,7 @@ public class Root {
}
</pre>
</div></div><p>the XSLT templates will have parameters with name 'id' and
'name' injected. In this particular case it may make sense to have two
templates, one for processing a Book XML stream (generated by JAXB) only, and
the other one for adding HTML specific elements. The HTML-specific template
will most likely import the template dealing with the Book stream.</p><p>Here
are some examples of how XSLTJaxbTemplate can be configured:</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;"> <map id="outTemplates">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"> <map id="outTemplates">
<entry key="application/xml"
value="classpath:/WEB-INF/templates/book-xml.xsl"/>
<entry key="text/html"
value="classpath:/WEB-INF/templates/book-html.xsl"/>
<entry key="application/json"
value="classpath:/WEB-INF/templates/book-json.xsl"/>
@@ -267,27 +267,27 @@ public class Root {
</bean>
</pre>
</div></div><p>In this example, the provider is injected with three out
templates, one for modifying the Book XML stream, the other one - for creating
an HTML Book representation and the last one for writing a JSON sequence which
the existing JSON providers may not be able to generate.</p><p>A 'uriResolver'
property can be used to point to a custom javax.xml.transform.URIResolver
implementation which can be used to resolve relative links in few XSLT
instructions such as 'import'/etc. A 'systemId' property can also be set.
Additionally, inProperties and outProperties map properties can be injected and
they will be used when XSLT template instances will be created.</p><p>Here is a
simpler configuration 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;"> <bean id="xsltProvider"
class="org.apache.cxf.jaxrs.provider.XSLTJaxbProvider">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"> <bean id="xsltProvider"
class="org.apache.cxf.jaxrs.provider.XSLTJaxbProvider">
<property name="outTemplate"
value="classpath:/WEB-INF/templates/book-xml.xsl"/>
<property name="inTemplate"
class="classpath:/WEB-INF/templates/fromNewBookToOldBook.xsl"/>
</bean>
</pre>
</div></div><p>The provider is configured with one output template and one
input template which will apply to all request and response data.</p><p>When
XSLTJaxbProvider is used for processing the incoming requests, its main goal is
to ensure the incoming XML can be adapted as needed for the JAXB unmarshalling
to succeed. The in template can modify the incoming XML in a number of ways or
it can extract the XML fragment out of the bigger XML instance which is similar
to what XMLSource and XPathProvider can do as well. Please also check the new
<a shape="rect"
href="http://cxf.apache.org/docs/transformationfeature.html";>Transformation</a>
feature.</p><p>Note that XSLTJaxbProvider may be used with other XML-aware
providers on the same endpoint if needed. In such cases one needs to restrict
the set of classes it can handle, for it to not interfere with the other XML
provider. This can be done using inClassNames and outClassNames list properties
which enumerate supported class names. Alte
rnatively, a new "supportJaxbOnly" property can be set, in which case
XSLTJaxbProvider will simply delegate to JAXBElementProvider if no template is
available for a given class.</p><p>Note that when XSLTJaxbProvider is used on
the client side, it may not always be possible for template parameters be
injected in cases when http-centric clients are used (as opposed to proxies).
For 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;">WebClient client = WebClient.create("http://books";);
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">WebClient client = WebClient.create("http://books";);
client.path("/store/1").get();
</pre>
</div></div><p>it is not possible to deduce that '1' represents a template
parameter in the "/store/1" expression. However, one can use the following code
instead if '1' needs to be available to XSLT templates :</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;">WebClient client = WebClient.create("http://books";);
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">WebClient client = WebClient.create("http://books";);
client.path("/store/{id}", 1).get();
</pre>
</div></div><h1 id="JAX-RSAdvancedXML-XMLProcessingInstructions">XML
Processing Instructions</h1><p>One way to get outbound XML transformed to HTML
or get an XHTML payload further decorated with CSS tags is to <a shape="rect"
class="external-link" href="http://www.w3.org/TR/xml-stylesheet/";
rel="nofollow">associate an xml-stylesheet processing instruction</a> with the
XML payload, for 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;"><?xml-stylesheet type="text/xsl"
href="http://localhost/myapp/stylesheets/toHTML.xsl"?>
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><?xml-stylesheet type="text/xsl"
href="http://localhost/myapp/stylesheets/toHTML.xsl"?>
<products xmlns="http://products">
<product id="1"/>
</products>
</pre>
</div></div><p>The browser will fetch a stylesheet from the server and will
transform this XML on the client's machine.<br clear="none"> This option is
alternative to using XSLTJaxbProvider to create HTML on the server side. It may
become less easy to use if XSL stylesheets importing other documents or rely on
additional parameters to produce the HTML but it can definitely be used to
offload the cost of doing the transformations from the server in some
cases.</p><p>You can also combine XSLTJaxbProvider to create complex HTML on
the server and use xml-stylesheet instructions to get the browser to download
and cache the CSS stylesheets, for 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;"><?xml-stylesheet type="text/css"
href="http://localhost/myapp/stylesheets/HTMLDecorator.css"?>
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><?xml-stylesheet type="text/css"
href="http://localhost/myapp/stylesheets/HTMLDecorator.css"?>
<!
XSLTJaxbProvider transformed the XML products payload into well-formed
XHTML.
The browser will get HTMLDecorator.css at the next step and apply it to
this HTML
@@ -300,7 +300,7 @@ client.path("/store/{id}", 1).get();
</html>
</pre>
</div></div><p>When working with JAXB, the way to add such xml processing
instructions is to set a <br clear="none"> "com.sun.xml.bind.xmlHeaders" or
"com.sun.xml.internal.bind.xmlHeaders" on the JAXB Marshaller.</p><p>Up until
CXF 2.5.1 the way to do is to use a JAXBElementProvider 'marshallerProperties'
map property, for 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:util="http://www.springframework.org/schema/util">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><beans
xmlns:util="http://www.springframework.org/schema/util">
<bean id="jaxbProvider"
class="org.apache.cxf.jaxrs.provider.JAXBElementProvider">
<map>
<entry key="com.sun.xml.bind.xmlHeaders"
@@ -310,7 +310,7 @@ client.path("/store/{id}", 1).get();
</beans>
</pre>
</div></div><p>The problem here is how to correctly point to an absolute URI
identifying the toHTML.xsl resource.<br clear="none"> Assuming that the browser
will correctly resolve a relative URI such as "/stylesheets/toHTML.xsl", then
all is set.<br clear="none"> Otherwise the best option is to extend
JAXBElementProvider and set marshaller properties there by using JAX-RS UriInfo
to get to the base request URI.</p><p>Starting from CXF 2.5.1 and 2.4.5 one can
use an <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/ext/xml/XMLInstruction.java";>XMLInstruction</a>
annotation:</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;">@Path("products")
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">@Path("products")
public class Resource {
@GET
@Produces("application/xml")
@@ -319,13 +319,13 @@ public class Resource {
}
</pre>
</div></div><p>Lets assume one runs a 'myapp' web application with CXFServlet
listening on "/services/*", which can accept requests such as "GET <a
shape="rect" class="external-link"
href="http://localhost/myapp/services/products";
rel="nofollow">http://localhost/myapp/services/products</a>".</p><p>The above
relative href value will be converted to
"http://localhost/myapp/stylesheets/toHTML.xsl"; thus making it easy to
resources not 'covered' by CXFServlet. What if you prefer not to even list
'stylesheets' in href='/stylesheets/toHTML.xsl' given that the name of the
resource folder may change ?<br clear="none"> Use an 'xmlResourceOffset'
property of JAXBElementProvider:</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;"><bean id="jaxbProvider"
class="org.apache.cxf.jaxrs.provider.JAXBElementProvider">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><bean id="jaxbProvider"
class="org.apache.cxf.jaxrs.provider.JAXBElementProvider">
<property name="xmlResourceOffset" value="stylesheets"/>
</bean>
</beans>
</pre>
</div></div><p>and only have href='toHTML.xsl'. You can also use
xmlResourceOffset to make sure the absolute URI will be covered by CXFServlet
if preferred.</p><h1
id="JAX-RSAdvancedXML-XSLTTransform">XSLTTransform</h1><p> </p><p><a
shape="rect" class="external-link"
href="https://git-wip-us.apache.org/repos/asf?p=cxf.git;a=blob;f=rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/ext/xml/XSLTTransform.java;h=245106caa903c4ec4612fb65ecc01061004fae67;hb=HEAD";>XSLTTransform</a>
is a new annotation introduced in CXF 3.0.0. It can support either server or
client driven transformations.</p><p>Single XSLTTransform annotation can also
support both client and server transformations.</p><p>Its 'mediaTypes'
property, if enabled, is used to restrict the server-based transformations to
the listed media types only and expected to be a subset of JAX-RS Produces
value.</p><p> </p><p>XSLTTransform can be used in SERVER, CLIENT or BOTH
modes.</p><p>For it to be effective for the server s
ide transformations (SERVER, BOTH), it has to be used in conjunction with
XSLTJaxbProvider.</p><p>Default JAXBElementProvider will support XSLTransform
CLIENT mode independently.</p><p>When it is used either in CLIENT or BOTH modes
to let the clients run the transformations it is processed by
JAXBElementProvider and is converted into XML XSL instruction.</p><p>Using it
in BOTH mode effectively supports a transformation 'negotiation': the clients
which can do the transformation themselves will have an XML XSL instruction
added to the response XML payloads,</p><p>and in other case the server will run
the transformations.</p><p>Examples:</p><p> </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;">// server based Products to XML transformation
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">// server based Products to XML transformation
@Path("products")
public class Resource {
@GET
@@ -379,19 +379,19 @@ public class Resource {
 </pre>
</div></div><p> </p><p>Typically you do not need to configure either XSLT
or JAXB providers with the additional properties for XSLTTransform be effective
unless BOTH mode is used, in this case simply set XSLTJaxbProvider
"supportJaxbOnly":</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;"><bean id="xsltProvider"
class="org.apache.cxf.jaxrs.provider.XSLTJaxbProvider">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><bean id="xsltProvider"
class="org.apache.cxf.jaxrs.provider.XSLTJaxbProvider">
<property name="supportJaxbOnly" value="true"/>
</bean>
</pre>
</div></div><p>The above configuration is sufficient to have XSLTTransform
BOTH mode supported.</p><h1 id="JAX-RSAdvancedXML-XSISchemaLocation">XSI Schema
Location</h1><p>Some tools such as <a shape="rect" class="external-link"
href="http://office.microsoft.com/en-us/excel-help/get-and-analyze-data-from-the-web-in-excel-HA001054848.aspx";
rel="nofollow">Microsoft Excel</a> can do WEB queries and import the XML
payload but this payload is expected to use an xsi:schemaLocation attribute
pointing to the XML schema document describing this XML, for 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;"><products xmlns="http://products";
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><products xmlns="http://products";
xmlns:xsi=""http://www.w3.org/2000/10/XMLSchema-instance"";
xsi:schemaLocation="http://localhost/myapp/schemas/product.xsd">
<product id="1"/>
</products>
</pre>
</div></div><p>In order to get this attribute set with JAXB, one needs to use
a "javax.xml.bind.Marshaller.JAXB_SCHEMA_LOCATION" property which can be set on
JAXBElementProvider directly (similarly to the way XML Processing Instructions
set, see the previous section) or, starting with CXF 2.5.1, with the help of a
new <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/ext/xml/XSISchemaLocation.java";>XSISchemaLocation</a>
annotation:</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;">@Path("products")
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">@Path("products")
public class Resource {
@GET
@Produces("application/xml")
Modified: websites/production/cxf/content/docs/jax-rs-and-jax-ws.html
==============================================================================
--- websites/production/cxf/content/docs/jax-rs-and-jax-ws.html (original)
+++ websites/production/cxf/content/docs/jax-rs-and-jax-ws.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,14 +121,14 @@ Apache CXF -- JAX-RS and JAX-WS
</p><p> </p><p> </p><p> </p><p> </p><p><style
type="text/css">/*<![CDATA[*/
-div.rbtoc1505311268186 {padding: 0px;}
-div.rbtoc1505311268186 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1505311268186 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1505314889339 {padding: 0px;}
+div.rbtoc1505314889339 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1505314889339 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1505311268186">
+/*]]>*/</style></p><div class="toc-macro rbtoc1505314889339">
<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RSandJAX-WS-JAX-RSandJAX-WS">JAX-RS and JAX-WS</a></li><li><a
shape="rect" href="#JAX-RSandJAX-WS-Dealingwithcontexts">Dealing with
contexts</a></li><li><a shape="rect"
href="#JAX-RSandJAX-WS-SharingCXFDataBindings">Sharing CXF
DataBindings</a></li><li><a shape="rect"
href="#JAX-RSandJAX-WS-SharingJAX-RSProviders">Sharing JAX-RS
Providers</a></li><li><a shape="rect"
href="#JAX-RSandJAX-WS-Applyingexternalusermodels">Applying external user
models</a></li></ul>
</div><h1 id="JAX-RSandJAX-WS-JAX-RSandJAX-WS">JAX-RS and JAX-WS</h1><p>Here's
a beans.xml showing how to have a single service class supporting both SOAP and
REST-based invocations at the same time with the help of JAX-WS and JAX-RS
:</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:xsi="http://www.w3.org/2001/XMLSchema-instance";
xmlns:jaxrs="http://cxf.apache.org/jaxrs";
@@ -160,18 +160,18 @@ http://cxf.apache.org/schemas/jaxws.xsd";
</beans>
</pre>
</div></div><p>Either contract-first or Java-first approach can be used for
JAX-WS. JAX-RS annotations can be added to the existing service class. Some
custom providers may need to be created, depending on the complexity of the
method signatures.</p><p>When a WSDL-first approach is used then a
document-literal-wrapped style may or may not be a good fit as the code
generator unwraps all the types into a signature, for 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;">public class CustomerService {
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">public class CustomerService {
public void doIt(String a, String b) {...};
}
</pre>
</div></div><p>By default JAX-RS may not be able to handle such methods as it
requires that only a single parameter can be available in a signature that is
not annotated by one of the JAX-RS annotations like @PathParam. So if <br
clear="none"> a 'String a' parameter can be mapped to a @Path template variable
or one of the query segments then this signature won't need to be changed
:</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;">@Path("/customers/{a}")
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">@Path("/customers/{a}")
public class CustomerService {
public void doIt(@PathParam("a") String a, String b) {...};
}
</pre>
</div></div><p>Note that CXF Continuations API is supported for both JAXWS and
JAXRS services.</p><h1 id="JAX-RSandJAX-WS-Dealingwithcontexts">Dealing with
contexts</h1><p>When combining JAXWS and JAXRS, one may need to access some
context information as part of processing a given request. At the moment, CXF
JAXRS does not offer a context implementation which can be used to access a
request-specific information common for both JAXWS and JAXRS requests, in cases
when the same methods are used to handle both JAXWS and JAXRS requests. Please
use a JAXWS WebServiceContext and JAXRS contexts or CXF JAXRS composite
MessageContext :</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;">@Path("/customers")
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">@Path("/customers")
@WebService
public class CustomerService {
@@ -196,7 +196,7 @@ public class CustomerService {
}
</pre>
</div></div><p>Note that injected context instances (jaxwsContext and
jaxrsContext) are in fact thread-local proxies hence they will not be equal to
null even if they do not represent a given request. For example, jaxrsContext
will not be equal to null even if it's not a JAXWS invocation which is being
processed at the moment.</p><p>However, if say a (JAXWS or JAXRS)
SecurityContext needs to be accessed then it will be set in, say, jaxwsContext
only if it's a JAXWS/SOAP invocation. For this reason it can be handy using a
composite CXF JAXRS MessageContext when accessing a JAXRS-specific context
information when combining JAXWS and JAXRS as one can easily check if it's
actually a JAXRS request by simply checking an individual context like
SecurityContext or UriInfo for null.</p><p>Using individual contexts like JAXRS
SecurityContext might be less attractive :</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;">@WebService
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">@WebService
public class CustomerService {
@Context WebServiceContext jaxwsContext;
// @Resource can be applied too
@@ -204,7 +204,7 @@ public class CustomerService {
}
</pre>
</div></div><p>as some methods of SecurityContext return boolean values so
only throwing a runtime exception can reliably indicate that this context is
actually not in scope.</p><p>Note that if you do not share the same service
methods between JAXRS and JAXWS invocations then you can directly access
corresponding contexts :</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;">@Path("/customers")
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">@Path("/customers")
@WebService
public class CustomerService
