cxf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r825563 - in /websites/production/cxf/content: cache/docs.pageCache docs/jax-rs-advanced-features.html
Date Thu, 12 Jul 2012 11:47:52 GMT
Author: buildbot
Date: Thu Jul 12 11:47:52 2012
New Revision: 825563

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

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 Thu Jul 12 11:47:52
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><ul><li><a
shape="rect" href="#JAX-RSAdvancedFeatures-Endpoints">Endpoints</a></li><li><a
shape="rect" href="#JAX-RSAdvancedFeatures-Client">Client</a></li></ul><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>
+<ul><li><a shape="rect" href="#JAX-RSAdvancedFeatures-JMSSupport">JMS Support</a></li><ul><li><a
shape="rect" href="#JAX-RSAdvancedFeatures-Endpoints">Endpoints</a></li><li><a
shape="rect" href="#JAX-RSAdvancedFeatures-Client">Client</a></li></ul><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-SearchExpressionsinURIPathsegments">Search Expressions
in URI Path segments</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Queriesinvolvingmultipleentities">Queries
involving multiple entities</a></li><ul><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Basicqueries">Basic
queries</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Complexqueries">Complex
queries</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><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Alternativequerylanguages">Alternative
query languages</a></li></ul><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Onewayinvocations">Oneway
invocations</a></li><li><a shape="rect" href="#JAX-RS
 AdvancedFeatures-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>
 
