cxf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r922451 - in /websites/production/cxf/content: cache/docs.pageCache docs/jax-rs-search.html
Date Tue, 16 Sep 2014 21:47:08 GMT
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>&#160;</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"><![CDATA[public
class Book {
 
     private int id;



Mime
View raw message