Author: buildbot
Date: Tue Oct 30 18:47:38 2012
New Revision: 836621
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 Oct
30 18:47:38 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><li><a shape="rect"
href="#JAX-RSAdvancedFeatures-SearchBean">SearchBean</a
></li></ul><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-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-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-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-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-Com
plexqueries">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-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>
@@ -359,7 +359,14 @@ expression or a more complex, composite
</div></div>
<p>the mapping between "oname" and "ownerinfo.name" will work too.</p>
-<h3><a shape="rect"
name="JAX-RSAdvancedFeatures-SearchBean"></a>SearchBean</h3>
+<h2><a shape="rect"
name="JAX-RSAdvancedFeatures-Mappingofquerypropertiestocolumn%2Ffieldnames"></a>Mapping
of query properties to column/field names</h2>
+
+<p>When converting FIQL queries to SQL or other untyped query language
expressions, as well as when using Lucene converter, it can be useful to be
able to map between an actual query parameter and the column or field name. All
FIQL converters shipped with CXF have constructors accepting a map for mapping
the queries to columns/fields. See the next "SearchBean" section for one
example.</p>
+
+<p>Note this property is not the same as the one described in the "Mapping of
query properties to bean properties" section. The latter (the one described in
the previous section) is required for getting FIQL queries captured into typed,
domain specific beans like Book, and it can be sufficient for JPA2 which also
has annotations like @Column. </p>
+
+
+<h2><a shape="rect"
name="JAX-RSAdvancedFeatures-SearchBean"></a>SearchBean</h2>
<p>org.apache.cxf.jaxrs.ext.search.SearchBean is a utility bean class which
can simplify analyzing the captured FIQL expressions and converting them to the
other language expressions, in cases where having to update the bean class such
as Book.class with all the properties that may need to be supported is not
practical or the properties need to be managed manually. For example:</p>
@@ -496,6 +503,47 @@ JPACriteriaQueryVisitor will be enhanced
<h3><a shape="rect" name="JAX-RSAdvancedFeatures-Lucene"></a>Lucene</h3>
+<p>Mapping of FIQL expressions to Lucene (4.0.0-BETA) Query is supported
starting from CXF 2.7.1.</p>
+
+<p>org.apache.cxf.jaxrs.ext.search.lucene.LuceneQueryVisitor can be used to
support the default (content) field or specific custom field queries.<br
clear="none">
+Queries for specific terms and phrases are supported. </p>
+
+<p>Example, "find the documents containing a 'text' term":</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent
panelContent">
+<pre class="code-java">
+<span class="code-keyword">import</span> org.apache.lucene.search.Query;
+
+SearchCondition<SearchBean> filter = <span
class="code-keyword">new</span>
FiqlParser<SearchBean>(SearchBean.class).parse(<span
class="code-quote">"ct==text"</span>);
+LuceneQueryVisitor<SearchBean> lucene = <span
class="code-keyword">new</span> LuceneQueryVisitor<SearchBean>(<span
class="code-quote">"ct"</span>, <span class="code-quote">"contents"</span>);
+lucene.visit(filter);
+org.apache.lucene.search.Query termQuery = lucene.getQuery();
+<span class="code-comment">// use Query</span>
+</pre>
+</div></div>
+
+<p>Note, "new LuceneQueryVisitor<SearchBean>("ct", "contents");" is a
simple constructor which lets create a mapping between the "ct" name used in
the query and the actual default content field. It is not required to use this
mapping but it is recommended as it keeps the query expression shorter and does
not leak the actual internal Lucene field name.</p>
+
+<p>All the FIQL operators have been mapped to related Lucene Query objects.
Queries such as "Less than", or "Greater than and less than" will work fine
against the typed fields like "org.apache.lucene.document.IntField". The
visitor can be configured with a "primitiveFieldTypeMap" map property to help
it map a given query name, example "id" to Integer.class.</p>
+
+<p>Phrases are supported too. Suppose you have few documents with each of them
containing name and value pairs like "name=Fred", "name=Barry" and you'd like
to list only the documents containing "name=Fred":</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent
panelContent">
+<pre class="code-java">
+
+SearchCondition<SearchBean> filter = <span
class="code-keyword">new</span>
FiqlParser<SearchBean>(SearchBean.class).parse(<span
class="code-quote">"name==Fred"</span>);
+LuceneQueryVisitor<SearchBean> lucene = <span
class="code-keyword">new</span> LuceneQueryVisitor<SearchBean>(<span
class="code-quote">"contents"</span>);
+lucene.visit(filter);
+org.apache.lucene.search.Query phraseQuery = lucene.getQuery();
+<span class="code-comment">// use query</span>
+</pre>
+</div></div>
+
+<p>In this example, the visitor is requested to create Lucene
org.apache.lucene.search.PhraseQuery against the specified contents field
("contents"). The visitor can also accept a contentsFieldMap map property when
different phrases may need to be checked against different contents fields.</p>
+
+
+<p>The current limitation is that no typed Date queries are supported yet
(except for the equality match), for example, "find all the documents issued
before a given date", to be supported shortly.</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>
