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 Mon Jun 24 17:10:51 2013 @@ -25,6 +25,18 @@ <meta http-equiv="Content-type" content="text/html;charset=UTF-8"> <meta name="keywords" content="business integration, EAI, SOA, Service Oriented Architecture, web services, SOAP, JBI, JMS, WSDL, XML, EDI, Electronic Data Interchange, standards support, integration standards, application integration, middleware, software, solutions, services, CXF, open source"> <meta name="description" content="Apache CXF, Services Framework - JAX-RS Advanced XML"> + + <link href='http://cxf.apache.org/resources/highlighter/styles/shCore.css' rel='stylesheet' type='text/css' /> + <link href='http://cxf.apache.org/resources/highlighter/styles/shThemeCXF.css' rel='stylesheet' type='text/css' /> + <script src='http://cxf.apache.org/resources/highlighter/scripts/shCore.js' type='text/javascript'></script> + <script src='http://cxf.apache.org/resources/highlighter/scripts/shBrushJava.js' type='text/javascript'></script> + <script src='http://cxf.apache.org/resources/highlighter/scripts/shBrushXml.js' type='text/javascript'></script> + + <script type="text/javascript"> + SyntaxHighlighter.defaults['toolbar'] = false; + SyntaxHighlighter.all(); + </script> + <title> Apache CXF -- JAX-RS Advanced XML </title> @@ -42,19 +54,15 @@ Apache CXF -- JAX-RS Advanced XML <td id="cell-1-0"> </td> <td id="cell-1-1"> </td> <td id="cell-1-2"> - <div style="padding: 5px;"> - <div id="banner"> - <!-- Banner --> -<div id="banner-content"> + <!-- Banner --> +<div class="banner" id="banner"><p> <table border="0" cellpadding="0" cellspacing="0" width="100%"><tr><td align="left" colspan="1" nowrap> <a shape="rect" href="http://cxf.apache.org/"; title="Apache CXF"><span style="font-weight: bold; font-size: 170%; color: white">Apache CXF</span></a> </td><td align="right" colspan="1" nowrap> <a shape="rect" href="http://www.apache.org/"; title="The Apache Sofware Foundation"><img border="0" alt="ASF Logo" src="http://cxf.apache.org/images/asf-logo.png";></a> </td></tr></table> -</div> - <!-- Banner --> - </div> - </div> +</p></div> + <!-- Banner --> <div id="top-menu"> <table border="0" cellpadding="1" cellspacing="0" width="100%"> <tr> @@ -94,7 +102,7 @@ Apache CXF -- JAX-RS Advanced XML <hr> -<ul class="alternate" type="square"><li>Search +<ul class="alternate" type="square"><li>Search<br clear="none"> <form enctype="application/x-www-form-urlencoded" method="get" id="cse-search-box" action="http://www.google.com/cse";> <div> @@ -137,49 +145,49 @@ Apache CXF -- JAX-RS Advanced XML <p>Here are some examples:</p> <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -InputStream is = <span class="code-keyword">new</span> ByteArrayInputStream(<span class="code-quote">"<foo><bar attr=\"</span>3\<span class="code-quote">">barValue</bar></foo>"</span>.getBytes()); -XMLSource xp = <span class="code-keyword">new</span> XMLSource(is); -xp.setBuffering(<span class="code-keyword">true</span>); -<span class="code-comment">// query 1 -</span><span class="code-object">String</span> value = xp.getValue(<span class="code-quote">"/foo/bar/@attr"</span>); -assertEquals(<span class="code-quote">"3"</span>, value); +<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ +InputStream is = new ByteArrayInputStream("<foo><bar attr=\"3\">barValue</bar></foo>".getBytes()); +XMLSource xp = new XMLSource(is); +xp.setBuffering(true); +// query 1 +String value = xp.getValue("/foo/bar/@attr"); +assertEquals("3", value); -<span class="code-comment">// query 2 -</span><span class="code-object">Integer</span> intValue = xp.getNode(<span class="code-quote">"/foo/bar/@attr"</span>, <span class="code-object">Integer</span>.class); +// query 2 +Integer intValue = xp.getNode("/foo/bar/@attr", Integer.class); assertEquals(3, intValue); -<span class="code-comment">// query 3 -</span>Node node = xp.getNode(<span class="code-quote">"/foo/bar/@attr"</span>, Node.class); -assertEquals(<span class="code-quote">"3"</span>, node.getTextValue()); -</pre> +// query 3 +Node node = xp.getNode("/foo/bar/@attr", Node.class); +assertEquals("3", node.getTextValue()); +]]></script> </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" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-keyword">public</span> class Bar { +<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ +public class Bar { @XmlAttribute - <span class="code-keyword">private</span> <span class="code-object">String</span> attr; - <span class="code-keyword">public</span> <span class="code-object">String</span> getAttribute() { - <span class="code-keyword">return</span> attr; + private String attr; + public String getAttribute() { + return attr; } } -InputStream is = <span class="code-keyword">new</span> ByteArrayInputStream(<span class="code-quote">"<foo><bar attr=\"</span>3\<span class="code-quote">">barValue</bar></foo>"</span>.getBytes()); -XMLSource xp = <span class="code-keyword">new</span> XMLSource(is); -xp.setBuffering(<span class="code-keyword">true</span>); - -<span class="code-comment">// query 1 -</span>Bar bean = xp.getNode(<span class="code-quote">"/foo/bar"</span>, Bar.class); -assertEquals(<span class="code-quote">"3"</span>, bean.getAttribute()); +InputStream is = new ByteArrayInputStream("<foo><bar attr=\"3\">barValue</bar></foo>".getBytes()); +XMLSource xp = new XMLSource(is); +xp.setBuffering(true); + +// query 1 +Bar bean = xp.getNode("/foo/bar", Bar.class); +assertEquals("3", bean.getAttribute()); -<span class="code-comment">// query 2 -</span><span class="code-object">String</span> value = xp.getValue(<span class="code-quote">"/foo/bar"</span>); -assertEquals(<span class="code-quote">"<bar attr=\"</span>3\<span class="code-quote">">barValue</bar>"</span>, value); -</pre> +// query 2 +String value = xp.getValue("/foo/bar"); +assertEquals("<bar attr=\"3\">barValue</bar>", value); +]]></script> </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> @@ -187,39 +195,39 @@ assertEquals(<span class="code-quote">"& <p>XMLSource also provides methods for capturing multiple nodes, example:</p> <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -InputStream is = <span class="code-keyword">new</span> ByteArrayInputStream(<span class="code-quote">"<foo><bar attr=\"</span>3\<span class="code-quote">">value1</bar><bar attr=\"</span>4\<span class="code-quote">">value2</bar></foo>"</span>.getBytes()); -XMLSource xp = <span class="code-keyword">new</span> XMLSource(is); -xp.setBuffering(<span class="code-keyword">true</span>); -<span class="code-comment">// query 1 -</span><span class="code-object">String</span>[] values = xp.getValue(<span class="code-quote">"/foo/bar/text()"</span>); -assertEquals(<span class="code-quote">"value1"</span>, values[0]); -assertEquals(<span class="code-quote">"value2"</span>, values[1]); +<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ +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 +String[] values = xp.getValue("/foo/bar/text()"); +assertEquals("value1", values[0]); +assertEquals("value2", values[1]); -<span class="code-comment">// query 2 -</span><span class="code-object">Integer</span>[] intValues = xp.getNodes(<span class="code-quote">"/foo/bar/@attr"</span>, <span class="code-object">Integer</span>.class); +// query 2 +Integer[] intValues = xp.getNodes("/foo/bar/@attr", Integer.class); assertEquals(3, intValues[0]); assertEquals(4, intValues[1]); -<span class="code-comment">// query 3 -</span>Bar[] nodes = xp.getNodes(<span class="code-quote">"/foo/bar"</span>, Bar.class); -</pre> +// query 3 +Bar[] nodes = xp.getNodes("/foo/bar", Bar.class); +]]></script> </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" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -InputStream is = <span class="code-keyword">new</span> ByteArrayInputStream(<span class="code-quote">"<foo xmlns=\"</span>http:<span class="code-comment">//foo\<span class="code-quote">"><ns1:bar xmlns:ns1=\"</span>http://bar\<span class="code-quote">" attr=\"</span>3\<span class="code-quote">">barValue</bar></foo>"</span>.getBytes()); -</span>XMLSource xp = <span class="code-keyword">new</span> XMLSource(is); -xp.setBuffering(<span class="code-keyword">true</span>); - -Foo foo = xp.getNode(<span class="code-quote">"/ps1:foo"</span>, Collections.singletonMap(<span class="code-quote">"ps1"</span>, <span class="code-quote">"http:<span class="code-comment">//foo"</span>), Foo.class); -</span>assertNotNull(foo); - -Bar foo = xp.getNode(<span class="code-quote">"/ps2:bar"</span>, Collections.singletonMap(<span class="code-quote">"ps2"</span>, <span class="code-quote">"http:<span class="code-comment">//bar"</span>), Bar.class); -</span>assertNotNull(foo); -</pre> +<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ +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); + +Foo foo = xp.getNode("/ps1:foo", Collections.singletonMap("ps1", "http://foo";), Foo.class); +assertNotNull(foo); + +Bar foo = xp.getNode("/ps2:bar", Collections.singletonMap("ps2", "http://bar";), Bar.class); +assertNotNull(foo); +]]></script> </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"> @@ -228,18 +236,18 @@ Bar foo = xp.getNode(<span class="code-q <p>XMLSource also provides few methods for capturing attribute or text values representing the HTTP links:</p> <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-object">String</span> xmlString = <span class="code-quote">"<customers xmlns=\"</span>http:<span class="code-comment">//customers\"> -</span> + <span class="code-quote">"<customer id="</span>1<span class="code-quote">" homepage=\"</span>http:<span class="code-comment">//customers/1\<span class="code-quote">"/>"</span> -</span> + <span class="code-quote">"</customers>"</span>; -InputStream is = <span class="code-keyword">new</span> ByteArrayInputStream(xmlString.getBytes()); -XMLSource xp = <span class="code-keyword">new</span> XMLSource(is); - -URI homePage = xp.getLink(<span class="code-quote">"/ps1:customer[@id='1']/@homePage"</span>, - Collections.singletonMap(<span class="code-quote">"ps1"</span>, <span class="code-quote">"http:<span class="code-comment">//customers"</span>)); -</span>WebClient client = WebClient.create(homePage); -<span class="code-comment">// access the home page</span> -</pre> +<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ +String xmlString = "<customers xmlns=\"http://customers\"> + + "<customer id="1" homepage=\"http://customers/1\"/>"; + + "</customers>"; +InputStream is = new ByteArrayInputStream(xmlString.getBytes()); +XMLSource xp = new XMLSource(is); + +URI homePage = xp.getLink("/ps1:customer[@id='1']/@homePage", + Collections.singletonMap("ps1", "http://customers";)); +WebClient client = WebClient.create(homePage); +// access the home page +]]></script> </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> @@ -247,26 +255,26 @@ URI homePage = xp.getLink(<span class="c <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" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-object">String</span> xmlString = <span class="code-quote">"<customers xmlns=\"</span>http:<span class="code-comment">//customers\<span class="code-quote">" xml:base="</span>http://customers"> -</span> + <span class="code-quote">"<customer id="</span>1<span class="code-quote">"/><customer id="</span>2<span class="code-quote">"/>"</span> - + <span class="code-quote">"</customers>"</span>; -InputStream is = <span class="code-keyword">new</span> ByteArrayInputStream(xmlString.getBytes()); -XMLSource xp = <span class="code-keyword">new</span> XMLSource(is); -xp.setBuffering(<span class="code-keyword">true</span>); +<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ +String xmlString = "<customers xmlns=\"http://customers\"; xml:base="http://customers"> + + "<customer id="1"/><customer id="2"/>" + + "</customers>"; +InputStream is = new ByteArrayInputStream(xmlString.getBytes()); +XMLSource xp = new XMLSource(is); +xp.setBuffering(true); URI baseURI = xp.getBaseURI(); -URI[] relativeURIs = xp.getLinks(<span class="code-quote">"/ps1:customer/@id"</span>, Collections.singletonMap(<span class="code-quote">"ps1"</span>, <span class="code-quote">"http:<span class="code-comment">//customers"</span>)); -</span> +URI[] relativeURIs = xp.getLinks("/ps1:customer/@id", Collections.singletonMap("ps1", "http://customers";)); + WebClient client = WebClient.create(baseURI); -<span class="code-keyword">for</span> (URI uri: relativeURIs) { +for (URI uri: relativeURIs) { client.path(uri); - <span class="code-comment">// access the home page -</span> - <span class="code-comment">// and get back to the base URI -</span> client.back(<span class="code-keyword">true</span>); + // access the home page + + // and get back to the base URI + client.back(true); } -</pre> +]]></script> </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"> @@ -277,26 +285,26 @@ XMLSource is used to get all the relativ <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" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -@Path(<span class="code-quote">"/root"</span>) -<span class="code-keyword">public</span> class Root { +<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ +@Path("/root") +public class Root { @POST - <span class="code-keyword">public</span> void post(XMLSource source) { - <span class="code-object">String</span> value = source.getProperty(<span class="code-quote">"/books/book/@name"</span>); + public void post(XMLSource source) { + String value = source.getProperty("/books/book/@name"); } } -</pre> +]]></script> </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" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -XPathProvider provider = <span class="code-keyword">new</span> XPathProvider(); -provider.setGlobalExpression(<span class="code-quote">"/books/book[position() = 1]"</span>); -WebClient wc = WebClient.create(<span class="code-quote">"http:<span class="code-comment">//aggregated/data"</span>, Collections.singletonList(provider)); -</span>Book b = wc.get(Book.class); -</pre> +<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ +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); +]]></script> </div></div> <h1><a shape="rect" name="JAX-RSAdvancedXML-XSLTsupport"></a>XSLT support</h1> @@ -313,17 +321,17 @@ WebClient wc = WebClient.create(<span cl <p>For example, given this resource method definition:</p> <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -@Path(<span class="code-quote">"/root"</span>) -<span class="code-keyword">public</span> class Root { +<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ +@Path("/root") +public class Root { @GET - @Path(<span class="code-quote">"{id}"</span>) - @Produces({<span class="code-quote">"application/xml"</span>, <span class="code-quote">"application/json"</span>, <span class="code-quote">"text/html"</span>} ) - <span class="code-keyword">public</span> Book get(@PathParam(<span class="code-quote">"id"</span>) <span class="code-object">String</span> id, @QueryParam(<span class="code-quote">"name"</span>) <span class="code-object">String</span> name) { - <span class="code-keyword">return</span> getBook(id, name); + @Path("{id}") + @Produces({"application/xml", "application/json", "text/html"} ) + public Book get(@PathParam("id") String id, @QueryParam("name") String name) { + return getBook(id, name); } } -</pre> +]]></script> </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> @@ -331,20 +339,20 @@ WebClient wc = WebClient.create(<span cl <p>Here are some examples of how XSLTJaxbTemplate can be configured:</p> <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-xml"> - <span class="code-tag"><map id=<span class="code-quote">"outTemplates"</span>></span> - <span class="code-tag"><entry key=<span class="code-quote">"application/xml"</span> value=<span class="code-quote">"classpath:/WEB-INF/templates/book-xml.xsl"</span>/></span> - <span class="code-tag"><entry key=<span class="code-quote">"text/html"</span> value=<span class="code-quote">"classpath:/WEB-INF/templates/book-html.xsl"</span>/></span> - <span class="code-tag"><entry key=<span class="code-quote">"application/json"</span> value=<span class="code-quote">"classpath:/WEB-INF/templates/book-json.xsl"</span>/></span> - <span class="code-tag"></map></span> +<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[ + <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"/> + </map> - <span class="code-tag"><bean id=<span class="code-quote">"uriResolver"</span> class=<span class="code-quote">"org.apache.cxf.systest.jaxrs.URIResolverImpl"</span>/></span> + <bean id="uriResolver" class="org.apache.cxf.systest.jaxrs.URIResolverImpl"/> - <span class="code-tag"><bean id=<span class="code-quote">"xsltProvider"</span> class=<span class="code-quote">"org.apache.cxf.jaxrs.provider.XSLTJaxbProvider"</span>></span> - <span class="code-tag"><property name=<span class="code-quote">"outMediaTemplates"</span> ref=<span class="code-quote">"outTemplates"</span>/></span> - <span class="code-tag"><property name=<span class="code-quote">"resolver"</span> ref=<span class="code-quote">"uriResolver"</span>/></span> - <span class="code-tag"></bean></span> -</pre> + <bean id="xsltProvider" class="org.apache.cxf.jaxrs.provider.XSLTJaxbProvider"> + <property name="outMediaTemplates" ref="outTemplates"/> + <property name="resolver" ref="uriResolver"/> + </bean> +]]></script> </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> @@ -354,12 +362,12 @@ WebClient wc = WebClient.create(<span cl <p>Here is a simpler configuration example:</p> <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-xml"> - <span class="code-tag"><bean id=<span class="code-quote">"xsltProvider"</span> class=<span class="code-quote">"org.apache.cxf.jaxrs.provider.XSLTJaxbProvider"</span>></span> - <span class="code-tag"><property name=<span class="code-quote">"outTemplate"</span> value=<span class="code-quote">"classpath:/WEB-INF/templates/book-xml.xsl"</span>/></span> - <span class="code-tag"><property name=<span class="code-quote">"inTemplate"</span> class=<span class="code-quote">"classpath:/WEB-INF/templates/fromNewBookToOldBook.xsl"</span>/></span> - <span class="code-tag"></bean></span> -</pre> +<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[ + <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> +]]></script> </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> @@ -371,31 +379,31 @@ WebClient wc = WebClient.create(<span cl <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" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -WebClient client = WebClient.create(<span class="code-quote">"http:<span class="code-comment">//books"</span>); -</span>client.path(<span class="code-quote">"/store/1"</span>).get(); -</pre> +<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ +WebClient client = WebClient.create("http://books";); +client.path("/store/1").get(); +]]></script> </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" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -WebClient client = WebClient.create(<span class="code-quote">"http:<span class="code-comment">//books"</span>); -</span>client.path(<span class="code-quote">"/store/{id}"</span>, 1).get(); -</pre> +<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ +WebClient client = WebClient.create("http://books";); +client.path("/store/{id}", 1).get(); +]]></script> </div></div> <h1><a shape="rect" name="JAX-RSAdvancedXML-XMLProcessingInstructions"></a>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" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-xml"> -<span class="code-tag"><?xml-stylesheet type=<span class="code-quote">"text/xsl"</span> href=<span class="code-quote">"http://localhost/myapp/stylesheets/toHTML.xsl";</span>?></span> -<span class="code-tag"><products xmlns=<span class="code-quote">"http://products";</span>></span> - <span class="code-tag"><product id=<span class="code-quote">"1"</span>/></span> -<span class="code-tag"></products></span> -</pre> +<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[ +<?xml-stylesheet type="text/xsl" href="http://localhost/myapp/stylesheets/toHTML.xsl"?> +<products xmlns="http://products"> + <product id="1"/> +</products> +]]></script> </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"> @@ -404,19 +412,19 @@ This option is alternative to using XSLT <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" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-xml"> -<span class="code-tag"><?xml-stylesheet type=<span class="code-quote">"text/css"</span> href=<span class="code-quote">"http://localhost/myapp/stylesheets/HTMLDecorator.css";</span>?></span> +<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[ +<?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 --> -<span class="code-tag"><html></span> - <span class="code-tag"><title></span>The products<span class="code-tag"></title></span> - <span class="code-tag"><table></span> - <span class="code-tag"><span class="code-comment"><!-- description of products --></span></span> - <span class="code-tag"></table></span> -<span class="code-tag"></html></span> -</pre> +<html> + <title>The products</title> + <table> + <!-- description of products --> + </table> +</html> +]]></script> </div></div> <p>When working with JAXB, the way to add such xml processing instructions is to set a <br clear="none"> @@ -424,16 +432,16 @@ This option is alternative to using XSLT <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" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-xml"> -<span class="code-tag"><beans <span class="code-keyword">xmlns:util</span>=<span class="code-quote">"http://www.springframework.org/schema/util";</span>></span> -<span class="code-tag"><bean id=<span class="code-quote">"jaxbProvider"</span> class=<span class="code-quote">"org.apache.cxf.jaxrs.provider.JAXBElementProvider"</span>></span> -<span class="code-tag"><map></span> -<entry key=<span class="code-quote">"com.sun.xml.bind.xmlHeaders"</span> - value=<span class="code-quote">"<span class="code-tag"><?xml-stylesheet type='text/xsl' href='/stylesheets/toHTML.xsl'?></span>"</span>/> -<span class="code-tag"></map></span> -<span class="code-tag"></bean></span> -<span class="code-tag"></beans></span> -</pre> +<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[ +<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" + value="<?xml-stylesheet type='text/xsl' href='/stylesheets/toHTML.xsl'?>"/> +</map> +</bean> +</beans> +]]></script> </div></div> <p>The problem here is how to correctly point to an absolute URI identifying the toHTML.xsl resource.<br clear="none"> @@ -442,15 +450,15 @@ Otherwise the best option is to extend J <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" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -@Path(<span class="code-quote">"products"</span>) -<span class="code-keyword">public</span> class Resource { +<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ +@Path("products") +public class Resource { @GET - @Produces(<span class="code-quote">"application/xml"</span>) - @XMLInstruction(<span class="code-quote">"<?xml-stylesheet type='text/xsl' href='/stylesheets/toHTML.xsl'?>"</span>) - <span class="code-keyword">public</span> Products getProducts() {} + @Produces("application/xml") + @XMLInstruction("<?xml-stylesheet type='text/xsl' href='/stylesheets/toHTML.xsl'?>") + public Products getProducts() {} } -</pre> +]]></script> </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> @@ -458,12 +466,12 @@ Otherwise the best option is to extend J <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" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-xml"> -<span class="code-tag"><bean id=<span class="code-quote">"jaxbProvider"</span> class=<span class="code-quote">"org.apache.cxf.jaxrs.provider.JAXBElementProvider"</span>></span> -<span class="code-tag"><property name=<span class="code-quote">"xmlResourceOffset"</span> value=<span class="code-quote">"stylesheets"</span>/></span> -<span class="code-tag"></bean></span> -<span class="code-tag"></beans></span> -</pre> +<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[ +<bean id="jaxbProvider" class="org.apache.cxf.jaxrs.provider.JAXBElementProvider"> +<property name="xmlResourceOffset" value="stylesheets"/> +</bean> +</beans> +]]></script> </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> @@ -472,26 +480,26 @@ Use an 'xmlResourceOffset' property of J <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" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-xml"> -<products xmlns=<span class="code-quote">"http://products";</span> - <span class="code-keyword">xmlns:xsi</span>=<span class="code-quote">""http://www.w3.org/2000/10/XMLSchema-instance";</span>" - xsi:schemaLocation=<span class="code-quote">"http://localhost/myapp/schemas/product.xsd";</span>> - <span class="code-tag"><product id=<span class="code-quote">"1"</span>/></span> -<span class="code-tag"></products></span> -</pre> +<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[ +<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> +]]></script> </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" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -@Path(<span class="code-quote">"products"</span>) -<span class="code-keyword">public</span> class Resource { +<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ +@Path("products") +public class Resource { @GET - @Produces(<span class="code-quote">"application/xml"</span>) - @XSISchemaLocation(<span class="code-quote">"schemas/products.xsd"</span>) - <span class="code-keyword">public</span> Products getProducts() {} + @Produces("application/xml") + @XSISchemaLocation("schemas/products.xsd") + public Products getProducts() {} } -</pre> +]]></script> </div></div> <p>Please see the previous section on how to affect the absolute URI to a given schema with the help of JAXBElementProvider.<br clear="none">
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 Mon Jun 24 17:10:51 2013 @@ -25,6 +25,18 @@ <meta http-equiv="Content-type" content="text/html;charset=UTF-8"> <meta name="keywords" content="business integration, EAI, SOA, Service Oriented Architecture, web services, SOAP, JBI, JMS, WSDL, XML, EDI, Electronic Data Interchange, standards support, integration standards, application integration, middleware, software, solutions, services, CXF, open source"> <meta name="description" content="Apache CXF, Services Framework - JAX-RS and JAX-WS"> + + <link href='http://cxf.apache.org/resources/highlighter/styles/shCore.css' rel='stylesheet' type='text/css' /> + <link href='http://cxf.apache.org/resources/highlighter/styles/shThemeCXF.css' rel='stylesheet' type='text/css' /> + <script src='http://cxf.apache.org/resources/highlighter/scripts/shCore.js' type='text/javascript'></script> + <script src='http://cxf.apache.org/resources/highlighter/scripts/shBrushJava.js' type='text/javascript'></script> + <script src='http://cxf.apache.org/resources/highlighter/scripts/shBrushXml.js' type='text/javascript'></script> + + <script type="text/javascript"> + SyntaxHighlighter.defaults['toolbar'] = false; + SyntaxHighlighter.all(); + </script> + <title> Apache CXF -- JAX-RS and JAX-WS </title> @@ -42,19 +54,15 @@ Apache CXF -- JAX-RS and JAX-WS <td id="cell-1-0"> </td> <td id="cell-1-1"> </td> <td id="cell-1-2"> - <div style="padding: 5px;"> - <div id="banner"> - <!-- Banner --> -<div id="banner-content"> + <!-- Banner --> +<div class="banner" id="banner"><p> <table border="0" cellpadding="0" cellspacing="0" width="100%"><tr><td align="left" colspan="1" nowrap> <a shape="rect" href="http://cxf.apache.org/"; title="Apache CXF"><span style="font-weight: bold; font-size: 170%; color: white">Apache CXF</span></a> </td><td align="right" colspan="1" nowrap> <a shape="rect" href="http://www.apache.org/"; title="The Apache Sofware Foundation"><img border="0" alt="ASF Logo" src="http://cxf.apache.org/images/asf-logo.png";></a> </td></tr></table> -</div> - <!-- Banner --> - </div> - </div> +</p></div> + <!-- Banner --> <div id="top-menu"> <table border="0" cellpadding="1" cellspacing="0" width="100%"> <tr> @@ -94,7 +102,7 @@ Apache CXF -- JAX-RS and JAX-WS <hr> -<ul class="alternate" type="square"><li>Search +<ul class="alternate" type="square"><li>Search<br clear="none"> <form enctype="application/x-www-form-urlencoded" method="get" id="cse-search-box" action="http://www.google.com/cse";> <div> @@ -132,12 +140,12 @@ Apache CXF -- JAX-RS and JAX-WS <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" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-xml"> -<span class="code-tag"><?xml version=<span class="code-quote">"1.0"</span> encoding=<span class="code-quote">"UTF-8"</span>?></span> -<beans xmlns=<span class="code-quote">"http://www.springframework.org/schema/beans";</span> - <span class="code-keyword">xmlns:xsi</span>=<span class="code-quote">"http://www.w3.org/2001/XMLSchema-instance";</span> - <span class="code-keyword">xmlns:jaxrs</span>=<span class="code-quote">"http://cxf.apache.org/jaxrs";</span> - <span class="code-keyword">xmlns:jaxws</span>=<span class="code-quote">"http://cxf.apache.org/jaxws";</span> +<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[ +<?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"; + xmlns:jaxws="http://cxf.apache.org/jaxws"; xsi:schemaLocation=" http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd @@ -146,24 +154,24 @@ http://cxf.apache.org/schemas/jaxrs.xsd http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd"> - <span class="code-tag"><import resource=<span class="code-quote">"classpath:META-INF/cxf/cxf.xml"</span> /></span> - <span class="code-tag"><import resource=<span class="code-quote">"classpath:META-INF/cxf/cxf-extension-jaxrs-binding.xml"</span> /></span> - <span class="code-tag"><import resource=<span class="code-quote">"classpath:META-INF/cxf/cxf-servlet.xml"</span> /></span> - - <span class="code-tag"><span class="code-comment"><!-- JAX-RS --></span></span> - <span class="code-tag"><jaxrs:server id=<span class="code-quote">"customerService"</span> address=<span class="code-quote">"/"</span>></span> - <span class="code-tag"><jaxrs:serviceBeans></span> - <span class="code-tag"><ref bean=<span class="code-quote">"customerService"</span> /></span> - <span class="code-tag"></jaxrs:serviceBeans></span> - <span class="code-tag"></jaxrs:server></span> - - <span class="code-tag"><span class="code-comment"><!-- JAX-WS --></span></span> - <jaxws:endpoint implementor=<span class="code-quote">"#customerService"</span> - address=<span class="code-quote">"/CustomerWorld"</span> wsdlLocation=<span class="code-quote">"..."</span>/> + <import resource="classpath:META-INF/cxf/cxf.xml" /> + <import resource="classpath:META-INF/cxf/cxf-extension-jaxrs-binding.xml" /> + <import resource="classpath:META-INF/cxf/cxf-servlet.xml" /> + + <!-- JAX-RS --> + <jaxrs:server id="customerService" address="/"> + <jaxrs:serviceBeans> + <ref bean="customerService" /> + </jaxrs:serviceBeans> + </jaxrs:server> + + <!-- JAX-WS --> + <jaxws:endpoint implementor="#customerService" + address="/CustomerWorld" wsdlLocation="..."/> - <span class="code-tag"><bean id=<span class="code-quote">"customerService"</span> class=<span class="code-quote">"demo.jaxrs.server.CustomerService"</span> /></span> -<span class="code-tag"></beans></span> -</pre> + <bean id="customerService" class="demo.jaxrs.server.CustomerService" /> +</beans> +]]></script> </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> @@ -171,23 +179,23 @@ http://cxf.apache.org/schemas/jaxws.xsd"; <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" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-keyword">public</span> class CustomerService { - <span class="code-keyword">public</span> void doIt(<span class="code-object">String</span> a, <span class="code-object">String</span> b) {...}; +<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ +public class CustomerService { + public void doIt(String a, String b) {...}; } -</pre> +]]></script> </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" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -@Path(<span class="code-quote">"/customers/{a}"</span>) -<span class="code-keyword">public</span> class CustomerService { - <span class="code-keyword">public</span> void doIt(@PathParam(<span class="code-quote">"a"</span>) <span class="code-object">String</span> a, <span class="code-object">String</span> b) {...}; +<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ +@Path("/customers/{a}") +public class CustomerService { + public void doIt(@PathParam("a") String a, String b) {...}; } -</pre> +]]></script> </div></div> <p>Note that CXF Continuations API is supported for both JAXWS and JAXRS services.</p> @@ -197,31 +205,31 @@ a 'String a' parameter can be mapped to <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" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -@Path(<span class="code-quote">"/customers"</span>) +<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ +@Path("/customers") @WebService -<span class="code-keyword">public</span> class CustomerService { +public class CustomerService { @Resource WebServiceContext jaxwsContext; @Resource MessageContext jaxrsContext; @WebMethod @POST - <span class="code-keyword">public</span> void doIt(<span class="code-object">String</span> b) { + public void doIt(String b) { isUserInRole(); }; - <span class="code-keyword">private</span> void isUserInRole() <span class="code-keyword">throws</span> WebApplicationException { - <span class="code-keyword">if</span> (jaxwsContext.getSecurityContext() != <span class="code-keyword">null</span>) { - <span class="code-comment">// soap invocation -</span> jaxwsContext.getSecurityContext().isUserInRole(theRole); - } <span class="code-keyword">else</span> { - <span class="code-comment">// http-only jaxrs one -</span> jaxrsContext.getSecurityContext().isUserInRole(theRole); + private void isUserInRole() throws WebApplicationException { + if (jaxwsContext.getSecurityContext() != null) { + // soap invocation + jaxwsContext.getSecurityContext().isUserInRole(theRole); + } else { + // http-only jaxrs one + jaxrsContext.getSecurityContext().isUserInRole(theRole); } } } -</pre> +]]></script> </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> @@ -231,14 +239,14 @@ a 'String a' parameter can be mapped to <p>Using individual contexts like JAXRS SecurityContext might be less attractive :</p> <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> +<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ @WebService -<span class="code-keyword">public</span> class CustomerService { +public class CustomerService { @Resource WebServiceContext jaxwsContext; - <span class="code-comment">// @Resource can be applied too -</span> @Context SecurityContext jaxrsSecurityContext; + // @Resource can be applied too + @Context SecurityContext jaxrsSecurityContext; } -</pre> +]]></script> </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> @@ -246,29 +254,29 @@ a 'String a' parameter can be mapped to <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" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -@Path(<span class="code-quote">"/customers"</span>) +<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ +@Path("/customers") @WebService -<span class="code-keyword">public</span> class CustomerService +public class CustomerService @Resource WebServiceContext jaxwsContext; @Resource MessageContext jaxrsContext; @WebMethod - <span class="code-keyword">public</span> void doItSoap(<span class="code-object">String</span> b) { + public void doItSoap(String b) { isUserInRole(jaxwsContext.getSecurityContext().getPrincipal()); }; @POST - <span class="code-keyword">public</span> void doItSoap(<span class="code-object">String</span> b) { + public void doItSoap(String b) { isUserInRole(jaxwsContext.getSecurityContext().getPrincipal()); } - <span class="code-keyword">private</span> void isUserInRole(Principal p) <span class="code-keyword">throws</span> WebApplicationException { + private void isUserInRole(Principal p) throws WebApplicationException { ... } } -</pre> +]]></script> </div></div> <p>Another option is to avoid the use of contexts in the service code and deal with them in CXF interceptors or JAXRS filters. Sometimes it's possible to avoid the use of contexts altogether. For example, Spring Security can be used to secure a given service at an individual method level. </p>
![http://cxf.apache.org/images/asf-logo.png"](http://cxf.apache.org/images/asf-logo.png"){kind=link}