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<Book>
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<Book>
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<Book>
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<Book>
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<Book>
doFindSelectedBooks(<span class="code-object">String</span> searchExpression) {
+ SearchCondition<Book> sc = context.getCondition(searchExpression,
Book.class);
+
+ <span class="code-comment">// JPA2 enity manager is initialized earlier
+</span> JPATypedQuery<Book> visitor = <span
class="code-keyword">new</span> JPATypedQueryVisitor<Book>(entityManager,
Book.class);
+ sc.visit(visitor);
+
+ TypedQuery<Book> 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<Book>
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<Chapter>
doFindSelectedChapters(<span class="code-object">String</span>
searchExpression, <span class="code-object">int</span> chapterIndex) {
+ SearchCondition<Book> sc = context.getCondition(searchExpression,
Book.class);
+
+ <span class="code-comment">// JPA2 enity manager is initialized earlier
+</span> 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();
+
+ List<Chapter> chapters = <span class="code-keyword">new</span>
ArrayList<Chapter>(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<Book>
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<Chapter>
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<Book> bookCondition =
context.getCondition(searchExpression, Book.class);
+
+ JPATypedQuery<Book> visitor = <span
class="code-keyword">new</span> JPATypedQueryVisitor<Book>(entityManager,
Book.class);
+ bookCondition.visit(visitor);
+ TypedQuery<Book> typedQuery = visitor.getQuery();
+ List<Book> books = typedQuery.getResultList();
+
+ <span class="code-comment">// now get the chapters
+</span> SearchCondition<Chapter> chapterCondition =
context.getCondition(chapterExpression, Chapter.class);
+ List<Chapter> chapters = <span class="code-keyword">new</span>
ArrayList<Chapter>();
+ <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>
