You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cxf.apache.org by bu...@apache.org on 2012/10/25 16:47:39 UTC
svn commit: r836145 - in /websites/production/cxf/content:
cache/docs.pageCache docs/jax-rs-advanced-features.html
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>