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 2014/02/18 20:48:18 UTC
svn commit: r898427 - in /websites/production/cxf/content:
cache/docs.pageCache docs/jax-rs-search.html
Author: buildbot
Date: Tue Feb 18 19:48:18 2014
New Revision: 898427
Log:
Production update by buildbot for cxf
Modified:
websites/production/cxf/content/cache/docs.pageCache
websites/production/cxf/content/docs/jax-rs-search.html
Modified: websites/production/cxf/content/cache/docs.pageCache
==============================================================================
Binary files - no diff available.
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 Tue Feb 18 19:48:18 2014
@@ -118,11 +118,11 @@ Apache CXF -- JAX-RS Search
<!-- Content -->
<div class="wiki-content">
<div id="ConfluenceContent"><h1 id="JAX-RSSearch-JAX-RSSearch">JAX-RS Search</h1><p> </p><p><style type="text/css">/*<![CDATA[*/
-div.rbtoc1392745678962 {padding: 0px;}
-div.rbtoc1392745678962 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1392745678962 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1392752871779 {padding: 0px;}
+div.rbtoc1392752871779 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1392752871779 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1392745678962">
+/*]]>*/</style></p><div class="toc-macro rbtoc1392752871779">
<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSSearch-JAX-RSSearch">JAX-RS Search</a>
<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSSearch-AdvancedSearchQueries">Advanced Search Queries</a></li><li><a shape="rect" href="#JAX-RSSearch-SupportedQueryLanguages">Supported Query Languages</a>
<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSSearch-FeedItemQueryLanguage">Feed Item Query Language</a></li><li><a shape="rect" href="#JAX-RSSearch-OpenDataProtocol">Open Data Protocol</a></li></ul>
@@ -156,14 +156,23 @@ div.rbtoc1392745678962 li {margin-left:
/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><h3 id="JAX-RSSearch-OpenDataProtocol">Open Data Protocol</h3><p>CXF 3.0.0-milestone2 supports the <a shape="rect" class="external-link" href="http://docs.oasis-open.org/odata/odata/v4.0/cos01/part2-url-conventions/odata-v4.0-cos01-part2-url-conventions.html#_Toc372793792" rel="nofollow">$filter</a> query defined as part of <a shape="rect" class="external-link" href="http://www.odata.org/" rel="nofollow">Open Data Protocol</a>, courtesy of <a shape="rect" class="external-link" href="http://olingo.incubator.apache.org/">Apache Olingo</a>.</p><p>The $filter query can have a number of the logical operator
s, here is a summary of the operators supported in scope of Search API:</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>"eq"</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Equal</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>"ne"</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>"and"</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>AND</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>"or"</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>OR</p></td></tr></tbody></table></div><p>Please note that OData protocol is not supported by CXF Search API, only the $filter query is supported for querying the application data with CXF Search API. Users should work directly with <a shape="rect" class="external-link" href="http://olingo.incubator.apache.org/">Apache Olingo</a> to get the <a shape="rect" class="external-link" href="http://www.odata.org/" rel="nofollow">OData</a> protocol supported as part of the application flow.</p><h2 id="JAX-RSSearch-Whentouseadvancedqueries.">When to use advanced queries.</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 or OData 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/OData and SearchCon
ditionVisitor 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">
+</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><h3 id="JAX-RSSearch-OpenDataProtocol">Open Data Protocol</h3><p>CXF 3.0.0-milestone2 supports the <a shape="rect" class="external-link" href="http://docs.oasis-open.org/odata/odata/v4.0/cos01/part2-url-conventions/odata-v4.0-cos01-part2-url-conventions.html#_Toc372793792" rel="nofollow">$filter</a> query defined as part of <a shape="rect" class="external-link" href="http://www.odata.org/" rel="nofollow">Open Data Protocol</a>, courtesy of <a shape="rect" class="external-link" href="http://olingo.incubator.apache.org/">Apache Olingo</a>.</p><p>The $filter query can have a number of the logical operator
s, here is a summary of the operators supported in scope of Search API:</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>"eq"</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Equal</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>"ne"</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>"and"</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>AND</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>"or"</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>OR</p></td></tr></tbody></table></div><p> </p><p>Please see the specification text for <a shape="rect" class="external-link" href="http://docs.oasis-open.org/odata/odata/v4.0/cos01/part2-url-conventions/odata-v4.0-cos01-part2-url-conventions.html#_Toc372793804" rel="nofollow">some examples</a>.</p><p>Please note that OData protocol is not supported by CXF Search API, only the $filter query is supported (only logical operators for now) for querying the application data with CXF Search API. Users should work directly with <a shape="rect" class="external-link" href
="http://olingo.incubator.apache.org/">Apache Olingo</a> to get the <a shape="rect" class="external-link" href="http://www.odata.org/" rel="nofollow">OData</a> protocol supported as part of the application flow.</p><p>Some of the following examples on this page may often refer to FIQL due to the fact FIQL has been supported for a long time, but the same examples will work with OData $filter expressions. For example, replace the "_s=name==CXF" query with "$filter=name eq CXF".</p><p>Please use a "search.query.parameter.name" contextual property to indicate to the runtime that a $filter query option need to be checked for the query expression and a "search.parser" property to point to the instance of org.apache.cxf.jaxrs.ext.search.odata.ODataParser, as shown in this <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/systests/jaxrs/src/test/java/org/apache/cxf/systest/jaxrs/JAXRSClientServerODataSearchTest.java">test</a>, see the startServers functio
n.</p><p>Also note that <a shape="rect" class="external-link" href="http://olingo.incubator.apache.org/">Apache Olingo</a> offers its own visitor model which can be used to work with JPA2, etc.</p><h2 id="JAX-RSSearch-Whentouseadvancedqueries.">When to use advanced queries.</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 or OData for capturing simple or medium complexity queries, typically in cases wh
ere 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/OData 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-Workingwiththequeries">Working with the queries</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/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/OData query. This SearchCondition can be used in a number of ways for finding the matching data.</p><p>In this section we assume that t
he data to be matched are already available in memory. The follow-up section on converting the queries will show how the 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">
+
+ <!-- If working with OData -->
+ <!--
+ <dependency>
+ <groupId>org.apache.olingo</groupId>
+ <artifactId>olingo-odata2-core-incubating</artifactId>
+ <version>1.1.0</version>
+ </dependency>
+ -->
+Â ]]></script>
+</div></div><p>Additionally, starting from 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-Workingwiththequeries">Working with the queries</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/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/OData query. This SearchCondition can be used in a number of ways for finding the matching data.</p><p>In this section we as
sume that the data to be matched are already available in memory. The follow-up section on converting the queries will show how the 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 {