cxf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From dk...@apache.org
Subject svn commit: r1018111 [11/33] - in /websites/production/cxf/content: ./ cache/ docs/
Date Wed, 13 Sep 2017 15:05:57 GMT
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>&#160;</p><p>&#160;</p><p>&#160;</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("&lt;foo&gt;&lt;bar attr=\"3\"&gt;barValue&lt;/bar&gt;&lt;/foo&gt;".getBytes());
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">InputStream
is = new ByteArrayInputStream("&lt;foo&gt;&lt;bar attr=\"3\"&gt;barValue&lt;/bar&gt;&lt;/foo&gt;".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("&lt;bar attr=\"3\"&gt;barValue&lt;/bar&gt;", 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("&lt;foo&gt;&lt;bar attr=\"3\"&gt;value1&lt;/bar&gt;&lt;bar
attr=\"4\"&gt;value2&lt;/bar&gt;&lt;/foo&gt;".getBytes());
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">InputStream
is = new ByteArrayInputStream("&lt;foo&gt;&lt;bar attr=\"3\"&gt;value1&lt;/bar&gt;&lt;bar
attr=\"4\"&gt;value2&lt;/bar&gt;&lt;/foo&gt;".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("&lt;foo xmlns=\"http://foo\"&gt;&lt;ns1:bar xmlns:ns1=\"http://bar\"
attr=\"3\"&gt;barValue&lt;/bar&gt;&lt;/foo&gt;".getBytes());
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">InputStream
is = new ByteArrayInputStream("&lt;foo xmlns=\"http://foo\"&gt;&lt;ns1:bar xmlns:ns1=\"http://bar\"
attr=\"3\"&gt;barValue&lt;/bar&gt;&lt;/foo&gt;".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 = "&lt;customers xmlns=\"http://customers\"&gt;
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">String
xmlString = "&lt;customers xmlns=\"http://customers\"&gt;
                     + "&lt;customer id="1" homepage=\"http://customers/1\"/&gt;"
                     + "&lt;/customers&gt;";
 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 = "&lt;customers xmlns=\"http://customers\" xml:base="http://customers"&gt;
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">String
xmlString = "&lt;customers xmlns=\"http://customers\" xml:base="http://customers"&gt;
                     + "&lt;customer id="1"/&gt;&lt;customer id="2"/&gt;"
                     + "&lt;/customers&gt;";
 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;">
  &lt;map id="outTemplates"&gt;
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">  
&lt;map id="outTemplates"&gt;
       &lt;entry key="application/xml" value="classpath:/WEB-INF/templates/book-xml.xsl"/&gt;
       &lt;entry key="text/html" value="classpath:/WEB-INF/templates/book-html.xsl"/&gt;
       &lt;entry key="application/json" value="classpath:/WEB-INF/templates/book-json.xsl"/&gt;
@@ -267,27 +267,27 @@ public class Root {
   &lt;/bean&gt;
 </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;">
  &lt;bean id="xsltProvider" class="org.apache.cxf.jaxrs.provider.XSLTJaxbProvider"&gt;
   
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">  
&lt;bean id="xsltProvider" class="org.apache.cxf.jaxrs.provider.XSLTJaxbProvider"&gt;
   
       &lt;property name="outTemplate" value="classpath:/WEB-INF/templates/book-xml.xsl"/&gt;
       &lt;property name="inTemplate" class="classpath:/WEB-INF/templates/fromNewBookToOldBook.xsl"/&gt;
   &lt;/bean&gt;
 </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;">&lt;?xml-stylesheet
type="text/xsl" href="http://localhost/myapp/stylesheets/toHTML.xsl"?&gt;
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">&lt;?xml-stylesheet
type="text/xsl" href="http://localhost/myapp/stylesheets/toHTML.xsl"?&gt;
 &lt;products xmlns="http://products"&gt;
    &lt;product id="1"/&gt;
 &lt;/products&gt;
 </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;">&lt;?xml-stylesheet
type="text/css" href="http://localhost/myapp/stylesheets/HTMLDecorator.css"?&gt;
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">&lt;?xml-stylesheet
type="text/css" href="http://localhost/myapp/stylesheets/HTMLDecorator.css"?&gt;
 &lt;! 
    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();
 &lt;/html&gt;
 </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;">&lt;beans
xmlns:util="http://www.springframework.org/schema/util"&gt;
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">&lt;beans
xmlns:util="http://www.springframework.org/schema/util"&gt;
 &lt;bean id="jaxbProvider" class="org.apache.cxf.jaxrs.provider.JAXBElementProvider"&gt;
 &lt;map&gt;
 &lt;entry key="com.sun.xml.bind.xmlHeaders" 
@@ -310,7 +310,7 @@ client.path("/store/{id}", 1).get();
 &lt;/beans&gt;
 </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;">&lt;bean
id="jaxbProvider" class="org.apache.cxf.jaxrs.provider.JAXBElementProvider"&gt;
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">&lt;bean
id="jaxbProvider" class="org.apache.cxf.jaxrs.provider.JAXBElementProvider"&gt;
 &lt;property name="xmlResourceOffset" value="stylesheets"/&gt;
 &lt;/bean&gt;
 &lt;/beans&gt;
 </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>&#160;</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>&#160;</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>&#160;</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 {
 
 &#160;</pre>
 </div></div><p>&#160;</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;">&lt;bean
id="xsltProvider" class="org.apache.cxf.jaxrs.provider.XSLTJaxbProvider"&gt;
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">&lt;bean
id="xsltProvider" class="org.apache.cxf.jaxrs.provider.XSLTJaxbProvider"&gt;
 &lt;property name="supportJaxbOnly" value="true"/&gt;
 &lt;/bean&gt;
 </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;">&lt;products
xmlns="http://products"
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">&lt;products
xmlns="http://products"
    xmlns:xsi=""http://www.w3.org/2000/10/XMLSchema-instance""
    xsi:schemaLocation="http://localhost/myapp/schemas/product.xsd"&gt;
    &lt;product id="1"/&gt;
 &lt;/products&gt;
 </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>&#160;</p><p>&#160;</p><p>&#160;</p><p>&#160;</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;">&lt;?xml
version="1.0" encoding="UTF-8"?&gt;
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">&lt;?xml
version="1.0" encoding="UTF-8"?&gt;
 &lt;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"
 &lt;/beans&gt;
 </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 
 



Mime
View raw message