You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cxf.apache.org by bu...@apache.org on 2012/06/26 18:47:52 UTC
svn commit: r823315 - in /websites/production/cxf/content:
cache/docs.pageCache docs/jax-rs-advanced-features.html
docs/jaxrs-services-description.html
Author: buildbot
Date: Tue Jun 26 16:47:51 2012
New Revision: 823315
Log:
Production update by buildbot for cxf
Modified:
websites/production/cxf/content/cache/docs.pageCache
websites/production/cxf/content/docs/jax-rs-advanced-features.html
websites/production/cxf/content/docs/jaxrs-services-description.html
Modified: websites/production/cxf/content/cache/docs.pageCache
==============================================================================
Binary files - no diff available.
Modified: websites/production/cxf/content/docs/jax-rs-advanced-features.html
==============================================================================
--- websites/production/cxf/content/docs/jax-rs-advanced-features.html (original)
+++ websites/production/cxf/content/docs/jax-rs-advanced-features.html Tue Jun 26 16:47:51 2012
@@ -124,7 +124,7 @@ Apache CXF -- JAX-RS Advanced Features
<div id="ConfluenceContent"><p><span style="font-size:2em;font-weight:bold">JAX-RS : Advanced Features</span></p>
<div>
-<ul><li><a shape="rect" href="#JAX-RSAdvancedFeatures-JMSSupport">JMS Support</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-FIQLsearchqueries">FIQL search queries</a></li><ul><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Introduction">Introduction</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-DependenciesandConfiguration">Dependencies and Configuration</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-ConsumingFIQLqueries">Consuming FIQL queries</a></li><ul><li><a shape="rect" href="#JAX-RSAdvancedFeatures-SearchBean">SearchBean</a></li></ul><li><a shape="rect" href="#JAX-RSAdvancedFeatures-BuildingFIQLqueries">Building FIQL queries</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Usingdatesinqueries">Using dates in queries</a></li></ul><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Onewayinvocations">Oneway invocations</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-SupportforContinuations">Support for Continuations<
/a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Serversidecaching">Server-side caching</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-RESTfulserviceswithoutannotations">RESTful services without annotations</a></li><ul><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Configuration">Configuration</a></li></ul></ul></div>
+<ul><li><a shape="rect" href="#JAX-RSAdvancedFeatures-JMSSupport">JMS Support</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-FIQLsearchqueries">FIQL search queries</a></li><ul><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Introduction">Introduction</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-DependenciesandConfiguration">Dependencies and Configuration</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-ConsumingFIQLqueries">Consuming FIQL queries</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-ConvertingFIQLqueries">Converting FIQL queries</a></li><ul><li><a shape="rect" href="#JAX-RSAdvancedFeatures-SQL">SQL</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-JPA2.0">JPA 2.0</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Customvisitors">Custom visitors</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-SearchBean">SearchBean</a></li></ul><li><a shape="rect" href="#JAX-RSAdvancedFeatures-BuildingFIQLqueries
">Building FIQL queries</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Usingdatesinqueries">Using dates in queries</a></li></ul><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Onewayinvocations">Oneway invocations</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-SupportforContinuations">Support for Continuations</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Serversidecaching">Server-side caching</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-RESTfulserviceswithoutannotations">RESTful services without annotations</a></li><ul><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Configuration">Configuration</a></li></ul></ul></div>
<h1><a shape="rect" name="JAX-RSAdvancedFeatures-JMSSupport"></a>JMS Support</h1>
@@ -195,7 +195,7 @@ An expression such as "name==CXF*" can b
<h2><a shape="rect" name="JAX-RSAdvancedFeatures-ConsumingFIQLqueries"></a>Consuming FIQL queries</h2>
-<p>To work with FIQL queries, a <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/search/SearchContext.java">SearchContext</a> needs be injected into an application code and used to retrieve a <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/search/SearchCondition.java">SearchCondition</a> representing the current FIQL query. This SearchCondition can be used in a number of ways for finding the matching data.</p>
+<p>To work with FIQL queries, a <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/extensions/search/src/main/java/org/apache/cxf/jaxrs/ext/search/SearchContext.java">SearchContext</a> needs be injected into an application code and used to retrieve a <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/extensions/search/src/main/java/org/apache/cxf/jaxrs/ext/search/SearchCondition.java">SearchCondition</a> representing the current FIQL query. This SearchCondition can be used in a number of ways for finding the matching data.</p>
<p>For example :</p>
@@ -225,25 +225,14 @@ An expression such as "name==CXF*" can b
<p>Note that a searchContext.getCondition(Book.class) call may return an arbitrary complex SearchCondition, it can be a simple primitive<br clear="none">
expression or a more complex one. The Book class needs to have a matching property per every name found in the FIQL expression, for example, given a 'name==b;id==123' expression, the Book class would need to have 'name' and 'id' properties available.</p>
-<p>SearchCondition can also be used to get to all the search requirements (originally expressed in FIQL) and do some manual<br clear="none">
-comparison against the local data. For example, SearchCondition provides a utility toSQL(String tableName, String... columnNames) method which internally introspects all the search expressions constituting a current query and converts them into an SQL expression:</p>
+<h2><a shape="rect" name="JAX-RSAdvancedFeatures-ConvertingFIQLqueries"></a>Converting FIQL queries</h2>
-<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
-<pre class="code-java">
-<span class="code-comment">// find all conditions with names starting from 'ami'
-</span><span class="code-comment">// and levels greater than 10 :
-</span><span class="code-comment">// ?_s=<span class="code-quote">"name==ami*;level=gt=10"</span>
-</span>SearchCondition<Book> sc = searchContext.getCondition(Book.class);
-assertEquals("SELECT * FROM table
- WHERE
- name LIKE 'ami%'
- AND
- level > '10'",
- sq.toSQL(<span class="code-quote">"table"</span>));
-</pre>
-</div></div>
+<p>SearchCondition can also be used to convert the search requirements (originally expressed in FIQL) into other query languages. <br clear="none">
+A custom <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/extensions/search/src/main/java/org/apache/cxf/jaxrs/ext/search/SearchConditionVisitor.java">SearchConditionVisitor</a> implementation can be used to convert SearchCondition objects into custom expressions or typed objects. CXF ships visitors for converting expressions to SQL and JPA 2.0 CriteriaQuery or TypedQuery objects.</p>
-<p>The SearchCondition.toSQL() method has become deprecated in CXF 2.3.3 and 2.4.0. Using an org.apache.cxf.jaxrs.ext.search.sql.SQLPrinterVisitor is recommended as it will allow for building more advanced SQL expressions. For example: </p>
+<h3><a shape="rect" name="JAX-RSAdvancedFeatures-SQL"></a>SQL</h3>
+
+<p>org.apache.cxf.jaxrs.ext.search.sql.SQLPrinterVisitor can be used for creating SQL expressions. For example: </p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
@@ -267,7 +256,7 @@ assertEquals("SELECT * FROM table
<span class="code-comment">// ?_s=<span class="code-quote">"level=gt=10"</span>
</span>SearchCondition<Book> sc = searchContext.getCondition(Book.class);
-Map\<, <span class="code-object">String</span>\> fieldMap = <span class="code-keyword">new</span> HashMap\<<span class="code-object">String</span>, <span class="code-object">String</span>\>();
+Map<<span class="code-object">String</span>, <span class="code-object">String</span>> fieldMap = <span class="code-keyword">new</span> HashMap<<span class="code-object">String</span>, <span class="code-object">String</span>>();
fieldMap.put(<span class="code-quote">"level"</span>, <span class="code-quote">"LEVEL_FIELD"</span>);
SQLPrinterVisitor<Book> visitor = <span class="code-keyword">new</span> SQLPrinterVisitor<Book>(fieldMap, <span class="code-quote">"table"</span>, <span class="code-quote">"LEVEL_COLUMN"</span>);
@@ -280,7 +269,33 @@ assertEquals("SELECT LEVEL_COLUMN FROM t
<p>The fields map can help hide the names of the actual table columns/record fields from the Web frontend. Example, the users will know that the 'level' property is available while internally it will be converted to a LEVEL_COLUMN name.</p>
-<p>Custom visitors producing more optimized SQL or non-SQL expressions can also be introduced.</p>
+<h3><a shape="rect" name="JAX-RSAdvancedFeatures-JPA2.0"></a>JPA 2.0</h3>
+
+<p>CXF 2.5.5 and CXF 2.6.2 introduces org.apache.cxf.jaxrs.ext.search.jpa.JPATypedQueryVisitor which can be used to produce javax.persistence.criteria.CriteriaQuery or javax.persistence.TypedQuery objects.</p>
+
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+<span class="code-keyword">import</span> javax.persistence.EntityManager;
+<span class="code-keyword">import</span> javax.persistence.TypedQuery;
+
+<span class="code-comment">// init EntityManager as required
+</span><span class="code-keyword">private</span> EntityManager entityManager;
+
+<span class="code-comment">// ?_s=<span class="code-quote">"name==ami*;level=gt=10"</span>
+</span>SearchCondition<Book> sc = searchContext.getCondition(Book.class);
+JPATypedQuery<Book> visitor = <span class="code-keyword">new</span> JPATypedQueryVisitor<Book>(entityManager, Book.class);
+sc.visit(visitor);
+TypedQuery<Book> typedQuery = visitor.getQuery();
+List<Book> books = typedQuery.getResultList();
+<span class="code-comment">// or
+</span><span class="code-comment">// CriteriaQuery<Book> criteriaQuery = visitor.getCriteriaQuery();</span>
+</pre>
+</div></div>
+
+<p>org.apache.cxf.jaxrs.ext.search.jpa.JPALanguageVisitor for converting FIQL expressions into JPQL expressions have also been introduced.</p>
+
+<h3><a shape="rect" name="JAX-RSAdvancedFeatures-Customvisitors"></a>Custom visitors</h3>
<p>Here is a possible code template to follow when a custom visitor needs to be written:</p>
Modified: websites/production/cxf/content/docs/jaxrs-services-description.html
==============================================================================
--- websites/production/cxf/content/docs/jaxrs-services-description.html (original)
+++ websites/production/cxf/content/docs/jaxrs-services-description.html Tue Jun 26 16:47:51 2012
@@ -124,7 +124,7 @@ Apache CXF -- JAXRS Services Description
<div id="ConfluenceContent"><p><span style="font-size:2em;font-weight:bold"> JAX-RS Services Description </span></p>
<div>
-<ul><li><a shape="rect" href="#JAXRSServicesDescription-WADLoverview">WADL overview</a></li><ul><li><a shape="rect" href="#JAXRSServicesDescription-Basicexample">Basic example</a></li><li><a shape="rect" href="#JAXRSServicesDescription-WADLwithreferences">WADL with references</a></li><li><a shape="rect" href="#JAXRSServicesDescription-SharingdeclarationsbetweenmultipleWADLs">Sharing declarations between multiple WADLs</a></li></ul><li><a shape="rect" href="#JAXRSServicesDescription-WADLfirstDevelopment">WADL-first Development</a></li><ul><li><a shape="rect" href="#JAXRSServicesDescription-wadl2javacommandlinetool">wadl2java command line tool</a></li><ul><li><a shape="rect" href="#JAXRSServicesDescription-JAXBcustomizations">JAXB customizations</a></li></ul><li><a shape="rect" href="#JAXRSServicesDescription-wadl2javaMavenplugin">wadl2java Maven plugin</a></li><li><a shape="rect" href="#JAXRSServicesDescription-Integration">Integration</a></li><li><a shape="rect" href="#JAXRS
ServicesDescription-ExternalWADLdocumentsandJAXRSendpoints.">External WADL documents and JAXRS endpoints.</a></li></ul><li><a shape="rect" href="#JAXRSServicesDescription-WADLAutoGeneration">WADL Auto Generation</a></li><ul><li><a shape="rect" href="#JAXRSServicesDescription-DocumentingresourceclassesandmethodsingeneratedWADL">Documenting resource classes and methods in generated WADL</a></li><li><a shape="rect" href="#JAXRSServicesDescription-CustomizingWADLGeneration">Customizing WADL Generation</a></li><ul><li><a shape="rect" href="#JAXRSServicesDescription-RepresentingexternalschemasandnonJAXBtypes">Representing external schemas and non JAXB types</a></li></ul></ul><li><a shape="rect" href="#JAXRSServicesDescription-ServicelistingsandWADLqueries">Service listings and WADL queries</a></li><li><a shape="rect" href="#JAXRSServicesDescription-WADLinJSONformat">WADL in JSON format</a></li><li><a shape="rect" href="#JAXRSServicesDescription-HidinglinkstoJAXRSendpointsfromthese
rvicespage">Hiding links to JAXRS endpoints from the services page</a></li></ul></div>
+<ul><li><a shape="rect" href="#JAXRSServicesDescription-WADLoverview">WADL overview</a></li><ul><li><a shape="rect" href="#JAXRSServicesDescription-Basicexample">Basic example</a></li><li><a shape="rect" href="#JAXRSServicesDescription-WADLwithreferences">WADL with references</a></li><li><a shape="rect" href="#JAXRSServicesDescription-SharingdeclarationsbetweenmultipleWADLs">Sharing declarations between multiple WADLs</a></li></ul><li><a shape="rect" href="#JAXRSServicesDescription-WADLfirstDevelopment">WADL-first Development</a></li><ul><li><a shape="rect" href="#JAXRSServicesDescription-wadl2javacommandlinetool">wadl2java command line tool</a></li><ul><li><a shape="rect" href="#JAXRSServicesDescription-JAXBcustomizations">JAXB customizations</a></li></ul><li><a shape="rect" href="#JAXRSServicesDescription-wadl2javaMavenplugin">wadl2java Maven plugin</a></li><li><a shape="rect" href="#JAXRSServicesDescription-Integration">Integration</a></li><li><a shape="rect" href="#JAXRS
ServicesDescription-ExternalWADLdocumentsandJAXRSendpoints.">External WADL documents and JAXRS endpoints.</a></li></ul><li><a shape="rect" href="#JAXRSServicesDescription-WADLAutoGeneration">WADL Auto Generation</a></li><ul><li><a shape="rect" href="#JAXRSServicesDescription-DocumentingresourceclassesandmethodsingeneratedWADL">Documenting resource classes and methods in generated WADL</a></li><li><a shape="rect" href="#JAXRSServicesDescription-CustomizingWADLGeneration">Customizing WADL Generation</a></li><ul><li><a shape="rect" href="#JAXRSServicesDescription-RepresentingexplicitJAXBcollections">Representing explicit JAXB collections</a></li><li><a shape="rect" href="#JAXRSServicesDescription-RepresentingexternalschemasandnonJAXBtypes">Representing external schemas and non JAXB types</a></li></ul></ul><li><a shape="rect" href="#JAXRSServicesDescription-ServicelistingsandWADLqueries">Service listings and WADL queries</a></li><li><a shape="rect" href="#JAXRSServicesDescriptio
n-WADLinJSONformat">WADL in JSON format</a></li><li><a shape="rect" href="#JAXRSServicesDescription-HidinglinkstoJAXRSendpointsfromtheservicespage">Hiding links to JAXRS endpoints from the services page</a></li></ul></div>
<p>CXF JAX-RS supports (Web Application Description Language|http://www.w3.org/Submission/wadl] (WADL). <br clear="none">
Users can use WADL documents to generate the initial code and have WADL auto-generated on demand. </p>
@@ -461,10 +461,10 @@ First option is to pass the collected op
<p>CXF JAX-RS supports the auto-generation of WADL for JAX-RS endpoints. <br clear="none">
Note that JAX-RS subresources are late-resolved by default, so using annotated interfaces for subresources and a staticSubresourceResolution=true property will let the whole resource tree/graph be described in a generated instance. Schemas will be generated for JAXB-annotated types. See below for the information on how to get auto-generated WADL instances reference existing schemas.</p>
-<h2><a shape="rect" name="JAXRSServicesDescription-DocumentingresourceclassesandmethodsingeneratedWADL"></a>Documenting resource classes and methods in generated WADL</h2>
-
<p><b>CXF 2.4.0</b>: org.apache.cxf.jaxrs.ext.Description and org.apache.cxf.jaxrs.ext.xml.XMLName have been moved to org.apache.cxf.jaxrs.model.wadl package given that their purpose is to improve the WADL generation. Also, org.apache.cxf.jaxrs.model.wadl.WadlElement has been renamed to 'ElementClass'. </p>
+<h2><a shape="rect" name="JAXRSServicesDescription-DocumentingresourceclassesandmethodsingeneratedWADL"></a>Documenting resource classes and methods in generated WADL</h2>
+
<p>WADL documents can include <a shape="rect" class="external-link" href="http://www.w3.org/Submission/wadl/#x3-80002.3" rel="nofollow">doc</a> fragments. </p>
<p>Users may want to use <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/model/wadl/Description.java">Description</a> annotations which can be attached to resource classes and methods.</p>
@@ -515,6 +515,24 @@ org.apache.cxf.jaxrs.model.wadl.WadlGene
<ul class="alternate" type="square"><li>applicationTitle: can be used to create an application title.</li><li>namespacePrefix: defaut is 'prefix', it can be set to other value such as 'ns'.</li><li>ignoreForwardSlash: can be used to enforce that resource path values do not start from '/'</li><li>addResourceAndMethodIds: WadlGenerator will add "id" attributes to wadl:resource and wadl:method elements</li></ul>
+<p>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/model/wadl/ElementClass.java">ElementClass</a> annotation can help with representing JAX-RS Response elements in the generated WADL. </p>
+
+<h3><a shape="rect" name="JAXRSServicesDescription-RepresentingexplicitJAXBcollections"></a>Representing explicit JAXB collections</h3>
+
+<p>Starting from CXF 2.5.5 and 2.6.2 it is possible to get explicit collections represented in generated WADL grammar sections and have WADL representations linking to these schema elements. Note it is only possible for JAXB collections, for example:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+
+@GET
+@Path(<span class="code-quote">"books"</span>)
+@org.apache.cxf.jaxrs.model.wadl.XMLName(<span class="code-quote">"{http:<span class="code-comment">//books}books"</span>)
+</span><span class="code-keyword">public</span> List<Book> getBooks() {...}
+</pre>
+</div></div>
+
+<p>Given the above example, WADLGenerator will attempt to add a 'books' element to the generated schema with the targetNamespace set to "http://books". This 'books' element will have a sequence of elements linking to a type representing the "Book" class.</p>
+
<h3><a shape="rect" name="JAXRSServicesDescription-RepresentingexternalschemasandnonJAXBtypes"></a>Representing external schemas and non JAXB types</h3>
<p>By default, the WADL grammar section will be properly generated if resource methods accept or return JAXB types. </p>
@@ -555,8 +573,6 @@ wg.setSchemaLocations(Collections.single
<p>If no JAXB is used then you can attach 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/model/wadl/XMLName.java">XMLName</a> annotation to method input or output types. Alternatively, you can register an instance 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/model/wadl/ElementQNameResolver.java">ElementQNameResolver</a> with the WadlGenerator which will be used for creating wadl:representation/@element values.</p>
-<p>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/model/wadl/ElementClass.java">ElementClass</a> annotation can help with representing JAX-RS Response elements in the generated WADL. </p>
-
<h1><a shape="rect" name="JAXRSServicesDescription-ServicelistingsandWADLqueries"></a>Service listings and WADL queries</h1>
<p>Links to WADL instances for RESTful endpoints are available from {base endpointaddress}/services, in addition to SOAP endpoints if any. </p>