Author: buildbot
Date: Thu Oct 25 14:47:39 2012
New Revision: 836145
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 Oct
25 14:47:39 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-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-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 quer
ies</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-ConsumingFIQLqueries">Consuming 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="rec
t" 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>
@@ -223,7 +223,7 @@ An expression such as "name==CXF*" can b
<p>The last two operators, "'"(OR) and ";"(AND) are used to concatenate and
build composite (possibly nested) expressions, while the first 6 operators are
used to build so called primitive expressions. </p>
-<p>As you can see FIQL is rich enough for the service implementations to offer
a more interesting search experience around the well-known data, while still
keeping the complexity of URI expressions under control which makes it simpler
to share such URI queries. </p>
+<p>As you can see FIQL is rich enough for the service implementations to offer
a more interesting search experience around the well-known data, while still
keeping the complexity of URI expressions under control which makes it simpler
to share such URI queries as well as use the same query language no matter what
data store is used internally by the service. </p>
<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>
@@ -341,19 +341,20 @@ expression or a more complex one. </p>
</div></div>
<p>Note, a property name such as "ownerinfo.name.name" uses '.' to let the
parser navigate to the actual Name bean which has a 'name' property. This can
be optimized in cases where the owner bean is known to have either a
constructor or static valueOf() method accepting the 'name' property, for
example, given</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent
panelContent">
+<pre class="code-java">
+<span class="code-keyword">public</span> class Name {
-<p>public class Name {</p>
-
-<p> private String name;<br clear="none">
- public Name() {<br clear="none">
- } <br clear="none">
- public Name(String name) </p>
-<div class="error"><span class="error">Unknown macro: {
- this.name = name;
- }</span> </div>
-<p> //setters and getters omitted for brewity<br clear="none">
-}</p>
-
+ <span class="code-keyword">private</span> <span
class="code-object">String</span> name;
+ <span class="code-keyword">public</span> Name() {
+ }
+ <span class="code-keyword">public</span> Name(<span
class="code-object">String</span> name) {
+ <span class="code-keyword">this</span>.name = name;
+ }
+ <span class="code-comment">//setters and getters omitted <span
class="code-keyword">for</span> brewity
+</span>}
+</pre>
+</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>
@@ -423,8 +424,10 @@ assertEquals("SELECT LEVEL_COLUMN FROM t
<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>
+<p>CXF 2.6.4 and CXF 2.7.1 introduce
org.apache.cxf.jaxrs.ext.search.jpa.JPATypedQueryVisitor and
org.apache.cxf.jaxrs.ext.search.jpa.JPACriteriaQueryVisitor which can be used
to capture FIQL expressions into <br clear="none">
+javax.persistence.TypedQuery or javax.persistence.criteria.CriteriaQuery
objects.</p>
+<p>For example:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent
panelContent">
<pre class="code-java">
@@ -434,19 +437,63 @@ assertEquals("SELECT LEVEL_COLUMN FROM t
<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 class="code-comment">// Find the books owned by Barry, published
starting from the first month of 2000
+</span><span class="code-comment">// ?_s=<span
class="code-quote">"date=ge=2000-01-01;ownername=barry"</span>
+</span>
+<span class="code-comment">// <span class="code-keyword">this</span> map will
have to be set as a contextual property on the jaxrs endpoint
+</span><span class="code-comment">// it assumes that Book bean has nested
OwnerInfo bean with nested Address and Name beans,
+</span><span class="code-comment">// with the latter containing 'street' and
'name' property respectively
+</span>
+Map<<span class="code-object">String</span>, <span
class="code-object">String</span>> beanPropertiesMap = <span
class="code-keyword">new</span> HashMap<<span
class="code-object">String</span>, <span
class="code-object">String</span>>();
+beanPropertiesMap.put(<span class="code-quote">"street"</span>, <span
class="code-quote">"ownerInfo.address.street"</span>);
+beanPropertiesMap.put(<span class="code-quote">"ownername"</span>, <span
class="code-quote">"ownerInfo.name.name"</span>);
+
+<span class="code-comment">// the actual application code
</span>SearchCondition<Book> sc = searchContext.getCondition(Book.class);
-JPATypedQuery<Book> visitor = <span class="code-keyword">new</span>
JPATypedQueryVisitor<Book>(entityManager, Book.class);
+SearchConditionVisitor<Book, TypedQuery<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>Using CriteriaQuery is preferred in cases when the actual result has to be
shaped into a bean of different type, using one of JPA2 CriteriaBuilder's shape
methods (array(), construct() or tuple()). For example:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent
panelContent">
+<pre class="code-java">
+
+Map<<span class="code-object">String</span>, <span
class="code-object">String</span>> beanPropertiesMap = <span
class="code-keyword">new</span> HashMap<<span
class="code-object">String</span>, <span
class="code-object">String</span>>();
+beanPropertiesMap.put(<span class="code-quote">"street"</span>, <span
class="code-quote">"ownerInfo.address.street"</span>);
+beanPropertiesMap.put(<span class="code-quote">"ownername"</span>, <span
class="code-quote">"ownerInfo.name.name"</span>);
+
+<span class="code-comment">// the actual application code
+</span>SearchCondition<Book> sc = searchContext.getCondition(Book.class);
+JPACriteriaQueryVisitor<Book, Tuple> visitor =
+ <span class="code-keyword">new</span> JPACriteriaQueryVisitor<Book,
Tuple>(entityManager, Book.class);
+sc.visit(visitor);
+
+List<SingularAttribute<Book, ?>> selections = <span
class="code-keyword">new</span> LinkedList<SingularAttribute<Book,
?>>();
+selections.add(Book_.id);
+
+visitor.selectTuple(selections);
+
+TypedQuery<Tuple> query = visitor.getQuery();
+
+Tuple tuple = typedQuery.getSingleResult();
+<span class="code-object">String</span> street = tuple.get(<span
class="code-quote">"street"</span>, <span
class="code-object">String</span>.class);
+
+</pre>
+</div></div>
+
+<p>Note that JPACriteriaQueryVisitor will automatically set aliases for an
expression like "tuple.get('street', String.class)" to work.<br clear="none">
+JPACriteriaQueryVisitor will be enhanced to support more of JPA2 advanced
constructs in time.</p>
+
<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-Lucene"></a>Lucene</h3>
+
<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>
