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>