@@ -406,6 +406,173 @@ assertEquals("SELECT LEVEL_COLUMN FROM t
 </pre>
 </div></div>
 
+<h2><a shape="rect" name="JAX-RSAdvancedFeatures-SearchExpressionsinURIPathsegments"></a>Search
Expressions in URI Path segments</h2>
+
+<p>By default, a FIQL expression is expected to be available in either '_s' or '_search'
query.<br clear="none">
+For example, "find all the books with an 'id' property value less than 123":</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-xml">
+GET /books?_s=id=lt=123
+</pre>
+</div></div>
+
+<p>Starting from CXF 2.6.2, it is possible to work with FIQL expressions included in
URI path segments, for example, the same query can be expressed<br clear="none">
+in a number of ways:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-xml">
+
+GET /books/id=lt=123
+GET /books[id=lt=123]
+GET /books(id=lt=123)
+GET /books;id=lt=123
+
+//etc, etc
+
+</pre>
+</div></div>
+
+<p>Such expressions can be captured in the code using JAX-RS annotations:</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+@Path(<span class="code-quote">"search"</span>)
+<span class="code-keyword">public</span> class BooksResource {
+   @Context
+   <span class="code-keyword">private</span> SearchContext context;
+
+   <span class="code-comment">//GET /books[id=lt=123]
+</span>   @GET
+   @Path(<span class="code-quote">"books[{search}]"</span>) 
+   <span class="code-keyword">public</span> List&lt;Book&gt; findSelectedBooks(@PathParam(<span
class="code-quote">"search"</span>) <span class="code-object">String</span>
searchExpression) {
+       <span class="code-keyword">return</span> doFindSelectedBooks(searchExpression);
+   }
+
+   <span class="code-comment">//GET /books(id=lt=123)
+</span>   @GET
+   @Path(<span class="code-quote">"books({search})"</span>) 
+   <span class="code-keyword">public</span> List&lt;Book&gt; findSelectedBooks(@PathParam(<span
class="code-quote">"search"</span>) <span class="code-object">String</span>
searchExpression) {
+       <span class="code-keyword">return</span> doFindSelectedBooks(searchExpression);
+   }
+
+   <span class="code-comment">//GET /books/id=lt=123
+</span>   @GET
+   @Path(<span class="code-quote">"books/{search}"</span>) 
+   <span class="code-keyword">public</span> List&lt;Book&gt; findSelectedBooks(@PathParam(<span
class="code-quote">"search"</span>) <span class="code-object">String</span>
searchExpression) {
+       <span class="code-keyword">return</span> doFindSelectedBooks(searchExpression);
+   }
+
+   <span class="code-comment">//GET /books;id=lt=123
+</span>   @GET
+   @Path(<span class="code-quote">"books;{search}"</span>) 
+   <span class="code-keyword">public</span> List&lt;Book&gt; findSelectedBooks(@PathParam(<span
class="code-quote">"search"</span>) <span class="code-object">String</span>
searchExpression) {
+       <span class="code-keyword">return</span> doFindSelectedBooks(searchExpression);
+   }
+
+   <span class="code-keyword">public</span> List&lt;Book&gt; doFindSelectedBooks(<span
class="code-object">String</span> searchExpression) {
+       SearchCondition&lt;Book&gt; sc = context.getCondition(searchExpression, Book.class);
+   
+       <span class="code-comment">// JPA2 enity manager is initialized earlier
+</span>       JPATypedQuery&lt;Book&gt; visitor = <span class="code-keyword">new</span>
JPATypedQueryVisitor&lt;Book&gt;(entityManager, Book.class);
+       sc.visit(visitor);
+   
+       TypedQuery&lt;Book&gt; typedQuery = visitor.getQuery();
+       <span class="code-keyword">return</span> typedQuery.getResultList();
+   }
+
+}
+</pre>
+</div></div> 
+
+<p>Note that if you have an expression added to a URI path segment with a ";" character
acting as a separator, example, "/books;id=lt=123",<br clear="none">
+or if an expression itself includes ";", example, "/books[id=lt=123;id=gt=300]" ("find all
the books with id less than 123 or greater than 300") <br clear="none">
+then a boolean contextual property "ignore.matrix.parameters" has to be set to "true" for
the runtime to avoid splitting the path segment into the path value and matrix parameters.</p>
+
+<h2><a shape="rect" name="JAX-RSAdvancedFeatures-Queriesinvolvingmultipleentities"></a>Queries
involving multiple entities</h2>
+
+<h3><a shape="rect" name="JAX-RSAdvancedFeatures-Basicqueries"></a>Basic
queries</h3>
+
+<p>Consider the query like "find the first chapters of all the books with 'id' less
than 123".<br clear="none">
+One easy way to manage such queries is to make FIQL and JAX-RS work together. For example:
   </p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+@Path(<span class="code-quote">"search"</span>)
+<span class="code-keyword">public</span> class BooksResource {
+   @Context
+   <span class="code-keyword">private</span> SearchContext context;
+
+   <span class="code-comment">//GET /books[id=lt=123]/chapter/1
+</span>   @GET
+   @Path(<span class="code-quote">"books[{search}]/chapter/{id}"</span>) 
+   <span class="code-keyword">public</span> List&lt;Book&gt; findSelectedBooks(@PathParam(<span
class="code-quote">"search"</span>) <span class="code-object">String</span>
searchExpression,
+                                       @PathParam(<span class="code-quote">"id"</span>)
<span class="code-object">int</span> chapterIndex) {
+       <span class="code-keyword">return</span> doFindSelectedChapters(searchExpression,
chapterIndex);
+   }
+
+   <span class="code-keyword">public</span> List&lt;Chapter&gt; doFindSelectedChapters(<span
class="code-object">String</span> searchExpression, <span class="code-object">int</span>
chapterIndex) {
+       SearchCondition&lt;Book&gt; sc = context.getCondition(searchExpression, Book.class);
+   
+       <span class="code-comment">// JPA2 enity manager is initialized earlier
+</span>       JPATypedQuery&lt;Book&gt; visitor = <span class="code-keyword">new</span>
JPATypedQueryVisitor&lt;Book&gt;(entityManager, Book.class);
+       sc.visit(visitor);
+   
+       TypedQuery&lt;Book&gt; typedQuery = visitor.getQuery();
+       List&lt;Book&gt; books = typedQuery.getResultList();
+
+       List&lt;Chapter&gt; chapters = <span class="code-keyword">new</span>
ArrayList&lt;Chapter&gt;(books.size);
+       <span class="code-keyword">for</span> (Book book : books) {
+           chapters.add(book.getChapter(chapterIndex)); 
+       }   
+       <span class="code-keyword">return</span> chapters;
+   }
+
+}
+</pre>
+</div></div> 
+
+<h3><a shape="rect" name="JAX-RSAdvancedFeatures-Complexqueries"></a>Complex
queries</h3>
+
+<p>At the moment one needs to follow the example (not necessarily using JPA2) presented
in the previous section to manage the complex queries <br clear="none">
+such as "find all the chapters with id less than 5 for all the books with id greater than
300", for example: </p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+@Path(<span class="code-quote">"search"</span>)
+<span class="code-keyword">public</span> class BooksResource {
+   @Context
+   <span class="code-keyword">private</span> SearchContext context;
+
+   <span class="code-comment">//GET /books(id=gt=300)/chapters(id=lt=5)
+</span>   @GET
+   @Path(<span class="code-quote">"books({search1})/chapter/{search2}"</span>)

+   <span class="code-keyword">public</span> List&lt;Book&gt; findSelectedBooks(@PathParam(<span
class="code-quote">"search1"</span>) <span class="code-object">String</span>
bookExpression,
+                                       @PathParam(<span class="code-quote">"search2"</span>)
<span class="code-object">String</span> chapterExpression) {
+       <span class="code-keyword">return</span> doFindSelectedBooks(bookExpression,
chapterExpression);
+   }
+
+   <span class="code-keyword">public</span> List&lt;Chapter&gt; doFindSelectedChapters(<span
class="code-object">String</span> bookExpression, <span class="code-object">String</span>
chapterExpression) {
+       <span class="code-comment">// find the books first
+</span>       
+       SearchCondition&lt;Book&gt; bookCondition = context.getCondition(searchExpression,
Book.class);
+   
+       JPATypedQuery&lt;Book&gt; visitor = <span class="code-keyword">new</span>
JPATypedQueryVisitor&lt;Book&gt;(entityManager, Book.class);
+       bookCondition.visit(visitor);
+       TypedQuery&lt;Book&gt; typedQuery = visitor.getQuery();
+       List&lt;Book&gt; books = typedQuery.getResultList();
+
+       <span class="code-comment">// now get the chapters
+</span>       SearchCondition&lt;Chapter&gt; chapterCondition = context.getCondition(chapterExpression,
Chapter.class);
+       List&lt;Chapter&gt; chapters = <span class="code-keyword">new</span>
ArrayList&lt;Chapter&gt;();
+       <span class="code-keyword">for</span> (Book book : books) {
+           chapters.addAll(chapterCondition.findAll(book.getChapters()); 
+       }   
+       <span class="code-keyword">return</span> chapters;
+   }
+
+}
+</pre>
+</div></div> 
+
+<p>The above code can be quite functional but not necessarilry optimal. Much depends
on the actual relationship between the endities, whether the initial (JPA2) query eagerly
loaded all the chapters for every given book, etc. Perhaps a JOIN-like query which will immediately
return only the matching chapters will be more optimal. Support for capturing the expressions
involving multiple entities and possibly converting them to JOIN statements will be investigated
shortly.</p>
 
 
 <h2><a shape="rect" name="JAX-RSAdvancedFeatures-BuildingFIQLqueries"></a>Building
FIQL queries</h2>
@@ -479,6 +646,11 @@ assertEquals(<span class="code-quote">"f
 </pre>
 </div></div>
 
+<h2><a shape="rect" name="JAX-RSAdvancedFeatures-Alternativequerylanguages"></a>Alternative
query languages</h2>
+
+<p>At the moment FIQL is the only and default query language (capable of expressing
simple and complex quieries) recognized by the Search module.<br clear="none">
+org.apache.cxf.jaxrs.ext.search.SearchConditionParser has been introduced to facilitate a
support for the alternative query languages. More work in this area will be done in the future.
</p>
+
 <h1><a shape="rect" name="JAX-RSAdvancedFeatures-Onewayinvocations"></a>Oneway
invocations</h1>
 
 <p>Resource methods with an org.apache.cxf.jaxrs.ext.Oneway annotation will be invoked
oneway with the original request returning 202 HTTP status. HTTP or JMS clients can also add
a "OnewayRequest" header if adding Oneway annotations is not an option.</p>



Mime
View raw message