You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cxf.apache.org by dk...@apache.org on 2013/12/19 17:43:23 UTC
svn commit: r891058 [19/31] - in /websites/production/cxf/content: ./
2008/04/28/ 2008/06/20/ 2009/02/10/ 2009/08/04/ cache/ docs/
Modified: websites/production/cxf/content/docs/jax-rs-search.html
==============================================================================
--- websites/production/cxf/content/docs/jax-rs-search.html (original)
+++ websites/production/cxf/content/docs/jax-rs-search.html Thu Dec 19 16:43:08 2013
@@ -99,13 +99,7 @@ Apache CXF -- JAX-RS Search
<div id="wrapper-menu-page-bottom">
<div id="menu-page">
<!-- NavigationBar -->
-<div id="navigation"><ul class="alternate"><li><a shape="rect" href="overview.html">Overview</a></li><li><a shape="rect" href="how-tos.html">How-Tos</a></li><li><a shape="rect" href="frontends.html">Frontends</a></li><li><a shape="rect" href="databindings.html">DataBindings</a></li><li><a shape="rect" href="transports.html">Transports</a></li><li><a shape="rect" href="configuration.html">Configuration</a></li><li><a shape="rect" href="debugging-and-logging.html">Debugging and Logging</a></li><li><a shape="rect" href="tools.html">Tools</a></li><li><a shape="rect" href="restful-services.html">RESTful Services</a></li><li><a shape="rect" href="wsdl-bindings.html">WSDL Bindings</a></li><li><a shape="rect" href="service-routing.html">Service Routing</a></li><li><a shape="rect" href="dynamic-languages.html">Dynamic Languages</a></li><li><a shape="rect" href="ws-support.html">WS-* Support</a></li><li><a shape="rect" href="advanced-integration.html">Advanced Integration</a></li><li><a shape
="rect" href="deployment.html">Deployment</a></li><li><a shape="rect" href="schemas-and-namespaces.html">Use of Schemas and Namespaces</a></li></ul>
-
-
-<hr>
-<ul class="alternate"><li>Search<br clear="none">
-
-<form enctype="application/x-www-form-urlencoded" method="get" id="cse-search-box" action="http://www.google.com/cse">
+<div id="navigation"><ul class="alternate"><li><a shape="rect" href="overview.html">Overview</a></li><li><a shape="rect" href="how-tos.html">How-Tos</a></li><li><a shape="rect" href="frontends.html">Frontends</a></li><li><a shape="rect" href="databindings.html">DataBindings</a></li><li><a shape="rect" href="transports.html">Transports</a></li><li><a shape="rect" href="configuration.html">Configuration</a></li><li><a shape="rect" href="debugging-and-logging.html">Debugging and Logging</a></li><li><a shape="rect" href="tools.html">Tools</a></li><li><a shape="rect" href="restful-services.html">RESTful Services</a></li><li><a shape="rect" href="wsdl-bindings.html">WSDL Bindings</a></li><li><a shape="rect" href="service-routing.html">Service Routing</a></li><li><a shape="rect" href="dynamic-languages.html">Dynamic Languages</a></li><li><a shape="rect" href="ws-support.html">WS-* Support</a></li><li><a shape="rect" href="advanced-integration.html">Advanced Integration</a></li><li><a shape
="rect" href="deployment.html">Deployment</a></li><li><a shape="rect" href="schemas-and-namespaces.html">Use of Schemas and Namespaces</a></li></ul><hr><ul class="alternate"><li><p>Search</p></li></ul><form enctype="application/x-www-form-urlencoded" method="get" id="cse-search-box" action="http://www.google.com/cse">
<div>
<input type="hidden" name="cx" value="002890367768291051730:o99qiwa09y4">
<input type="hidden" name="ie" value="UTF-8">
@@ -113,13 +107,7 @@ Apache CXF -- JAX-RS Search
<input type="submit" name="sa" value="Search">
</div>
</form>
-<script type="text/javascript" src="http://www.google.com/cse/brand?form=cse-search-box&lang=en"></script>
-</li></ul>
-
-
-<hr>
-<ul class="alternate"><li><a shape="rect" href="http://cxf.apache.org/javadoc/latest/">API (Javadoc)</a></li><li><a shape="rect" href="http://cxf.apache.org/">CXF Website</a></li></ul>
-</div>
+<script type="text/javascript" src="http://www.google.com/cse/brand?form=cse-search-box&lang=en"></script><hr><ul class="alternate"><li><a shape="rect" href="http://cxf.apache.org/javadoc/latest/">API (Javadoc)</a></li><li><a shape="rect" href="http://cxf.apache.org/">CXF Website</a></li></ul></div>
<!-- NavigationBar -->
</div>
</div>
@@ -129,15 +117,13 @@ Apache CXF -- JAX-RS Search
<td height="100%">
<!-- Content -->
<div class="wiki-content">
-<div id="ConfluenceContent"><p><span style="font-size:2em;font-weight:bold"> JAX-RS: Search </span></p><p></p>
+<div id="ConfluenceContent"><h1 id="JAX-RSSearch-JAX-RSSearch">JAX-RS Search</h1><p> </p><p><style type="text/css">/*<![CDATA[*/
+div.rbtoc1387471148351 {padding: 0px;}
+div.rbtoc1387471148351 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1387471148351 li {margin-left: 0px;padding-left: 0px;}
-<style type="text/css">/*<![CDATA[*/
-div.rbtoc1387228359240 {padding: 0px;}
-div.rbtoc1387228359240 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1387228359240 li {margin-left: 0px;padding-left: 0px;}
-
-/*]]>*/</style><div class="toc-macro rbtoc1387228359240">
-<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSSearch-FIQLsearchqueries">FIQL search queries</a>
+/*]]>*/</style></p><div class="toc-macro rbtoc1387471148351">
+<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSSearch-JAX-RSSearch">JAX-RS Search</a></li><li><a shape="rect" href="#JAX-RSSearch-FIQLsearchqueries">FIQL search queries</a>
<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSSearch-Introduction">Introduction</a></li><li><a shape="rect" href="#JAX-RSSearch-WhentouseFIQL">When to use FIQL</a></li><li><a shape="rect" href="#JAX-RSSearch-DependenciesandConfiguration">Dependencies and Configuration</a></li><li><a shape="rect" href="#JAX-RSSearch-WorkingwithFIQLqueries">Working with FIQL queries</a></li><li><a shape="rect" href="#JAX-RSSearch-CapturingFIQLqueries">Capturing FIQL queries</a>
<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSSearch-Mappingofquerypropertiestobeanproperties">Mapping of query properties to bean properties</a></li><li><a shape="rect" href="#JAX-RSSearch-Parserproperties">Parser properties</a></li></ul>
</li><li><a shape="rect" href="#JAX-RSSearch-Mappingofquerypropertiestocolumn/fieldnames">Mapping of query properties to column/field names</a></li><li><a shape="rect" href="#JAX-RSSearch-SearchBean">SearchBean</a></li><li><a shape="rect" href="#JAX-RSSearch-ConvertingFIQLqueries">Converting FIQL queries</a>
@@ -150,103 +136,31 @@ div.rbtoc1387228359240 li {margin-left:
<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSSearch-Basicqueries">Basic queries</a></li><li><a shape="rect" href="#JAX-RSSearch-Complexqueries">Complex queries</a></li></ul>
</li><li><a shape="rect" href="#JAX-RSSearch-Validation">Validation</a></li><li><a shape="rect" href="#JAX-RSSearch-BuildingFIQLqueries">Building FIQL queries</a></li><li><a shape="rect" href="#JAX-RSSearch-Usingdatesinqueries">Using dates in queries</a></li><li><a shape="rect" href="#JAX-RSSearch-Alternativequerylanguages">Alternative query languages</a></li></ul>
</li></ul>
-</div>
-
-<h1 id="JAX-RSSearch-FIQLsearchqueries">FIQL search queries</h1>
-
-<h2 id="JAX-RSSearch-Introduction">Introduction</h2>
-
-<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, the following query</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-?_s=name==CXF;version=ge=2.2
+</div><h1 id="JAX-RSSearch-FIQLsearchqueries">FIQL search queries</h1><h2 id="JAX-RSSearch-Introduction">Introduction</h2><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, the following query</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[?_s=name==CXF;version=ge=2.2
]]></script>
-</div></div>
-
-<p>lets users 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 '_s' 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 do the partial equality check (example: the name should start from "CXF").</p>
-
-<p>More complex composite expressions can also be expressed easily enough, examples:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-// Find all employees younger than 25 or older than 35 living in London
+</div></div><p>lets users 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 '_s' 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 do the partial equality check (example: the name should start from "CXF").</p><p>More complex composite expressions can also be expressed easily enough, examples:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[// Find all employees younger than 25 or older than 35 living in London
/employees?_s=(age=lt=25,age=gt=35);city==London
// Find all books on math or physics published in 1999 only.
/books?_s=date=lt=2000-01-01;date=gt=1999-01-01;(sub==math,sub==physics)
]]></script>
-</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"><p> Operator </p></th><th colspan="1" rowspan="1" class="confluenceTh"><p> Description </p></th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> "==" </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> Equal </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> "!=" </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> Not Equal </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> "=lt=" </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> Less Than </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> "=le=" </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> Less or Equal </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> "=gt=" </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> Greater Than </p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p> "=ge=" </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> Greater or Equal </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> ";" </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> AND </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> "," </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> OR </p></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>From CXF 2.7.7: single '=' operator can be optionally supported instead of '==': set a "fiql.support.single.equals.operator" contextual property to "true". </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. Starting from CXF 2.7.2 it is also possible to use the whole query component to convey a FIQL expression, example,</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-
-// Find all books on math or physics published in 1999 only.
+</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"><p>Operator</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>Description</p></th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>"=="</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Equal</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>"!="</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Not Equal</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>"=lt="</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Less Than</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>"=le="</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Less or Equal</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>"=gt="</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Greater Than</p></td></tr><
tr><td colspan="1" rowspan="1" class="confluenceTd"><p>"=ge="</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Greater or Equal</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>";"</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>AND</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>","</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>OR</p></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>From CXF 2.7.7: single '=' operator can be optionally supported instead of '==': set a "fiql.support.single.equals.operator" contextual property to "true".</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 U
RI 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. Starting from CXF 2.7.2 it is also possible to use the whole query component to convey a FIQL expression, example,</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[// Find all books on math or physics published in 1999 only.
/books?date=lt=2000-01-01;date=gt=1999-01-01;(sub==math,sub==physics)
]]></script>
-</div></div>
-
-<p>Note that no "_s" or "_search" query parameter is available, the whole query string starting after "?" represents an actual FIQL expression.<br clear="none">
-Please use "search.use.all.query.component" contextual property for this option be supported.</p>
-
-<p>Alternatively the expressions can be encoded as URI path segments, see the sections below for more information.</p>
-
-<h2 id="JAX-RSSearch-WhentouseFIQL">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 to capture conditional expressions with the custom language, example, "find all resource with 'a' property less than 123" when a number of properties is large or the entities which can be searched are created dynamically.</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>
-
-<p>Furthermore, consider using FIQL and SearchConditionVisitor for the purpose of generalizing the search code, when the number of properties and entities is large, dynamic, etc.</p>
-
-
-<h2 id="JAX-RSSearch-DependenciesandConfiguration">Dependencies and Configuration</h2>
-
-<p>The following dependency is required starting from CXF 2.6.0:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[
- <dependency>
+</div></div><p>Note that no "_s" or "_search" query parameter is available, the whole query string starting after "?" represents an actual FIQL expression.<br clear="none"> Please use "search.use.all.query.component" contextual property for this option be supported.</p><p>Alternatively the expressions can be encoded as URI path segments, see the sections below for more information.</p><h2 id="JAX-RSSearch-WhentouseFIQL">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 to capture conditional expressions with the custom language, example, "find all resource with 'a' property less than 123" when a number of properties is
large or the entities which can be searched are created dynamically.</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><p>Furthermore, consider using FIQL and SearchConditionVisitor for the purpose of generalizing the search code, when the number of properties and entities is large, dynamic, etc.</p><h2 id="JAX-RSSearch-DependenciesandConfiguration">Dependencies and Configuration</h2><p>The following dependency is required starting from CXF 2.6.0:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[ <dependency>
<groupId>org.apache.cxf</groupId>
<artifactId>cxf-rt-rs-extension-search</artifactId>
<version>2.6.0</version>
</dependency>
]]></script>
-</div></div>
-
-<p>Additionally, in CXF 2.6.0, <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/extensions/search/src/main/java/org/apache/cxf/jaxrs/ext/search/SearchContextProvider.java">SearchContextProvider</a> needs to be registered as jaxrs:provider. </p>
-
-<h2 id="JAX-RSSearch-WorkingwithFIQLqueries">Working with FIQL queries</h2>
-
-<p>To work with FIQL queries, a <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/extensions/search/src/main/java/org/apache/cxf/jaxrs/ext/search/SearchContext.java">SearchContext</a> needs be injected into an application code and used to retrieve a <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/extensions/search/src/main/java/org/apache/cxf/jaxrs/ext/search/SearchCondition.java">SearchCondition</a> representing the current FIQL query. This SearchCondition can be used in a number of ways for finding the matching data. </p>
-
-<p>In this section we assume that the data to be matched are already available in memory. The follow-up section on converting the queries will show how FIQL queries can be converted to some other query language typed or text expression.</p>
-
-<p>So, suppose a list or map of Book instances is available. Here is one possible approach:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-@Path("books")
+</div></div><p>Additionally, in CXF 2.6.0, <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/extensions/search/src/main/java/org/apache/cxf/jaxrs/ext/search/SearchContextProvider.java">SearchContextProvider</a> needs to be registered as jaxrs:provider.</p><h2 id="JAX-RSSearch-WorkingwithFIQLqueries">Working with FIQL queries</h2><p>To work with FIQL queries, a <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/extensions/search/src/main/java/org/apache/cxf/jaxrs/ext/search/SearchContext.java">SearchContext</a> needs be injected into an application code and used to retrieve a <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/extensions/search/src/main/java/org/apache/cxf/jaxrs/ext/search/SearchCondition.java">SearchCondition</a> representing the current FIQL query. This SearchCondition can be used in a number of ways for finding the matching data.</p><p>In this
section we assume that the data to be matched are already available in memory. The follow-up section on converting the queries will show how FIQL queries can be converted to some other query language typed or text expression.</p><p>So, suppose a list or map of Book instances is available. Here is one possible approach:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[@Path("books")
public class Books {
private Map<Long, Book> books;
@@ -265,32 +179,8 @@ private SearchContext context;
}
}
]]></script>
-</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, composite one. </p>
-
-<h2 id="JAX-RSSearch-CapturingFIQLqueries">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 id="JAX-RSSearch-Mappingofquerypropertiestobeanproperties">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"><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 or directly with SearchContext. For example, given</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-
-public class Book {
+</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, composite one.</p><h2 id="JAX-RSSearch-CapturingFIQLqueries">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 id="JAX-RSSearch-Mappingofquerypropertiestobeanproperties">Mapping of query properties to bean properties</h3><p>As noted above, when a 'typed' bean such as Book.class i
s 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"><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 propert
ies map, using a "search.bean.property.map" contextual property or directly with SearchContext. For example, given</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[public class Book {
private int id;
private OwnerInfo ownerinfo;
@@ -313,32 +203,18 @@ public class Name {
}
]]></script>
-</div></div>
-
-<p>and the following map:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[
-<map>
+</div></div><p>and the following map:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<map>
<!-- 'oname' is alias for the actual nested bean property -->
<entry key="oname" value="ownerinfo.name.name"/>
</map>
]]></script>
-</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 pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-//Find all the books owned by Fred with id greater than 100
+</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 pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[//Find all the books owned by Fred with id greater than 100
/books?_s=id=gt=100;oname=Fred
]]></script>
-</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 pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-public class Name {
+</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 pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[public class Name {
private String name;
public Name() {
@@ -349,48 +225,15 @@ public class Name {
//setters and getters omitted for brewity
}
]]></script>
-</div></div>
-<p>the mapping between "oname" and "ownerinfo.name" will work too.</p>
-
-<p>You can also have many to one mappings, for example</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[
-<map>
+</div></div><p>the mapping between "oname" and "ownerinfo.name" will work too.</p><p>You can also have many to one mappings, for example</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<map>
<!-- 'oname' and 'owner' are aliases for the 'ownerinfo.name.name' bean property -->
<entry key="oname" value="ownerinfo.name.name"/>
<entry key="owner" value="ownerinfo.name.name"/>
</map>
]]></script>
-</div></div>
-
-
-
-<h3 id="JAX-RSSearch-Parserproperties">Parser properties</h3>
-
-<p>The parser properties are the ones which tell the parser how to treat the conversion of Date values and the unrecognized search property names. </p>
-
-<p>As explained above, "search.lax.property.match" can be used to tell the parser that it should ignore the search property names which have no corresponding bean properties.</p>
-
-<p>"search.date.format" and "search.timezone.support" tell the parser how to convert the date values, see "Using dates in queries" section.</p>
-
-<p>More properties may be supported in the future.</p>
-
-<p>All of these properties can be set as endpoint contextual properties or directly with SearchContext.</p>
-
-<h2 id="JAX-RSSearch-Mappingofquerypropertiestocolumn/fieldnames">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 id="JAX-RSSearch-SearchBean">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>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-// ?_s="level=gt=10"
+</div></div><h3 id="JAX-RSSearch-Parserproperties">Parser properties</h3><p>The parser properties are the ones which tell the parser how to treat the conversion of Date values and the unrecognized search property names.</p><p>As explained above, "search.lax.property.match" can be used to tell the parser that it should ignore the search property names which have no corresponding bean properties.</p><p>"search.date.format" and "search.timezone.support" tell the parser how to convert the date values, see "Using dates in queries" section.</p><p>More properties may be supported in the future.</p><p>All of these properties can be set as endpoint contextual properties or directly with SearchContext.</p><h2 id="JAX-RSSearch-Mappingofquerypropertiestocolumn/fieldnames">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 ac
tual 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 id="JAX-RSSearch-SearchBean">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><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[// ?_s="level=gt=10"
SearchCondition<SearchBean> sc = searchContext.getCondition(SearchBean.class);
Map\<, String\> fieldMap = new HashMap\<String, String\>();
@@ -402,21 +245,8 @@ assertEquals("SELECT LEVEL_COLUMN F
WHERE LEVEL_COLUMN > '10'",
visitor.getResult());
]]></script>
-</div></div>
-
-
-<h2 id="JAX-RSSearch-ConvertingFIQLqueries">Converting FIQL queries</h2>
-
-<p>SearchCondition can also be used to convert the search requirements (originally expressed in FIQL) into other query languages. <br clear="none">
-A custom <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/extensions/search/src/main/java/org/apache/cxf/jaxrs/ext/search/SearchConditionVisitor.java">SearchConditionVisitor</a> implementation can be used to convert SearchCondition objects into custom expressions or typed objects. CXF ships visitors for converting expressions to SQL, JPA 2.0 CriteriaQuery or TypedQuery, Lucene Query.</p>
-
-<h3 id="JAX-RSSearch-SQL">SQL</h3>
-
-<p>org.apache.cxf.jaxrs.ext.search.sql.SQLPrinterVisitor can be used for creating SQL expressions. For example: </p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-// ?_s="name==ami*;level=gt=10"
+</div></div><h2 id="JAX-RSSearch-ConvertingFIQLqueries">Converting FIQL queries</h2><p>SearchCondition can also be used to convert the search requirements (originally expressed in FIQL) into other query languages. <br clear="none"> A custom <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/extensions/search/src/main/java/org/apache/cxf/jaxrs/ext/search/SearchConditionVisitor.java">SearchConditionVisitor</a> implementation can be used to convert SearchCondition objects into custom expressions or typed objects. CXF ships visitors for converting expressions to SQL, JPA 2.0 CriteriaQuery or TypedQuery, Lucene Query.</p><h3 id="JAX-RSSearch-SQL">SQL</h3><p>org.apache.cxf.jaxrs.ext.search.sql.SQLPrinterVisitor can be used for creating SQL expressions. For example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[// ?_s="name==ami*;level=gt=10"
SearchCondition<Book> sc = searchContext.getCondition(Book.class);
SQLPrinterVisitor<Book> visitor = new SQLPrinterVisitor<Book>("table");
sc.accept(visitor);
@@ -427,13 +257,8 @@ assertEquals("SELECT * FROM table
level > '10'",
visitor.getResult());
]]></script>
-</div></div>
-
-<p>Note that SQLPrinterVisitor can also be initialized with the names of columns and the field aliases map:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-// ?_s="level=gt=10"
+</div></div><p>Note that SQLPrinterVisitor can also be initialized with the names of columns and the field aliases map:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[// ?_s="level=gt=10"
SearchCondition<Book> sc = searchContext.getCondition(Book.class);
Map<String, String> fieldMap = new HashMap<String, String>();
@@ -445,21 +270,8 @@ assertEquals("SELECT LEVEL_COLUMN F
WHERE LEVEL_COLUMN > '10'",
visitor.getResult());
]]></script>
-</div></div>
-
-<p>The fields map can help hide the names of the actual table columns/record fields from the Web frontend. Example, the users will know that the 'level' property is available while internally it will be converted to a LEVEL_COLUMN name.</p>
-
-<h3 id="JAX-RSSearch-JPA2.0">JPA 2.0</h3>
-
-<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, given:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-
-public class Book {
+</div></div><p>The fields map can help hide the names of the actual table columns/record fields from the Web frontend. Example, the users will know that the 'level' property is available while internally it will be converted to a LEVEL_COLUMN name.</p><h3 id="JAX-RSSearch-JPA2.0">JPA 2.0</h3><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, given:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[public class Book {
private String title;
private Date date;
@@ -491,13 +303,8 @@ public class Address {
]]></script>
-</div></div>
-
-<p>the following code can be used:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-import javax.persistence.EntityManager;
+</div></div><p>the following code can be used:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[import javax.persistence.EntityManager;
import javax.persistence.TypedQuery;
// init EntityManager as required
@@ -523,14 +330,8 @@ sc.accept(visitor);
TypedQuery<Book> typedQuery = visitor.getQuery();
List<Book> books = typedQuery.getResultList();
]]></script>
-</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 pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-
-// Find the books owned by Barry who lives in London, published starting from the first month of 2000
+</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 pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[// Find the books owned by Barry who lives in London, published starting from the first month of 2000
// ?_s="date=ge=2000-01-01;ownername=barry;address=london"
// this map will have to be set as a contextual property on the jaxrs endpoint
@@ -563,20 +364,8 @@ for (Tuple tuple : tuples) {
}
]]></script>
-</div></div>
-
-
-
-<p>Note that JPACriteriaQueryVisitor will automatically set aliases for an expression like "tuple.get('id', String.class)" to work.<br clear="none">
-JPACriteriaQueryVisitor will be enhanced to support more of JPA2 advanced constructs in time.</p>
-
-
-<p>Or, instead of using Tuple, use a capturing bean like BeanInfo:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-
-public static class BookInfo {
+</div></div><p>Note that JPACriteriaQueryVisitor will automatically set aliases for an expression like "tuple.get('id', String.class)" to work.<br clear="none"> JPACriteriaQueryVisitor will be enhanced to support more of JPA2 advanced constructs in time.</p><p>Or, instead of using Tuple, use a capturing bean like BeanInfo:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[public static class BookInfo {
private int id;
private String title;
@@ -611,14 +400,8 @@ List<BookInfo> bookInfo = typedQue
return bookInfo;
]]></script>
-</div></div>
-
-<p>JPA2 typed converters also support join operations in cases when explicit collections are used, for example, given:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-
-@Entity(name = "Book")
+</div></div><p>JPA2 typed converters also support join operations in cases when explicit collections are used, for example, given:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[@Entity(name = "Book")
public class Book {
private List<BookReview> reviews = new LinkedList<BookReview>();
@@ -684,14 +467,8 @@ public class BookReview {
}
]]></script>
-</div></div>
-
-<p>the following will find "all the books with good reviews written by Ted":</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-
-SearchCondition<Book> filter = new FiqlParser<Book>(Book.class).parse("reviews.review==good;reviews.authors==Ted");
+</div></div><p>the following will find "all the books with good reviews written by Ted":</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[SearchCondition<Book> filter = new FiqlParser<Book>(Book.class).parse("reviews.review==good;reviews.authors==Ted");
// in practice, map "reviews.review" to "review", "reviews.authors" to "reviewAuthor"
// and have a simple query like "review==good;reviewAuthor==Ted" instead
@@ -701,54 +478,20 @@ TypedQuery<Book> query = jpa.getQu
return query.getResultList();
]]></script>
-</div></div>
-
-
-<p>org.apache.cxf.jaxrs.ext.search.jpa.JPALanguageVisitor for converting FIQL expressions into JPQL expressions have also been introduced.</p>
-
-<h4 id="JAX-RSSearch-Countexpressions">Count expressions</h4>
-
-<p>Count expressions are supported at the two levels, </p>
-
-<p>First, one may want to get the count of records matching a given search expression, this actually can be done by checking the size of the result list:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-TypedQuery<Book> query = jpa.getQuery();
+</div></div><p>org.apache.cxf.jaxrs.ext.search.jpa.JPALanguageVisitor for converting FIQL expressions into JPQL expressions have also been introduced.</p><h4 id="JAX-RSSearch-Countexpressions">Count expressions</h4><p>Count expressions are supported at the two levels,</p><p>First, one may want to get the count of records matching a given search expression, this actually can be done by checking the size of the result list:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[TypedQuery<Book> query = jpa.getQuery();
return query.getResultList().size();
]]></script>
-</div></div>
-
-<p>However this can be very inefficient for large number of records, so using a CriteriaBuilder count operation is recommended, for example:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-
-SearchCondition<Book> filter = new FiqlParser<Book>(Book.class).parse("reviews.review==good;reviews.authors==Ted");
+</div></div><p>However this can be very inefficient for large number of records, so using a CriteriaBuilder count operation is recommended, for example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[SearchCondition<Book> filter = new FiqlParser<Book>(Book.class).parse("reviews.review==good;reviews.authors==Ted");
JPACriteriaQueryVisitor<Book, Long> jpa = new JPACriteriaQueryVisitor<Book, Long>(em, Book.class, Long.class);
filter.accept(jpa);
long count = jpa.count();
]]></script>
-</div></div>
-
-<p>Second, one may want to find say all the books written by at least two authors or all the books with no reviews.<br clear="none">
-If a collection entity such as BookReview has a non primitive type, then typing "reviews==0" is all what is needed, otherwise a count extension needs to be used, for example: "count(authors)=ge=2" </p>
-
-
-<h3 id="JAX-RSSearch-Lucene">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 pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-import org.apache.lucene.search.Query;
+</div></div><p>Second, one may want to find say all the books written by at least two authors or all the books with no reviews.<br clear="none"> If a collection entity such as BookReview has a non primitive type, then typing "reviews==0" is all what is needed, otherwise a count extension needs to be used, for example: "count(authors)=ge=2"</p><h3 id="JAX-RSSearch-Lucene">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 pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[import org.apache.lucene.search.Query;
SearchCondition<SearchBean> filter = new FiqlParser<SearchBean>(SearchBean.class).parse("ct==text");
LuceneQueryVisitor<SearchBean> lucene = new LuceneQueryVisitor<SearchBean>("ct", "contents");
@@ -756,51 +499,15 @@ lucene.visit(filter);
org.apache.lucene.search.Query termQuery = lucene.getQuery();
// use Query
]]></script>
-</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 pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-
-SearchCondition<SearchBean> filter = new FiqlParser<SearchBean>(SearchBean.class).parse("name==Fred");
+</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 pdl" style="border-width
: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[SearchCondition<SearchBean> filter = new FiqlParser<SearchBean>(SearchBean.class).parse("name==Fred");
LuceneQueryVisitor<SearchBean> lucene = new LuceneQueryVisitor<SearchBean>("contents");
lucene.visit(filter);
org.apache.lucene.search.Query phraseQuery = lucene.getQuery();
// use query
]]></script>
-</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 id="JAX-RSSearch-LDAP">LDAP</h3>
-
-<p>Mapping of FIQL expressions to LDAP queries as defined by <a shape="rect" class="external-link" href="http://tools.ietf.org/html/rfc4515" rel="nofollow">RFC-4515</a> is supported starting from CXF 2.7.1 with the help of org.apache.cxf.jaxrs.ext.search.ldap.LdapQueryVisitor. Use this visitor when working with LDAP or OSGI.</p>
-
-<p>Here is a summary of LDAP filter operators:</p>
-
-<div class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh"><p> Operator </p></th><th colspan="1" rowspan="1" class="confluenceTh"><p> Description </p></th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> "=" </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> Equal </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> "!" </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> Not Equal </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> "<=" </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> Less Or Equal </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> ">=" </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> Greater or Equal </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> "&" </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> AND </p></td></tr><tr><td colspan="1" rowspan="1" c
lass="confluenceTd"><p> "|" </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> OR </p></td></tr></tbody></table></div>
-
-
-<p>FIQL "=le=" and "=lt=" will both map to "<=", while "=ge=" and "=gt=" to ">=".</p>
-
-<p>For example:</p>
-
-<div class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh"><p> FIQL </p></th><th colspan="1" rowspan="1" class="confluenceTh"><p> LDAP </p></th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> "name==bar*" </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> "(name=bar*)" </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> "name!=bar" </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> "(!name=bar)" </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> "name!=bar;id=gt=10" </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> "(&(!name=bar)(id>=10))" </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> "name!=bar;(id=gt=10,id=lt=5)" </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> "(&(!name=bar)(|(id>=10)(id<=5)))" </p></td></tr></tbody></table></div>
-
-
-<p>The converter is created like all other converters:</p>
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-
-// FIQL "oclass=Bar"
+</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 id="JAX-RSSearch-LDAP">LDAP</h3><p>Mapping of FIQL expressions to LDAP queries as defined by <a shape="rect" class="external-link" href="http://tools.ietf.org/html/rfc4515" rel="nofollow">RFC-4515</a> is supported starting from CXF 2.7.1 with the help of org.apache.cxf.jaxrs.ext.search.ldap.LdapQueryVisitor. Use this visitor when working with LDAP or OSGI.</p><p>Here is a summary of LDAP filter operators:</p><div class="table-wrap"><table class="confluenceTable"><tbody><tr><th cols
pan="1" rowspan="1" class="confluenceTh"><p>Operator</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>Description</p></th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>"="</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Equal</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>"!"</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Not Equal</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>"<="</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Less Or Equal</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>">="</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Greater or Equal</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>"&"</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>AND</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>"|"</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>OR</p></td>
</tr></tbody></table></div><p>FIQL "=le=" and "=lt=" will both map to "<=", while "=ge=" and "=gt=" to ">=".</p><p>For example:</p><div class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh"><p>FIQL</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>LDAP</p></th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>"name==bar*"</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>"(name=bar*)"</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>"name!=bar"</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>"(!name=bar)"</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>"name!=bar;id=gt=10"</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>"(&(!name=bar)(id>=10))"</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>"name!=bar;(id=gt=10,id=lt=5)"</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>"(&(!name=bar)(
|(id>=10)(id<=5)))"</p></td></tr></tbody></table></div><p>The converter is created like all other converters:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[// FIQL "oclass=Bar"
// map 'oclass' used in the FIQL query to the actual property name, 'objectClass'
LdapQueryVisitor<Condition> visitor =
@@ -810,17 +517,8 @@ filter.accept(visitor.visitor());
String ldap = visitor.getQuery();
]]></script>
-</div></div>
-
-<h3 id="JAX-RSSearch-Customvisitors">Custom visitors</h3>
-
-<p>In cases when a custom conversion has to be done, a converter for doing the untyped (example, SQL) or typed (example, JPA2 TypedQuery) conversions can be provided. </p>
-
-<h4 id="JAX-RSSearch-Untypedconverters">Untyped converters</h4>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-public class CustomSQLVisitor<T> extends AbstractSearchConditionVisitor<T, String> {
+</div></div><h3 id="JAX-RSSearch-Customvisitors">Custom visitors</h3><p>In cases when a custom conversion has to be done, a converter for doing the untyped (example, SQL) or typed (example, JPA2 TypedQuery) conversions can be provided.</p><h4 id="JAX-RSSearch-Untypedconverters">Untyped converters</h4><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[public class CustomSQLVisitor<T> extends AbstractSearchConditionVisitor<T, String> {
private String tableName;
private StringBuilder sb = new StringBuilder();
@@ -856,15 +554,8 @@ public void visit(SearchCondition<T&g
}
}
]]></script>
-</div></div>
-
-<h4 id="JAX-RSSearch-Typedconverters">Typed converters</h4>
-
-<p>import org.custom.search.Query;</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-public class CustomTypedVisitor<T> extends AbstractSearchConditionVisitor<T, Query> {
+</div></div><h4 id="JAX-RSSearch-Typedconverters">Typed converters</h4><p>import org.custom.search.Query;</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[public class CustomTypedVisitor<T> extends AbstractSearchConditionVisitor<T, Query> {
private Stack<List<Query>> queryStack = new Stack<List<Query>>();
@@ -899,17 +590,8 @@ public void visit(SearchCondition<T&g
}
}
]]></script>
-</div></div>
-
-
-<h4 id="JAX-RSSearch-Customparsing">Custom parsing</h4>
-
-<p>If needed you can access a FIQL query directly and delegate it further to your own custom FIQL handler:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-
-@Path("/search")
+</div></div><h4 id="JAX-RSSearch-Customparsing">Custom parsing</h4><p>If needed you can access a FIQL query directly and delegate it further to your own custom FIQL handler:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[@Path("/search")
public class SearchEngine {
@Context
private UriInfo ui;
@@ -925,17 +607,8 @@ public class SearchEngine {
}
]]></script>
-</div></div>
-
-<h2 id="JAX-RSSearch-ConvertingFIQLquerieswithQueryContext">Converting FIQL queries with QueryContext</h2>
-
-<p><a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/extensions/search/src/main/java/org/apache/cxf/jaxrs/ext/search/QueryContext.java">QueryContext</a> 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 pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-import java.util.ArrayList;
+</div></div><h2 id="JAX-RSSearch-ConvertingFIQLquerieswithQueryContext">Converting FIQL queries with QueryContext</h2><p><a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/extensions/search/src/main/java/org/apache/cxf/jaxrs/ext/search/QueryContext.java">QueryContext</a> 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 pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[import java.util.ArrayList;
import java.util.List;
import org.apache.cxf.jaxrs.JAXRSServerFactoryBean;
import org.apache.cxf.jaxrs.ext.search.QueryContextProvider;
@@ -959,13 +632,8 @@ sf.getProperties(true).put("search.
sf.setResourceClasses(BookStore.class);
server = sf.create();
]]></script>
-</div></div>
-
-<p>and convert the queries:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-@Path("/")
+</div></div><p>and convert the queries:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[@Path("/")
public class BookStore {
@GET
@Path("/books/{expression}")
@@ -978,32 +646,14 @@ public class BookStore {
}
}
]]></script>
-</div></div>
-
-<p>where the client code may look like this:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-String address = "http://localhost:8080/bookstore/books/id=ge=123";
+</div></div><p>where the client code may look like this:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[String address = "http://localhost:8080/bookstore/books/id=ge=123";
WebClient client = WebClient.create(address);
client.accept("application/xml");
List<Book> books = client.getCollection(Book.class);
]]></script>
-</div></div>
-
-<p>Note, given that SQLPrinterVisitor will be shared between multiple requests it has to be made thread-safe by injecting a thread-local<br clear="none">
-org.apache.cxf.jaxrs.ext.search.visitor.SBThrealLocalVisitorState. This is not required when the visitor is created in the code on the per-request basis.</p>
-
-<p>Custom visitors which are expected to be singletons and have the state accumulating between multiple visit calls have to be thread safe. Utility org.apache.cxf.jaxrs.ext.search.visitor.ThrealLocalVisitorState class can be used.</p>
-
-<h2 id="JAX-RSSearch-PlainqueriestoFIQLconversion">Plain queries to FIQL conversion</h2>
-
-<p>If you'd like to generalize the processing of search queries and use FIQL visitors, you may want to consider setting up a contextual property "search.use.plain.queries" to "true" and get the plain query expressions converted to FIQL expressions internally. </p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-
-// GET /search?a=a1&a=v2
+</div></div><p>Note, given that SQLPrinterVisitor will be shared between multiple requests it has to be made thread-safe by injecting a thread-local<br clear="none"> org.apache.cxf.jaxrs.ext.search.visitor.SBThrealLocalVisitorState. This is not required when the visitor is created in the code on the per-request basis.</p><p>Custom visitors which are expected to be singletons and have the state accumulating between multiple visit calls have to be thread safe. Utility org.apache.cxf.jaxrs.ext.search.visitor.ThrealLocalVisitorState class can be used.</p><h2 id="JAX-RSSearch-PlainqueriestoFIQLconversion">Plain queries to FIQL conversion</h2><p>If you'd like to generalize the processing of search queries and use FIQL visitors, you may want to consider setting up a contextual property "search.use.plain.queries" to "true" and get the plain query expressions converted to FIQL expressions internally.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelConte
nt pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[// GET /search?a=a1&a=v2
String exp = searchContext.getSearchExpression();
assertEquals("(a==a1,a==a2)", exp);
@@ -1012,38 +662,16 @@ exp = searchContext.getSearchExpression(
assertEquals("(a==a1;b==b1)", exp);
]]></script>
-</div></div>
-
-<p>Also, by default, if a query property name ends with "From" then "=ge=" (greater or equals to) will be used, and if ends with "Till" then "=lt=" will be used, for example:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-
-// GET /search?ageFrom=10&ageTill=20
+</div></div><p>Also, by default, if a query property name ends with "From" then "=ge=" (greater or equals to) will be used, and if ends with "Till" then "=lt=" will be used, for example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[// GET /search?ageFrom=10&ageTill=20
String exp = searchContext.getSearchExpression();
assertEquals("(age=ge=10,age=le=20)", exp);
]]></script>
-</div></div>
-
-<p>This can allow the plain query expressions mapped to typed bean properties and further used with all the existing converters.</p>
-
-<h2 id="JAX-RSSearch-SearchExpressionsinURIPathsegments">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">
-For example, "find all the books with an 'id' property value less than 123":</p>
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[
-GET /books?_s=id=lt=123
+</div></div><p>This can allow the plain query expressions mapped to typed bean properties and further used with all the existing converters.</p><h2 id="JAX-RSSearch-SearchExpressionsinURIPathsegments">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"> For example, "find all the books with an 'id' property value less than 123":</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[GET /books?_s=id=lt=123
]]></script>
-</div></div>
-
-<p>Starting from CXF 2.6.2, it is possible to work with FIQL expressions included in URI path segments, for example, the same query can be expressed<br clear="none">
-in a number of ways:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[
-
-GET /books/id=lt=123
+</div></div><p>Starting from CXF 2.6.2, it is possible to work with FIQL expressions included in URI path segments, for example, the same query can be expressed<br clear="none"> in a number of ways:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[GET /books/id=lt=123
GET /books[id=lt=123]
GET /books(id=lt=123)
GET /books;id=lt=123
@@ -1051,12 +679,8 @@ GET /books;id=lt=123
//etc, etc
]]></script>
-</div></div>
-
-<p>Such expressions can be captured in the code using JAX-RS annotations:</p>
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-@Path("search")
+</div></div><p>Such expressions can be captured in the code using JAX-RS annotations:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[@Path("search")
public class BooksResource {
@Context
private SearchContext context;
@@ -1102,21 +726,8 @@ public class BooksResource {
}
]]></script>
-</div></div>
-
-<p>Note that if you have an expression added to a URI path segment with a ";" character acting as a separator, example, "/books;id=lt=123",<br clear="none">
-or if an expression itself includes ";", example, "/books[id=lt=123;id=gt=300]" ("find all the books with id less than 123 or greater than 300") <br clear="none">
-then a boolean contextual property "ignore.matrix.parameters" has to be set to "true" for the runtime to avoid splitting the path segment into the path value and matrix parameters.</p>
-
-<h2 id="JAX-RSSearch-Queriesinvolvingmultipleentities">Queries involving multiple entities</h2>
-
-<h3 id="JAX-RSSearch-Basicqueries">Basic queries</h3>
-
-<p>Consider the query like "find chapters with a given chapter id from all the books with 'id' less than 123".<br clear="none">
-One easy way to manage such queries is to make FIQL and JAX-RS work together. For example: </p>
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-@Path("search")
+</div></div><p>Note that if you have an expression added to a URI path segment with a ";" character acting as a separator, example, "/books;id=lt=123",<br clear="none"> or if an expression itself includes ";", example, "/books[id=lt=123;id=gt=300]" ("find all the books with id less than 123 or greater than 300") <br clear="none"> then a boolean contextual property "ignore.matrix.parameters" has to be set to "true" for the runtime to avoid splitting the path segment into the path value and matrix parameters.</p><h2 id="JAX-RSSearch-Queriesinvolvingmultipleentities">Queries involving multiple entities</h2><h3 id="JAX-RSSearch-Basicqueries">Basic queries</h3><p>Consider the query like "find chapters with a given chapter id from all the books with 'id' less than 123".<br clear="none"> One easy way to manage such queries is to make FIQL and JAX-RS work together. For example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[@Path("search")
public class BooksResource {
@Context
private SearchContext context;
@@ -1148,19 +759,8 @@ public class BooksResource {
}
]]></script>
-</div></div>
-
-<h3 id="JAX-RSSearch-Complexqueries">Complex queries</h3>
-
-<p>In the previous section we had the properties of two entities, Book and Chapter, used in the query. The query was considered 'simple' because it was really only the simple book properties that were checked, and the only chapter property was a chapter id, assumed to be equal to a chapter list index. </p>
-
-<p>Consider "Find all the chapters with id less than 5 for all the books with id greater than 300".</p>
-
-<p>One way to handle is to follow the example from the previous section with few modifications: </p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-@Path("search")
+</div></div><h3 id="JAX-RSSearch-Complexqueries">Complex queries</h3><p>In the previous section we had the properties of two entities, Book and Chapter, used in the query. The query was considered 'simple' because it was really only the simple book properties that were checked, and the only chapter property was a chapter id, assumed to be equal to a chapter list index.</p><p>Consider "Find all the chapters with id less than 5 for all the books with id greater than 300".</p><p>One way to handle is to follow the example from the previous section with few modifications:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[@Path("search")
public class BooksResource {
@Context
private SearchContext context;
@@ -1194,16 +794,8 @@ public class BooksResource {
}
]]></script>
-</div></div>
-
-<p>In this case two conditions are created and the 2nd condition is used to filter the chapters from the books filtered by the 1st condition.</p>
-
-<p>Perhaps a simpler approach, especially in case of JPA2, is to start looking for Chapters immediately, assuming Chapter classes have a one to one bidirectional relationship with Book:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-
-public class Chapter {
+</div></div><p>In this case two conditions are created and the 2nd condition is used to filter the chapters from the books filtered by the 1st condition.</p><p>Perhaps a simpler approach, especially in case of JPA2, is to start looking for Chapters immediately, assuming Chapter classes have a one to one bidirectional relationship with Book:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[public class Chapter {
private int id;
private Book book;
@@ -1231,25 +823,8 @@ public class BooksResource {
}
]]></script>
-</div></div>
-
-<p>Note this code assumes that "bookId" is mapped to "Book.id" property with the help of the contextual "search.bean.property.map" property as explained earlier.</p>
-
-<h2 id="JAX-RSSearch-Validation">Validation</h2>
-
-<p>First option is to have a bean capturing specific property values do a domain specific validation. For example, a Book.class may have its setName(String name) method validating the name value. <br clear="none">
-Another option is to inject a custom <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/extensions/search/src/main/java/org/apache/cxf/jaxrs/ext/search/visitor/PropertyValidator.java">validator</a> into a visitor which is used to build the untyped or typed query.</p>
-
-<p>Finally, avoid letting users to use properties whose values which can not be well validated in the application code. Using a typed capturing bean like Book.class offers a perfect option to limit a number of supported properties to the ones known to be related to Books.</p>
-
-
-<h2 id="JAX-RSSearch-BuildingFIQLqueries">Building FIQL queries</h2>
-
-<p>CXF 2.4.0 introduces <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/ext/search/client/SearchConditionBuilder.java">SearchConditionBuilder</a> which makes it simpler to build FIQL queries. SearchConditionBuilder is an abstract class that returns a FIQL builder by default:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-SearchConditionBuilder b = SearchConditionBuilder.instance();
+</div></div><p>Note this code assumes that "bookId" is mapped to "Book.id" property with the help of the contextual "search.bean.property.map" property as explained earlier.</p><h2 id="JAX-RSSearch-Validation">Validation</h2><p>First option is to have a bean capturing specific property values do a domain specific validation. For example, a Book.class may have its setName(String name) method validating the name value. <br clear="none"> Another option is to inject a custom <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/extensions/search/src/main/java/org/apache/cxf/jaxrs/ext/search/visitor/PropertyValidator.java">validator</a> into a visitor which is used to build the untyped or typed query.</p><p>Finally, avoid letting users to use properties whose values which can not be well validated in the application code. Using a typed capturing bean like Book.class offers a perfect option to limit a number of supported properties to the ones known t
o be related to Books.</p><h2 id="JAX-RSSearch-BuildingFIQLqueries">Building FIQL queries</h2><p>CXF 2.4.0 introduces <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/ext/search/client/SearchConditionBuilder.java">SearchConditionBuilder</a> which makes it simpler to build FIQL queries. SearchConditionBuilder is an abstract class that returns a FIQL builder by default:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[SearchConditionBuilder b = SearchConditionBuilder.instance();
String fiqlQuery = b.is("id").greaterThan(123).query();
WebClient wc = WebClient.create("http://books.com/search");
@@ -1257,13 +832,8 @@ wc.query("_s", fiqlQuery);
// find all the books with id greater than 123
Collection books = wc.getCollection(Book.class);
]]></script>
-</div></div>
-
-<p>Here is an example of building more complex queries:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-// OR condition
+</div></div><p>Here is an example of building more complex queries:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[// OR condition
String ret = b.is("foo").greaterThan(20).or().is("foo").lessThan(10).query();
assertEquals("foo=gt=20,foo=lt=10", ret);
@@ -1277,23 +847,13 @@ String ret = b.is("foo").equal
b.is("baz").lessThan(20)).query();
assertEquals("foo==123.4,(bar==asadf*;baz=lt=20.0)", ret);
]]></script>
-</div></div>
-
-<p>Note, starting from CXF 2.7.1 the following can be used to make connecting multiple primitive expressions simpler:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-// AND condition, '.and("bar")' is a shortcut for "and().is("bar")", similar shortcut is supported for 'or'
+</div></div><p>Note, starting from CXF 2.7.1 the following can be used to make connecting multiple primitive expressions simpler:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[// AND condition, '.and("bar")' is a shortcut for "and().is("bar")", similar shortcut is supported for 'or'
String ret = b.is("foo").greaterThan(20).and("bar").equalTo("plonk").query();
assertEquals("foo=gt=20;bar==plonk", ret);
]]></script>
-</div></div>
-
-<p>More updates to the builder API are available on the trunk:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-// OR condition
+</div></div><p>More updates to the builder API are available on the trunk:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[// OR condition
String ret = b.is("foo").equalTo(20).or().is("foo").equalTo(10).query();
assertEquals("foo==20,foo==10", ret);
@@ -1301,13 +861,8 @@ assertEquals("foo==20,foo==10"
String ret = b.is("foo").equalTo(20, 10).query();
assertEquals("foo==20,foo==10", ret);
]]></script>
-</div></div>
-
-<p>and</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-// Connecting composite or() and and() expressions will add "()" implicitly:
[... 61 lines stripped ...]