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">