cxf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r928263 - in /websites/production/cxf/content: cache/docs.pageCache docs/jax-rs-oauth2.html docs/jax-rs-search.html
Date Fri, 07 Nov 2014 10:47:47 GMT
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
   &lt;/jaxrs:serviceBeans&gt;
 &lt;/jaxrs:server&gt;
 ]]></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>&#160;</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>&#160;</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>&#160;</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&#160;TikaContentExtractor</a></li><li><a
shape="rect" href="#JAX-RSSearch-UsingTikaLuceneContentExtractor">Using&#160;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>&#160;</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[
&lt;cxf:bus&gt;
-  &lt;cxf:properties&gt;
-    &lt;entry key=&quot;search.query.parameter.name&quot; value=&quot;$filter&quot;
/&gt;
-    &lt;entry key=&quot;search.parser&quot;&gt;
-      &lt;bean class=&quot;org.apache.cxf.jaxrs.ext.search.odata.ODataParser&quot;&gt;
-         &lt;constructor-arg value=&quot;#{ T(org.apache.cxf.jaxrs.ext.search.SearchBean)
}&quot; /&gt;
-      &lt;/bean&gt;
-    &lt;/entry&gt;
-  &lt;/cxf:properties&gt;
-&lt;/cxf:bus&gt;
- ]]></script>
-</div></div><p>&#160;</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&amp;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>&#160;</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&amp;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[
  &lt;dependency&gt;
       &lt;groupId&gt;org.apache.cxf&lt;/groupId&gt;
       &lt;artifactId&gt;cxf-rt-rs-extension-search&lt;/artifactId&gt;
@@ -919,7 +909,7 @@ assertEquals(&quot;(foo==20;bar=lt=10),b
 
 
 ]]></script>
-</div></div><h3 id="JAX-RSSearch-OData">OData</h3><p>&#160;</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>&#160;</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(&quot;foo&quot;).equalTo(d).query();
 assertEquals(&quot;foo==2011-03-01T12:34:00&quot;, 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&#160;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>&#160;</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[
&lt;cxf:bus&gt;
+  &lt;cxf:properties&gt;
+    &lt;entry key=&quot;search.query.parameter.name&quot; value=&quot;$filter&quot;
/&gt;
+    &lt;entry key=&quot;search.parser&quot;&gt;
+      &lt;bean class=&quot;org.apache.cxf.jaxrs.ext.search.odata.ODataParser&quot;&gt;
+         &lt;constructor-arg value=&quot;#{ T(org.apache.cxf.jaxrs.ext.search.SearchBean)
}&quot; /&gt;
+      &lt;/bean&gt;
+    &lt;/entry&gt;
+  &lt;/cxf:properties&gt;
+&lt;/cxf:bus&gt;
+ ]]></script>
+</div></div><p>&#160;</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&#160;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( &quot;testPDF.pdf&quot;
).toPath() ) );]]></script>
 </div></div><p>By default, the TikaContentExtractor&#160; 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&#160;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&#160; 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">



Mime
View raw message