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 15:47:38 UTC
svn commit: r836143 - in /websites/production/cxf/content:
cache/docs.pageCache docs/jax-rs-advanced-features.html
Author: buildbot
Date: Thu Oct 25 13:47:38 2012
New Revision: 836143
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 13: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-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>
+<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>
<h1><a shape="rect" name="JAX-RSAdvancedFeatures-JMSSupport"></a>JMS Support</h1>
@@ -188,22 +188,44 @@ assertEquals(<span class="code-quote">"G
<h2><a shape="rect" name="JAX-RSAdvancedFeatures-Introduction"></a>Introduction</h2>
-<p>CXF JAXRS (since 2.3.0) lets users do the advanced search queries based on the <a shape="rect" class="external-link" href="http://tools.ietf.org/html/draft-nottingham-atompub-fiql-00" rel="nofollow">Feed Item Query Language</a>(FIQL). FIQL lets users express complex search expressions using an intuitive and URI friendly language.</p>
+<p>CXF JAXRS (since 2.3.0) supports <a shape="rect" class="external-link" href="http://tools.ietf.org/html/draft-nottingham-atompub-fiql-00" rel="nofollow">Feed Item Query Language</a>(FIQL). FIQL provides for a way to express complex search expressions using an intuitive and URI friendly language.</p>
-<p>For example, a query such as</p>
+<p>For example, the following query</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
-?_search=name==CXF;version=ge=2.2
+?_s=name==CXF;version=ge=2.2
</pre>
</div></div>
-<p>lets users to search for all the Apache projects with the name 'CXF' and the version greater or equals to '2.2'. The initial '=' separates the name of the query '_search' from the FIQL expression, while '==' and '=ge=' convey 'equals to' and 'greater or equals to' respectively.<br clear="none">
+<p>lets users to search for all the Apache projects with the name 'CXF' and the version greater or equal to '2.2'. The initial '=' separates the name of the query '_search' from the FIQL expression, while '==' and '=ge=' convey 'equals to' and 'greater or equals to' respectively.<br clear="none">
An expression such as "name==CXF*" can be used to the partial equality checks (in this example: the name should start from "CXF").</p>
-<p>More complex composite expressions can also be expressed easily enough.</p>
+<p>More complex composite expressions can also be expressed easily enough, examples:</p>
-<p>Note that either '_search' or '_s' query has to be used to pass the FIQL expression.</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+<span class="code-comment">// Find all employees younger than 25 or older than 35 living in London
+</span>/employees?_s=(age=lt=25,age=gt=35);city==London
+
+<span class="code-comment">// Find all books on math or physics published in 1999 only.
+</span>/books?_s=date=lt=2000-01-01;date=gt=1999-01-01;(sub==math,sub==physics)
+
+</pre>
+</div></div>
+
+<p>Here is a summary of FIQL operators:</p>
+
+<div class="table-wrap">
+<table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh"> Operator </th><th colspan="1" rowspan="1" class="confluenceTh"> Description </th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"> "==" </td><td colspan="1" rowspan="1" class="confluenceTd"> Equal </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"> "!=" </td><td colspan="1" rowspan="1" class="confluenceTd"> Not Equal </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"> "=lt=" </td><td colspan="1" rowspan="1" class="confluenceTd"> Less Than </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"> "=le=" </td><td colspan="1" rowspan="1" class="confluenceTd"> Less or Equal </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"> "=gt=" </td><td colspan="1" rowspan="1" class="confluenceTd"> Greater Than </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"> "=ge=" </td><td colspan="1" rowspan="1" class="confluenceTd"> Greater or Equal
</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"> ";" </td><td colspan="1" rowspan="1" class="confluenceTd"> AND </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"> "'" </td><td colspan="1" rowspan="1" class="confluenceTd"> OR </td></tr></tbody></table>
+</div>
+
+
+<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>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-DependenciesandConfiguration"></a>Dependencies and Configuration</h2>
@@ -214,7 +236,7 @@ An expression such as "name==CXF*" can b
<span class="code-tag"><dependency></span>
<span class="code-tag"><groupId></span>org.apache.cxf<span class="code-tag"></groupId></span>
<span class="code-tag"><artifactId></span>cxf-rt-rs-extension-search<span class="code-tag"></artifactId></span>
- <span class="code-tag"><version></span>2.5.0<span class="code-tag"></version></span>
+ <span class="code-tag"><version></span>2.6.0<span class="code-tag"></version></span>
<span class="code-tag"></dependency></span>
</pre>
</div></div>
@@ -251,7 +273,109 @@ An expression such as "name==CXF*" can b
</div></div>
<p>Note that a searchContext.getCondition(Book.class) call may return an arbitrary complex SearchCondition, it can be a simple primitive<br clear="none">
-expression or a more complex one. The Book class needs to have a matching property per every name found in the FIQL expression, for example, given a 'name==b;id==123' expression, the Book class would need to have 'name' and 'id' properties available.</p>
+expression or a more complex one. </p>
+
+<h2><a shape="rect" name="JAX-RSAdvancedFeatures-CapturingFIQLqueries"></a>Capturing FIQL queries </h2>
+
+<p>For the query expression to be captured, a bean like Book.class is instantiated and has all the search properties injected into it. A complex composite expression will be 'injected' into a number of Book instances - something that may have to be optimized.</p>
+
+<p>Note that by default, a bean such as Book class needs to have a matching property per every property name found in the FIQL expression, for example, given a 'name==b;id==123' expression, the Book class would need to have 'name' and 'id' properties available. The reason for this strict mode being enabled by default is that ignoring a property which can not be captured may lead to a false or unexpected match, for example, if Book 'name' property has been renamed to 'title' then ignoring the 'name' property will lead to a wider match. Thus, if the property does not exist, org.apache.cxf.jaxrs.ext.search.PropertyNotFoundException will be thrown; capturing it can let returning an empty response or retry with the more lax mode, see the next paragraph.</p>
+
+<p>When a more lax parsing of FIQL expressions is expected, for example, where the primitive expressions are joined by "OR", using SearchBean (see one of the next subsections) or setting a contextual property "search.lax.property.match" will help. The former option is better when you need to know the list of all the properties which have been used in the expression, even those which will not be possible to use for the actual search; the latter option will simply have the unrecognized properties ignored.</p>
+
+<h3><a shape="rect" name="JAX-RSAdvancedFeatures-Mappingofquerypropertiestobeanproperties"></a>Mapping of query properties to bean properties</h3>
+
+<p>As noted above, when a 'typed' bean such as Book.class is used to capture the expressions, a property found in the query expression that can not be mapped to a specific Book property will lead to an exception being reported or it can be optionally ignored. In the reality, there is a number of reasons why the direct match between properties found in query expressions and in capturing beans may not be ideal:</p>
+
+<ul class="alternate" type="square"><li>Capturing beans may evolve independently of the actual queries; for example, a working query such as "name==b" will break if a Book 'name' gets renamed to 'title' which will make it difficult to have the queries bookmarked.</li><li>Direct match will simply not work for cases where an actual bean property does not belong to the capturing bean itself but to one of its child properties; for example, a JPA2 Book entity may have an OwnerInfo bean with Name bean property which does contain a primitive 'name' property.</li></ul>
+
+
+<p>The preferred approach, when working with typed beans, is to register a bean properties map, using a "search.bean.property.map" contextual 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 Book {
+
+ <span class="code-keyword">private</span> <span class="code-object">int</span> id;
+ <span class="code-keyword">private</span> OwnerInfo ownerinfo;
+ <span class="code-comment">//setters and getters omitted <span class="code-keyword">for</span> brewity
+</span>}
+
+@Embeddable
+<span class="code-keyword">public</span> class OwnerInfo {
+
+ <span class="code-keyword">private</span> Address address;
+ <span class="code-keyword">private</span> Name name;
+ <span class="code-comment">//setters and getters omitted <span class="code-keyword">for</span> brewity
+</span>}
+
+@Embeddable
+<span class="code-keyword">public</span> class Name {
+
+ <span class="code-keyword">private</span> <span class="code-object">String</span> name;
+ <span class="code-comment">//setters and getters omitted <span class="code-keyword">for</span> brewity
+</span>}
+
+</pre>
+</div></div>
+
+<p>and the following map:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-xml">
+<span class="code-tag"><map></span>
+ <span class="code-tag"><span class="code-comment"><!-- 'oname' is alias for the actual nested bean property --></span></span>
+ <span class="code-tag"><entry key=<span class="code-quote">"oname"</span> value=<span class="code-quote">"ownerinfo.name.name"</span>/></span>
+<span class="code-tag"></map></span>
+</pre>
+</div></div>
+
+<p>will let users type and bookmark queries (and without seeing them producing unexpected results) like this one:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+<span class="code-comment">//Find all the books owned by Fred with id greater than 100
+</span>/books?_s=id=gt=100;oname=Fred
+</pre>
+</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>
+
+<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>
+
+<p>the mapping between "oname" and "ownerinfo.name" will work too.</p>
+
+<h3><a shape="rect" name="JAX-RSAdvancedFeatures-SearchBean"></a>SearchBean</h3>
+
+<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>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+<span class="code-comment">// ?_s=<span class="code-quote">"level=gt=10"</span>
+</span>SearchCondition<SearchBean> sc = searchContext.getCondition(SearchBean.class);
+
+Map\<, <span class="code-object">String</span>\> fieldMap = <span class="code-keyword">new</span> HashMap\<<span class="code-object">String</span>, <span class="code-object">String</span>\>();
+fieldMap.put(<span class="code-quote">"level"</span>, <span class="code-quote">"LEVEL_FIELD"</span>);
+
+SQLPrinterVisitor<SearchBean> visitor = <span class="code-keyword">new</span> SQLPrinterVisitor<SearchBean>(fieldMap, <span class="code-quote">"table"</span>, <span class="code-quote">"LEVEL_COLUMN"</span>);
+sc.visit(visitor);
+assertEquals("SELECT LEVEL_COLUMN FROM table
+ WHERE LEVEL_COLUMN > '10'",
+ visitor.getResult());
+</pre>
+</div></div>
+
<h2><a shape="rect" name="JAX-RSAdvancedFeatures-ConvertingFIQLqueries"></a>Converting FIQL queries</h2>
@@ -386,26 +510,6 @@ List<Book> books = typedQuery.getR
</pre>
</div></div>
-<h3><a shape="rect" name="JAX-RSAdvancedFeatures-SearchBean"></a>SearchBean</h3>
-
-<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 thatmay need to be supported is not practical. For example:</p>
-
-<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
-<pre class="code-java">
-<span class="code-comment">// ?_s=<span class="code-quote">"level=gt=10"</span>
-</span>SearchCondition<SearchBean> sc = searchContext.getCondition(SearchBean.class);
-
-Map\<, <span class="code-object">String</span>\> fieldMap = <span class="code-keyword">new</span> HashMap\<<span class="code-object">String</span>, <span class="code-object">String</span>\>();
-fieldMap.put(<span class="code-quote">"level"</span>, <span class="code-quote">"LEVEL_FIELD"</span>);
-
-SQLPrinterVisitor<SearchBean> visitor = <span class="code-keyword">new</span> SQLPrinterVisitor<SearchBean>(fieldMap, <span class="code-quote">"table"</span>, <span class="code-quote">"LEVEL_COLUMN"</span>);
-sc.visit(visitor);
-assertEquals("SELECT LEVEL_COLUMN FROM table
- WHERE LEVEL_COLUMN > '10'",
- visitor.getResult());
-</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">
@@ -613,15 +717,15 @@ assertEquals(<span class="code-quote">"f
<h2><a shape="rect" name="JAX-RSAdvancedFeatures-Usingdatesinqueries"></a>Using dates in queries</h2>
-<p>By default, the date values have to have the following <a shape="rect" class="external-link" href="http://download.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html" rel="nofollow">format</a>: "yyyy-MM-dd'T'HH:mm:ss.SSSZ", for example:</p>
+<p>By default, the date values have to have the following <a shape="rect" class="external-link" href="http://download.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html" rel="nofollow">format</a>: "yyyy-MM-dd", for example:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
-?_search=time=le=2010-03-11T18:00:00.000+00:00
+?_search=date=le=2010-03-11
</pre>
</div></div>
-<p>A simpler date format can be supported. Use "search.date-format" and "search.timezone.support" contextual properies, ex, "search.date-format"="yyyy-MM-dd'T'HH:mm:ss" and "search.timezone.support"="false" will let users avoid specifying milliseconds and timezones:</p>
+<p>A custom date format can be supported. Use "search.date-format" contextual property, example, "search.date-format"="yyyy-MM-dd'T'HH:mm:ss" will let users type:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
@@ -629,6 +733,8 @@ assertEquals(<span class="code-quote">"f
</pre>
</div></div>
+<p>If needed, "search.timezone.support" can be enabled to get the timezones supported too.</p>
+
<p>At the moment, for custom date formats be recognized by SearchConditionBuilder, FIQLSearchConditionBuilder has to be created explicitly:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
@@ -659,7 +765,7 @@ org.apache.cxf.jaxrs.ext.search.SearchCo
<p>Please see <a shape="rect" class="external-link" href="http://sberyozkin.blogspot.com/2008/12/continuations-in-cxf.html" rel="nofollow">this blog entry</a> describing how JAXRS (and indeed) JAXWS services can rely on the CXF Continuations API. </p>
-<p>Please see the <a shape="rect" class="createlink" href="https://cwiki.apache.org/confluence/pages/createpage.action?spaceKey=CXF20DOC&title=CXF+Continuations&linkCreation=true&fromPageId=24190907">CXF Continuations</a> page for more information.</p>
+<p>Please see the <span class="error">[CXF Continuations]</span> page for more information.</p>
<h1><a shape="rect" name="JAX-RSAdvancedFeatures-Serversidecaching"></a>Server-side caching</h1>