Author: buildbot
Date: Fri Nov 7 10:47:47 2014
New Revision: 928263
Log:
Production update by buildbot for cxf
Modified:
websites/production/cxf/content/cache/docs.pageCache
websites/production/cxf/content/docs/jax-rs-oauth2.html
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-oauth2.html
==============================================================================
--- websites/production/cxf/content/docs/jax-rs-oauth2.html (original)
+++ websites/production/cxf/content/docs/jax-rs-oauth2.html Fri Nov 7 10:47:47
2014
@@ -118,11 +118,11 @@ Apache CXF -- JAX-RS OAuth2
<!-- Content -->
<div class="wiki-content">
<div id="ConfluenceContent"><h1 id="JAX-RSOAuth2-JAX-RS:OAuth2">JAX-RS:
OAuth2</h1><p><style type="text/css">/*<![CDATA[*/
-div.rbtoc1408538785810 {padding: 0px;}
-div.rbtoc1408538785810 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1408538785810 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1415357218365 {padding: 0px;}
+div.rbtoc1415357218365 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1415357218365 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1408538785810">
+/*]]>*/</style></p><div class="toc-macro rbtoc1415357218365">
<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RSOAuth2-JAX-RS:OAuth2">JAX-RS: OAuth2</a></li><li><a shape="rect"
href="#JAX-RSOAuth2-Introduction">Introduction</a></li><li><a shape="rect"
href="#JAX-RSOAuth2-Mavendependencies">Maven dependencies</a></li><li><a
shape="rect" href="#JAX-RSOAuth2-ClientRegistration">Client
Registration</a></li><li><a shape="rect"
href="#JAX-RSOAuth2-DevelopingOAuth2Servers">Developing OAuth2 Servers</a>
<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RSOAuth2-AuthorizationService">Authorization Service</a>
<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RSOAuth2-EndUserNameinAuthorizationForm">EndUser Name in
Authorization Form</a></li><li><a shape="rect"
href="#JAX-RSOAuth2-PublicClients(Devices)">Public Clients (Devices)</a>
@@ -413,7 +413,7 @@ ModelEncryptionSupport.decryptAccessToke
</jaxrs:serviceBeans>
</jaxrs:server>
]]></script>
-</div></div><p>AuthorizationCodeGrantService listens on a relative
"/authorize" path so in this case its absolute address will be something like
"http://localhost:8080/services/myapp/authorize";. This address and that of
AccessTokenService will be used by third-party clients.</p><h1
id="JAX-RSOAuth2-ThirdPartyClientAuthentication">Third Party Client
Authentication</h1><p>When a client requests a token from Access Token Service,
it needs to get authenticated. Providing its client_id and client secret as
part of Basic Authorization scheme or posting them directly as form parameters
are typical options, however other authentication schemes can be supported if
required.</p><p>For example, using client certificates or assertions like SAML2
Bearer or JWT is all acceptable - the only additional requirement in this case
is that a given security filter processing a specific authentication scheme
maps the client credentials to an actual client_id - CXF Access Token Service
will check a "client
_id" property on the current message context as the last resort.</p><p>Please
see <a shape="rect" href="jaxrs-oauth2-assertions.html">JAXRS OAuth2
Assertions</a> section for more information on how it may work.</p><h1
id="JAX-RSOAuth2-UserSessionAuthenticity">User Session
Authenticity</h1><p>Redirection-based Authorization Code and Implicit flows
depend on end users signing in if needed during the initial redirection,
challenged with the client authorization form and returning their decision. By
default, CXF will enforce the user session authenticity by keeping the session
state in a servlet container's HTTPSession. If the alternative storage is
preferred then you can register a new <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/provider/SessionAuthenticityTokenProvider.java";>SessionAuthenticityTokenProvider</a>
(available from CXF 2.6.4) with either Authorizatio
nCodeGrantService or ImplicitGrantService beans.</p><h1
id="JAX-RSOAuth2-CustomizingEndUserSubjectinitialization">Customizing End User
Subject initialization</h1><p>By default, redirection based authorization
services will the the current CXF SecurityContext to initialize a subject
representing the authenticated resource owner/end user. If the customization if
needed: custom CXF filter can be used to create UserSubject and set it on the
message or org.apache.cxf.rs.security.oauth2.provider.SubjectCreator interface
implementation can be registered with either AuthorizationCodeGrantService or
ImplicitGrantService.</p><h1
id="JAX-RSOAuth2-ProtectingresourceswithOAuthfilters">Protecting resources with
OAuth filters</h1><p><a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/filters/OAuthRequestFilter.java";>OAuthRequestFilter</a>
request handler can be used to protect the r
esource server when processing the requests from the third-party clients. Add
it as a jaxrs:provider to the endpoint which deals with the clients requesting
the resources.</p><p>When checking a request like this:</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>AuthorizationCodeGrantService listens on a relative
"/authorize" path so in this case its absolute address will be something like
"http://localhost:8080/services/myapp/authorize";. This address and that of
AccessTokenService will be used by third-party clients.</p><h1
id="JAX-RSOAuth2-ThirdPartyClientAuthentication">Third Party Client
Authentication</h1><p>When a client requests a token from Access Token Service,
it needs to get authenticated. Providing its client_id and client secret as
part of Basic Authorization scheme or posting them directly as form parameters
are typical options, however other authentication schemes can easily be
supported if required.</p><p>For example, using client certificates or
assertions like SAML2 Bearer or JWT is all acceptable - the only additional
requirement in this case is that a given security filter processing a specific
authentication scheme maps the client credentials to an actual client_id - CXF
Access Token Service will check a
"client_id" property on the current message context as the last resort. Note
that org.apache.cxf.rs.security.oauth2.provider.ClientIdProvider can be
registered with AccessTokenService to facilitate the mapping between an
authenticated client and its id expected by the data provider if the container
or filter based authentication can not set a "client_id" contextual
property.</p><p>If a Basic authentication scheme is used and neither the
container or filter has authenticated the client AccessTokenService will
request a Client from the data provider and compare the Client's secret against
the password found in the Basic scheme data.
org.apache.cxf.rs.security.oauth2.provider.ClientSecretVerifier is available
starting from CXF 3.0.3 to support Clients saving only password hashes. Its
org.apache.cxf.rs.security.oauth2.provider.ClientSecretHashVerifier (calculates
a SHA-256 password hash and compares it with the Client's secret) or custom
implementations can be registered with AccessToke
nService.</p><p>If a 2-way TLS is sued to authenticate a client and Client has
a Base64 encoded representations of its X509Certificates available in its
"applicationCertificates" property then AccessTokenService will do the
additional comparison of these certificates against the ones available in the
current TLS session.</p><p> </p><p>Please see <a shape="rect"
href="jaxrs-oauth2-assertions.html">JAXRS OAuth2 Assertions</a> section for
more information on how it may work.</p><p> </p><h1
id="JAX-RSOAuth2-UserSessionAuthenticity">User Session
Authenticity</h1><p>Redirection-based Authorization Code and Implicit flows
depend on end users signing in if needed during the initial redirection,
challenged with the client authorization form and returning their decision. By
default, CXF will enforce the user session authenticity by keeping the session
state in a servlet container's HTTPSession. If the alternative storage is
preferred then you can register a new <a shape="rect" class
="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/provider/SessionAuthenticityTokenProvider.java";>SessionAuthenticityTokenProvider</a>
(available from CXF 2.6.4) with either AuthorizationCodeGrantService or
ImplicitGrantService beans.</p><h1
id="JAX-RSOAuth2-CustomizingEndUserSubjectinitialization">Customizing End User
Subject initialization</h1><p>By default, redirection based authorization
services will the the current CXF SecurityContext to initialize a subject
representing the authenticated resource owner/end user. If the customization if
needed: custom CXF filter can be used to create UserSubject and set it on the
message or org.apache.cxf.rs.security.oauth2.provider.SubjectCreator interface
implementation can be registered with either AuthorizationCodeGrantService or
ImplicitGrantService.</p><h1
id="JAX-RSOAuth2-ProtectingresourceswithOAuthfilters">Protecting resources with
OAuth
filters</h1><p><a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/filters/OAuthRequestFilter.java";>OAuthRequestFilter</a>
request handler can be used to protect the resource server when processing the
requests from the third-party clients. Add it as a jaxrs:provider to the
endpoint which deals with the clients requesting the resources.</p><p>When
checking a request like this:</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[Address:
http://localhost:8080/services/thirdPartyAccess/calendar
Http-Method: GET
Headers:
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 Fri Nov 7 10:47:47
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.rbtoc1413819985865 {padding: 0px;}
-div.rbtoc1413819985865 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1413819985865 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1415357220402 {padding: 0px;}
+div.rbtoc1415357220402 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1415357220402 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1413819985865">
+/*]]>*/</style></p><div class="toc-macro rbtoc1415357220402">
<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>
@@ -137,8 +137,10 @@ div.rbtoc1413819985865 li {margin-left:
</li><li><a shape="rect"
href="#JAX-RSSearch-ConvertingthequerieswithQueryContext">Converting the
queries with QueryContext</a></li><li><a shape="rect"
href="#JAX-RSSearch-PlainqueriestoFIQLconversion">Plain queries to FIQL
conversion</a></li><li><a shape="rect"
href="#JAX-RSSearch-SearchExpressionsinURIPathsegments">Search Expressions in
URI Path segments</a></li><li><a shape="rect"
href="#JAX-RSSearch-Queriesinvolvingmultipleentities">Queries involving
multiple entities</a>
<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-Buildingthequeries">Building the queries</a>
-<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RSSearch-FIQL">FIQL</a></li><li><a shape="rect"
href="#JAX-RSSearch-OData">OData</a></li></ul>
-</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><li><a shape="rect"
href="#JAX-RSSearch-ContentExtraction">Content Extraction</a>
+<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RSSearch-FIQL">FIQL</a></li></ul>
+</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>
+<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RSSearch-OData">OData</a></li></ul>
+</li><li><a shape="rect" href="#JAX-RSSearch-ContentExtraction">Content
Extraction</a>
<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RSSearch-UsingTikaContentExtractor">Using TikaContentExtractor</a></li><li><a
shape="rect"
href="#JAX-RSSearch-UsingTikaLuceneContentExtractor">Using TikaLuceneContentExtractor</a></li></ul>
</li></ul>
</li></ul>
@@ -158,19 +160,7 @@ div.rbtoc1413819985865 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> </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>And here is also an XML Spring configuration example (using
SearchBean in this specific case):</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[ <cxf:bus>
- <cxf:properties>
- <entry key="search.query.parameter.name"
value="$filter" />
- <entry key="search.parser">
- <bean
class="org.apache.cxf.jaxrs.ext.search.odata.ODataParser">
- <constructor-arg value="#{
T(org.apache.cxf.jaxrs.ext.search.SearchBean) }" />
- Â </bean>
- </entry>
- </cxf:properties>
-</cxf:bus>
-Â ]]></script>
-</div></div><p> </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, ty
pically 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
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">
+</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><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 expressi
ons 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 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>
@@ -919,7 +909,7 @@ assertEquals("(foo==20;bar=lt=10),b
]]></script>
-</div></div><h3 id="JAX-RSSearch-OData">OData</h3><p> </p><p>Please work
with <a shape="rect" class="external-link"
href="http://olingo.incubator.apache.org/";>Apache Olingo</a> to produce OData
queries from the code.</p><h2 id="JAX-RSSearch-Usingdatesinqueries">Using dates
in queries</h2><p>By default, the date values have to have the following <a
shape="rect" class="external-link"
href="http://download.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html";
rel="nofollow">format</a>: "yyyy-MM-dd", for example:</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p> </p><h2 id="JAX-RSSearch-Usingdatesinqueries">Using dates
in queries</h2><p>By default, the date values have to have the following <a
shape="rect" class="external-link"
href="http://download.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html";
rel="nofollow">format</a>: "yyyy-MM-dd", 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[?_search=date=le=2010-03-11
]]></script>
</div></div><p>A custom date format can be supported. Use "search.date-format"
contextual property, example, "search.date-format"="yyyy-MM-dd'T'HH:mm:ss" will
let users type:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
@@ -937,7 +927,19 @@ FiqlSearchConditionBuilder bCustom = new
String ret = bCustom.is("foo").equalTo(d).query();
assertEquals("foo==2011-03-01T12:34:00", ret);
]]></script>
-</div></div><h2 id="JAX-RSSearch-Alternativequerylanguages">Alternative query
languages</h2><p>Custom org.apache.cxf.jaxrs.ext.search.SearchConditionParser
implementations can be registered as a "search.parser" contextual property
starting from CXF 3.0.0-milestone2.</p><h2
id="JAX-RSSearch-ContentExtraction">Content Extraction</h2><p>Starting from CXF
3.0.2, the content extraction support has been added in order to complement the
search capabilites with text extraction from various document formats (PDF,
ODF, DOC,TXT,RTF,...). It is based on Apache Tika and is available in two
shapes: raw content extraction (TikaContentExtractor) and Lucene document
content extraction (TikaLuceneContentExtractor).</p><h3
id="JAX-RSSearch-UsingTikaContentExtractor">Using TikaContentExtractor</h3><p>The
purpose of Tika content extractor is to provide the essential support of text
extraction from supported document formats. Additionally, the metadata is being
extracted as well depending on the doc
ument format (author, modified, created, pages, ...). The TikaContentExtractor
accepts the list of supported parsers and returns the extracted metadata
together with the desired extracted content format (by default raw text). For
example:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
+</div></div><h2 id="JAX-RSSearch-Alternativequerylanguages">Alternative query
languages</h2><p>Custom org.apache.cxf.jaxrs.ext.search.SearchConditionParser
implementations can be registered as a "search.parser" contextual property
starting from CXF 3.0.0-milestone2.</p><h3
id="JAX-RSSearch-OData">OData</h3><p> </p><p>Please use a
"search.query.parameter.name" contextual property to indicate to the runtime
that an OData '$filter' query option needs 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 function.</p><p>And here is also an XML Spring
configuration example (using SearchBean in this specific case):</p><div
class="code panel pdl" style="border-widt
h: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: xml; gutter: false"
type="syntaxhighlighter"><![CDATA[ <cxf:bus>
+ <cxf:properties>
+ <entry key="search.query.parameter.name"
value="$filter" />
+ <entry key="search.parser">
+ <bean
class="org.apache.cxf.jaxrs.ext.search.odata.ODataParser">
+ <constructor-arg value="#{
T(org.apache.cxf.jaxrs.ext.search.SearchBean) }" />
+ Â </bean>
+ </entry>
+ </cxf:properties>
+</cxf:bus>
+Â ]]></script>
+</div></div><p> </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-ContentExtraction">Content
Extraction</h2><p>Starting from CXF 3.0.2, the content extraction support has
been added in order to complement the search capabilites with text extraction
from various document formats (PDF, ODF, DOC,TXT,RTF,...). It is based on
Apache Tika and is available in two shapes: raw content extraction
(TikaContentExtractor) and Lucene document content extraction
(TikaLuceneContentExtractor).</p><h3
id="JAX-RSSearch-UsingTikaContentExtractor">Using TikaContentExtractor</h3><p>The
purpose of Tika content extractor is to provide the essential support of text
extraction from supported document formats. Additionally, the metadata is being
extracted as well depending on the document format (author, modified, created,
pages, ...).
The TikaContentExtractor accepts the list of supported parsers and returns the
extracted metadata together with the desired extracted content format (by
default raw text). 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[TikaContentExtractor extractor = new
TikaContentExtractor(new PDFParser(), true);
TikaContent content = extractor .extract( Files.newInputStream( new File(
"testPDF.pdf" ).toPath() ) );]]></script>
</div></div><p>By default, the TikaContentExtractor  also performs the
content type detection and validation, which could be turned off using the
'validateMediaType' constructor argument.</p><h3
id="JAX-RSSearch-UsingTikaLuceneContentExtractor">Using TikaLuceneContentExtractor</h3><p>The
TikaLuceneContentExtractor is very similar to TikaContentExtractor but instead
of raw content and metadata it returns prepared Lucene document. However, in
order to properly create the Lucene document which is ready to be indexed,
TikaLuceneContentExtractor  accepts an additional parameter,
LuceneDocumentMetadata, with the field types and type converters. For
example:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
