Author: buildbot
Date: Tue Nov 20 14:48:01 2012
New Revision: 838931
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 Tue Nov
20 14:48:01 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-WorkingwithFIQLqueries">Working with FIQL
queries</a></li><li><a shape="rect"
href="#JAX-RSAdvancedFeatures-CapturingFIQLqueries">Capturing FIQL
queries</a></li><ul><li><a shape="rect"
href="#JAX-RSAdvancedFeatures-Mappingofquerypropertiestobeanproperties">Mapping
of query properties to bean properties</a></li></ul><li><a shape="rect"
href="#JAX-RSAdvancedFeatures-Mappingofqueryproper
tiestocolumn%2Ffieldnames">Mapping of query properties to column/field
names</a></li><li><a shape="rect"
href="#JAX-RSAdvancedFeatures-SearchBean">SearchBean</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-Lucene">Lucene</a></li><li><a shape="rect"
href="#JAX-RSAdvancedFeatures-Customvisitors">Custom
visitors</a></li><ul><li><a shape="rect"
href="#JAX-RSAdvancedFeatures-Untypedconverters">Untyped
converters</a></li><li><a shape="rect"
href="#JAX-RSAdvancedFeatures-Typedconverters">Typed converters</a></li><li><a
shape="rect" href="#JAX-RSAdvancedFeatures-Customparsing">Custom
parsing</a></li></ul></ul><li><a shape="rect"
href="#JAX-RSAdvancedFeatures-SearchExpressionsinURIPathsegments">Search
Expressions in URI Path seg
ments</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-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-RSAdvanc
edFeatures-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-WhentouseFIQL">When to use
FIQL</a></li><li><a shape="rect"
href="#JAX-RSAdvancedFeatures-DependenciesandConfiguration">Dependencies and
Configuration</a></li><li><a shape="rect"
href="#JAX-RSAdvancedFeatures-WorkingwithFIQLqueries">Working with FIQL
queries</a></li><li><a shape="rect"
href="#JAX-RSAdvancedFeatures-CapturingFIQLqueries">Capturing FIQL
queries</a></li><ul><li><a shape="rect"
href="#JAX-RSAdvancedFeatures-Mappingofquerypropertiestobeanproperties">Mapping
of query properties to bean prop
erties</a></li></ul><li><a shape="rect"
href="#JAX-RSAdvancedFeatures-Mappingofquerypropertiestocolumn%2Ffieldnames">Mapping
of query properties to column/field names</a></li><li><a shape="rect"
href="#JAX-RSAdvancedFeatures-SearchBean">SearchBean</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-Lucene">Lucene</a></li><li><a shape="rect"
href="#JAX-RSAdvancedFeatures-Customvisitors">Custom
visitors</a></li><ul><li><a shape="rect"
href="#JAX-RSAdvancedFeatures-Untypedconverters">Untyped
converters</a></li><li><a shape="rect"
href="#JAX-RSAdvancedFeatures-Typedconverters">Typed converters</a></li><li><a
shape="rect" href="#JAX-RSAdvancedFeatures-Customparsing">Custom
parsing</a></li></ul></ul><li><a shape="rect" href="#JAX
-RSAdvancedFeatures-ConvertingFIQLquerieswithQueryContext">Converting FIQL
queries with QueryContext</a></li><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="re
ct" 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>
@@ -227,6 +227,18 @@ An expression such as "name==CXF*" can b
<p>Note, when passing the FIQL queries via URI query parameters, either
'_search' or '_s' query parameter has to be used to mark a FIQL expression for
it not to 'interfere' with other optional query parameters. Alternatively the
expressions can be encoded as URI path segments, see the sections below for
more information.</p>
+<h2><a shape="rect" name="JAX-RSAdvancedFeatures-WhentouseFIQL"></a>When to
use FIQL</h2>
+
+<p>Consider a typical query expression such as "a=avalue&c=cvalue". This
can mean either "find all resources with 'a' and 'c' properties equal to
'avalue' and 'cvalue'" or "find all resources with 'a' or 'c' properties equal
to 'avalue' and 'cvalue'". It is application specific on whether it is "and" or
"or" as far as the combination of multiple query properties is concerned.</p>
+
+<p>It is also difficult to capture conditional expressions with the custom
language, example, "find all resource with 'a' property less than 123".</p>
+
+<p>Use FIQL for capturing simple or medium complexity queries, typically in
cases where a set of properties that a user can specify is well-known. Example,
a book store resource will let users search books given a number of useful
properties(those of Book and/or Library a given book is available in, etc). </p>
+
+
+
+
+
<h2><a shape="rect"
name="JAX-RSAdvancedFeatures-DependenciesandConfiguration"></a>Dependencies and
Configuration</h2>
<p>The following dependency is required starting from CXF 2.6.0:</p>
@@ -846,6 +858,71 @@ org.apache.lucene.search.Query phraseQue
</pre>
</div></div>
+<h2><a shape="rect"
name="JAX-RSAdvancedFeatures-ConvertingFIQLquerieswithQueryContext"></a>Converting
FIQL queries with QueryContext</h2>
+
+<p><span class="error">[QueryContext|]</span> is the helper context available
from CXF 2.7.1 which makes it simpler for the application code to<br
clear="none">
+get the converted query expression, with the actual converter/visitor
registered as the jaxrs contextual property, for example:</p>
+
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent
panelContent">
+<pre class="code-java">
+<span class="code-keyword">import</span> java.util.ArrayList;
+<span class="code-keyword">import</span> java.util.List;
+<span class="code-keyword">import</span>
org.apache.cxf.jaxrs.JAXRSServerFactoryBean;
+<span class="code-keyword">import</span>
org.apache.cxf.jaxrs.ext.search.QueryContextProvider;
+<span class="code-keyword">import</span>
org.apache.cxf.jaxrs.ext.search.SearchBean;
+<span class="code-keyword">import</span>
org.apache.cxf.jaxrs.ext.search.sql.SQLPrinterVisitor;
+
+<span class="code-keyword">import</span> books.BookStore;
+
+<span class="code-comment">// Register the visitor:
+</span>JAXRSServerFactoryBean sf = <span class="code-keyword">new</span>
JAXRSServerFactoryBean();
+List<<span class="code-object">Object</span>> providers = <span
class="code-keyword">new</span> ArrayList<<span
class="code-object">Object</span>>();
+providers.add(<span class="code-keyword">new</span> QueryContextProvider());
+sf.setProviders(providers);
+sf.getProperties(<span class="code-keyword">true</span>).put(<span
class="code-quote">"search.visitor"</span>, <span
class="code-keyword">new</span> SQLPrinterVisitor<SearchBean>(<span
class="code-quote">"books"</span>));
+
+
+sf.setResourceClasses(BookStore.class);
+server = sf.create();
+</pre>
+</div></div>
+
+<p>and convert the queries:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent
panelContent">
+<pre class="code-java">
+@Path(<span class="code-quote">"/"</span>)
+<span class="code-keyword">public</span> class BookStore {
+ @GET
+ @Path(<span class="code-quote">"/books/{expression}"</span>)
+ @Produces(<span class="code-quote">"application/xml"</span>)
+ <span class="code-keyword">public</span> List<Book>
getBookQueryContext(@PathParam(<span class="code-quote">"expression"</span>)
<span class="code-object">String</span> expression,
+ @Context QueryContext searchContext)
+ <span class="code-keyword">throws</span> BookNotFoundFault {
+ <span class="code-object">String</span> sqlExpression =
searchContext.getConvertedExpression(expression);
+ <span class="code-comment">// pass it to the SQL DB and <span
class="code-keyword">return</span> the list of Books
+</span>
+ <span class="code-comment">// or instead of registering
SQLPrinterVisitor, register JPA2TypedQueryVisitor
+</span> <span class="code-comment">// (see section on JPA2) and <span
class="code-keyword">do</span>
+</span> TypedQuery<Book> query =
searchContext.getConvertedExpression(expression);
+ <span class="code-keyword">return</span> query.getResultList();
+ }
+}
+</pre>
+</div></div>
+
+<p>where the client code may look like this:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent
panelContent">
+<pre class="code-java">
+<span class="code-object">String</span> address = <span
class="code-quote">"http:<span
class="code-comment">//localhost:8080/bookstore/books/id=ge=123"</span>;
+</span>WebClient client = WebClient.create(address);
+client.accept(<span class="code-quote">"application/xml"</span>);
+List<Book> books = client.getCollection(Book.class);
+</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">
