Author: buildbot
Date: Tue Sep 16 21:47:08 2014
New Revision: 922451
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 Sep 16 21:47:08
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.rbtoc1397238485730 {padding: 0px;}
-div.rbtoc1397238485730 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1397238485730 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1410904000555 {padding: 0px;}
+div.rbtoc1410904000555 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1410904000555 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1397238485730">
+/*]]>*/</style></p><div class="toc-macro rbtoc1410904000555">
<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>
@@ -204,7 +204,7 @@ 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-Capturingthequeries">Capturing the 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 h
as 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 propertie
s 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">
+</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-Capturingthequeries">Capturing the 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 h
as 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><p>Note that a "search.decode.values" property can be used to have
the 'reserved' characters such as FIQL ',' or ';' characters passed as
percent-encoded characters as part of
the search property values.</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 Bo
ok 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"><