You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cxf.apache.org by bu...@apache.org on 2012/11/01 14:47:36 UTC
svn commit: r836885 - in /websites/production/cxf/content:
cache/docs.pageCache docs/jax-rs-advanced-features.html
Author: buildbot
Date: Thu Nov 1 13:47:35 2012
New Revision: 836885
Log:
Production update by buildbot for cxf
Modified:
websites/production/cxf/content/cache/docs.pageCache
websites/production/cxf/content/docs/jax-rs-advanced-features.html
Modified: websites/production/cxf/content/cache/docs.pageCache
==============================================================================
Binary files - no diff available.
Modified: websites/production/cxf/content/docs/jax-rs-advanced-features.html
==============================================================================
--- websites/production/cxf/content/docs/jax-rs-advanced-features.html (original)
+++ websites/production/cxf/content/docs/jax-rs-advanced-features.html Thu Nov 1 13:47:35 2012
@@ -124,7 +124,7 @@ Apache CXF -- JAX-RS Advanced Features
<div id="ConfluenceContent"><p><span style="font-size:2em;font-weight:bold">JAX-RS : Advanced Features</span></p>
<div>
-<ul><li><a shape="rect" href="#JAX-RSAdvancedFeatures-JMSSupport">JMS Support</a></li><ul><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Endpoints">Endpoints</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Client">Client</a></li></ul><li><a shape="rect" href="#JAX-RSAdvancedFeatures-FIQLsearchqueries">FIQL search queries</a></li><ul><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Introduction">Introduction</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-DependenciesandConfiguration">Dependencies and Configuration</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-WorkingwithFIQLqueries">Working with FIQL queries</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-CapturingFIQLqueries">Capturing FIQL queries</a></li><ul><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Mappingofquerypropertiestobeanproperties">Mapping of query properties to bean properties</a></li></ul><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Mappingofqueryproper
tiestocolumn%2Ffieldnames">Mapping of query properties to column/field names</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-SearchBean">SearchBean</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-ConvertingFIQLqueries">Converting FIQL queries</a></li><ul><li><a shape="rect" href="#JAX-RSAdvancedFeatures-SQL">SQL</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-JPA2.0">JPA 2.0</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Lucene">Lucene</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Customvisitors">Custom visitors</a></li></ul><li><a shape="rect" href="#JAX-RSAdvancedFeatures-SearchExpressionsinURIPathsegments">Search Expressions in URI Path segments</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Queriesinvolvingmultipleentities">Queries involving multiple entities</a></li><ul><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Basicqueries">Basic queries</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Com
plexqueries">Complex queries</a></li></ul><li><a shape="rect" href="#JAX-RSAdvancedFeatures-BuildingFIQLqueries">Building FIQL queries</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Usingdatesinqueries">Using dates in queries</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Alternativequerylanguages">Alternative query languages</a></li></ul><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Onewayinvocations">Oneway invocations</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-SupportforContinuations">Support for Continuations</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Serversidecaching">Server-side caching</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-RESTfulserviceswithoutannotations">RESTful services without annotations</a></li><ul><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Configuration">Configuration</a></li></ul></ul></div>
+<ul><li><a shape="rect" href="#JAX-RSAdvancedFeatures-JMSSupport">JMS Support</a></li><ul><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Endpoints">Endpoints</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Client">Client</a></li></ul><li><a shape="rect" href="#JAX-RSAdvancedFeatures-FIQLsearchqueries">FIQL search queries</a></li><ul><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Introduction">Introduction</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-DependenciesandConfiguration">Dependencies and Configuration</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-WorkingwithFIQLqueries">Working with FIQL queries</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-CapturingFIQLqueries">Capturing FIQL queries</a></li><ul><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Mappingofquerypropertiestobeanproperties">Mapping of query properties to bean properties</a></li></ul><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Mappingofqueryproper
tiestocolumn%2Ffieldnames">Mapping of query properties to column/field names</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-SearchBean">SearchBean</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-ConvertingFIQLqueries">Converting FIQL queries</a></li><ul><li><a shape="rect" href="#JAX-RSAdvancedFeatures-SQL">SQL</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-JPA2.0">JPA 2.0</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Lucene">Lucene</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Customvisitors">Custom visitors</a></li><ul><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Untypedconverters">Untyped converters</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Typedconverters">Typed converters</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Customparsing">Custom parsing</a></li></ul></ul><li><a shape="rect" href="#JAX-RSAdvancedFeatures-SearchExpressionsinURIPathsegments">Search Expressions in URI Path seg
ments</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Queriesinvolvingmultipleentities">Queries involving multiple entities</a></li><ul><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Basicqueries">Basic queries</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Complexqueries">Complex queries</a></li></ul><li><a shape="rect" href="#JAX-RSAdvancedFeatures-BuildingFIQLqueries">Building FIQL queries</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Usingdatesinqueries">Using dates in queries</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Alternativequerylanguages">Alternative query languages</a></li></ul><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Onewayinvocations">Oneway invocations</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-SupportforContinuations">Support for Continuations</a></li><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Serversidecaching">Server-side caching</a></li><li><a shape="rect" href="#JAX-RSAdvanc
edFeatures-RESTfulserviceswithoutannotations">RESTful services without annotations</a></li><ul><li><a shape="rect" href="#JAX-RSAdvancedFeatures-Configuration">Configuration</a></li></ul></ul></div>
<h1><a shape="rect" name="JAX-RSAdvancedFeatures-JMSSupport"></a>JMS Support</h1>
@@ -484,7 +484,7 @@ JPACriteriaQueryVisitor<Book, Tuple&g
sc.visit(visitor);
List<SingularAttribute<Book, ?>> selections = <span class="code-keyword">new</span> LinkedList<SingularAttribute<Book, ?>>();
-selections.add(Book_.id);
+selections.add(Book_.address);
visitor.selectTuple(selections);
@@ -546,44 +546,96 @@ org.apache.lucene.search.Query phraseQue
<h3><a shape="rect" name="JAX-RSAdvancedFeatures-Customvisitors"></a>Custom visitors</h3>
-<p>Here is a possible code template to follow when a custom visitor needs to be written:</p>
+<p>In cases when a custom conversion has to be done, a converter for doing the untyped (example, SQL) or typed (example, JPA2 TypedQuery) conversions can be provided. </p>
+
+<h4><a shape="rect" name="JAX-RSAdvancedFeatures-Untypedconverters"></a>Untyped converters</h4>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
-<span class="code-keyword">public</span> class CustomVisitor<T> impements SearchConditionVisitor<T> {
+<span class="code-keyword">public</span> class CustomSQLVisitor<T> <span class="code-keyword">extends</span> AbstractSearchConditionVisitor<T, <span class="code-object">String</span>> {
+<span class="code-keyword">private</span> <span class="code-object">String</span> tableName;
<span class="code-keyword">private</span> StringBuilder sb = <span class="code-keyword">new</span> StringBuilder();
<span class="code-keyword">public</span> void visit(SearchCondition<T> sc) {
<span class="code-keyword">if</span> (sb == <span class="code-keyword">null</span>) {
sb = <span class="code-keyword">new</span> StringBuilder();
- <span class="code-comment">// start the expression as needed
+ <span class="code-comment">// start the expression as needed, example
+</span> <span class="code-comment">// sb.append(<span class="code-quote">"Select from "</span>).append(tableName);
</span> }
PrimitiveStatement statement = sc.getStatement();
<span class="code-keyword">if</span> (statement != <span class="code-keyword">null</span>) {
- <span class="code-comment">// ex a > b
+ <span class="code-comment">// ex <span class="code-quote">"a > b"</span>
</span> <span class="code-comment">// use statement.getValue()
-</span> <span class="code-comment">// use statement.getConditionType()
+</span> <span class="code-comment">// use statement.getConditionType() such as greaterThan, lessThan
</span> <span class="code-comment">// use statement.getProperty();
-</span>
+</span> <span class="code-comment">// to convert <span class="code-quote">"a > b"</span> into SQL expression
+</span> sb.append(toSQL(statement));
} <span class="code-keyword">else</span> {
- <span class="code-keyword">for</span> (SearchCondition<T> condition : sc.getSearchConditions()) {
- <span class="code-comment">// pre-process
+ <span class="code-comment">// composite expression, ex <span class="code-quote">"a > b;c < d"</span>
+</span> <span class="code-keyword">for</span> (SearchCondition<T> condition : sc.getSearchConditions()) {
+ <span class="code-comment">// pre-process, example sb.append(<span class="code-quote">"("</span>);
</span> condition.accept(<span class="code-keyword">this</span>);
- <span class="code-comment">// post-process
+ <span class="code-comment">// post-process, example sb.append(<span class="code-quote">")"</span>);
</span> }
}
}
- <span class="code-keyword">public</span> <span class="code-object">String</span> getResult() {
- <span class="code-comment">// convert the internal state into <span class="code-object">String</span>
-</span> }
+ <span class="code-keyword">public</span> <span class="code-object">String</span> getQuery() {
+ <span class="code-keyword">return</span> sb.toString();
+ }
+}
+</pre>
+</div></div>
+
+<h4><a shape="rect" name="JAX-RSAdvancedFeatures-Typedconverters"></a>Typed converters</h4>
+
+<p>import org.custom.search.Query;</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+<span class="code-keyword">public</span> class CustomTypedVisitor<T> <span class="code-keyword">extends</span> AbstractSearchConditionVisitor<T, Query> {
+
+<span class="code-keyword">private</span> Stack<List<Query>> queryStack = <span class="code-keyword">new</span> Stack<List<Query>>();
+
+<span class="code-keyword">public</span> void visit(SearchCondition<T> sc) {
+
+ PrimitiveStatement statement = sc.getStatement();
+ <span class="code-keyword">if</span> (statement != <span class="code-keyword">null</span>) {
+ <span class="code-comment">// ex <span class="code-quote">"a > b"</span>
+</span> <span class="code-comment">// use statement.getValue()
+</span> <span class="code-comment">// use statement.getConditionType() such as greaterThan, lessThan
+</span> <span class="code-comment">// use statement.getProperty();
+</span> <span class="code-comment">// to convert <span class="code-quote">"a > b"</span> into Query object
+</span> Query query = buildSimpleQuery(statement);
+ queryStack.peek().add(query);
+
+ } <span class="code-keyword">else</span> {
+ <span class="code-comment">// composite expression, ex <span class="code-quote">"a > b;c < d"</span>
+</span> queryStack.push(<span class="code-keyword">new</span> ArrayList<Query>());
+
+ <span class="code-keyword">for</span> (SearchCondition<T> condition : sc.getSearchConditions()) {
+ condition.accept(<span class="code-keyword">this</span>);
+ }
+
+ <span class="code-object">boolean</span> orCondition = sc.getConditionType() == ConditionType.OR;
+ List<Query> queries = queryStack.pop();
+ queryStack.peek().add(createCompositeQuery(queries, orCondition));
+ }
+ }
+
+ <span class="code-keyword">public</span> Query getResult() {
+ <span class="code-keyword">return</span> queryStack.peek().get(0);
+ }
}
</pre>
</div></div>
+
+<h4><a shape="rect" name="JAX-RSAdvancedFeatures-Customparsing"></a>Custom parsing</h4>
+
<p>If needed you can access a FIQL query directly and delegate it further to your own custom FIQL handler:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
@@ -692,7 +744,7 @@ then a boolean contextual property "igno
<h3><a shape="rect" name="JAX-RSAdvancedFeatures-Basicqueries"></a>Basic queries</h3>
-<p>Consider the query like "find the first chapters of all the books with 'id' less than 123".<br clear="none">
+<p>Consider the query like "find chapters with a given chapter id from all the books with 'id' less than 123".<br clear="none">
One easy way to manage such queries is to make FIQL and JAX-RS work together. For example: </p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
@@ -704,7 +756,7 @@ One easy way to manage such queries is t
<span class="code-comment">//GET /books[id=lt=123]/chapter/1
</span> @GET
@Path(<span class="code-quote">"books[{search}]/chapter/{id}"</span>)
- <span class="code-keyword">public</span> List<Book> findSelectedBooks(@PathParam(<span class="code-quote">"search"</span>) <span class="code-object">String</span> searchExpression,
+ <span class="code-keyword">public</span> List<Chapter> findSelectedChapters(@PathParam(<span class="code-quote">"search"</span>) <span class="code-object">String</span> searchExpression,
@PathParam(<span class="code-quote">"id"</span>) <span class="code-object">int</span> chapterIndex) {
<span class="code-keyword">return</span> doFindSelectedChapters(searchExpression, chapterIndex);
}
@@ -732,8 +784,11 @@ One easy way to manage such queries is t
<h3><a shape="rect" name="JAX-RSAdvancedFeatures-Complexqueries"></a>Complex queries</h3>
-<p>At the moment one needs to follow the example (not necessarily using JPA2) presented in the previous section to manage the complex queries <br clear="none">
-such as "find all the chapters with id less than 5 for all the books with id greater than 300", for example: </p>
+<p>In the previous section we had the properties of two entities, Book and Chapter, used in the query. The query was considered 'simple' because it was really only the simple book properties that were checked, and the only chapter property was a chapter id, assumed to be equal to a chapter list index. </p>
+
+<p>Consider "Find all the chapters with id less than 5 for all the books with id greater than 300".</p>
+
+<p>One way to handle is to follow the example from the previous section with few modifications: </p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
@@ -745,7 +800,7 @@ such as "find all the chapters with id l
<span class="code-comment">//GET /books(id=gt=300)/chapters(id=lt=5)
</span> @GET
@Path(<span class="code-quote">"books({search1})/chapter/{search2}"</span>)
- <span class="code-keyword">public</span> List<Book> findSelectedBooks(@PathParam(<span class="code-quote">"search1"</span>) <span class="code-object">String</span> bookExpression,
+ <span class="code-keyword">public</span> List<Chapter> findSelectedChapters(@PathParam(<span class="code-quote">"search1"</span>) <span class="code-object">String</span> bookExpression,
@PathParam(<span class="code-quote">"search2"</span>) <span class="code-object">String</span> chapterExpression) {
<span class="code-keyword">return</span> doFindSelectedBooks(bookExpression, chapterExpression);
}
@@ -773,8 +828,45 @@ such as "find all the chapters with id l
</pre>
</div></div>
-<p>The above code can be quite functional but not be optimal. Much depends on the actual relationship between the entities, whether the initial (JPA2) query eagerly loaded all the chapters for every given book or not, etc. Perhaps a JOIN-like query which will immediately return only the matching chapters will be more optimal. Support for capturing the expressions involving multiple entities and possibly converting them to JOIN statements will be investigated shortly.</p>
+<p>In this case two conditions are created and the 2nd condition is used to filter the chapters from the books filtered by the 1st condition.</p>
+
+<p>Perhaps a simpler approach, especially in case of JPA2, is to start looking for Chapters immediately, assuming Chapter classes have a one to one bidirectional relationship with Book:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+
+<span class="code-keyword">public</span> class Chapter {
+ <span class="code-keyword">private</span> <span class="code-object">int</span> id;
+ <span class="code-keyword">private</span> Book book;
+
+ @OneToOne(mappedBy=<span class="code-quote">"book"</span>)
+ <span class="code-keyword">public</span> Book getBook() {}
+}
+
+@Path(<span class="code-quote">"search"</span>)
+<span class="code-keyword">public</span> class BooksResource {
+ @Context
+ <span class="code-keyword">private</span> SearchContext context;
+
+ <span class="code-comment">//GET /chapters(bookId=gt=300,id=lt=5)
+</span> @GET
+ @Path(<span class="code-quote">"chapters({search})"</span>)
+ <span class="code-keyword">public</span> List<Chapter> findSelectedChapters(@PathParam(<span class="code-quote">"search"</span>) <span class="code-object">String</span> chapterExpression) {
+
+ SearchCondition<Chapter> chapterCondition = context.getCondition(chapterExpression, Chapter.class);
+
+ JPATypedQuery<Chapter> visitor = <span class="code-keyword">new</span> JPATypedQueryVisitor<Chapter>(entityManager, Chapter.class);
+ chapterCondition.visit(visitor);
+ TypedQuery<Chapter> typedQuery = visitor.getQuery();
+ <span class="code-keyword">return</span> typedQuery.getResultList();
+ }
+
+}
+Note <span class="code-keyword">this</span> code assumes that <span class="code-quote">"bookId"</span> is mapped to <span class="code-quote">"Book.id"</span> property with the help of the contextual <span class="code-quote">"search.bean.property.map"</span> property as explained earlier.
+
+</pre>
+</div></div>
<h2><a shape="rect" name="JAX-RSAdvancedFeatures-BuildingFIQLqueries"></a>Building FIQL queries</h2>