Author: buildbot
Date: Mon Feb 21 17:04:58 2011
New Revision: 785892
Log:
Staging update by buildbot
Modified:
websites/staging/chemistry/trunk/content/java/queryintegration.html
Modified: websites/staging/chemistry/trunk/content/java/queryintegration.html
==============================================================================
--- websites/staging/chemistry/trunk/content/java/queryintegration.html
(original)
+++ websites/staging/chemistry/trunk/content/java/queryintegration.html Mon Feb
21 17:04:58 2011
@@ -185,15 +185,16 @@ integrate into the query interface. Thes
comfort and flexibility. OpenCMIS integrates a query parser that uses ANTLR
as parsing engine. However there is no strong dependency on ANTLR. If you
prefer a different language parsing tool it is possible to do this.</p>
-<p>There are four different levels how you can integrate query:
-1. Implement query in the discovery service
-1. Use the built-in ANTLR and ANTLR CMISQL grammar
-1. Use OpenCMIS CMISQL grammar and integrate into ANTLR query walker
-1. Use predefined query walker and integrate into interface
-IQueryConditionProcessor.</p>
+<p>There are four different levels how you can integrate query:</p>
+<ol>
+<li>Implement query in the discovery service</li>
+<li>Use the built-in ANTLR and ANTLR CMISQL grammar</li>
+<li>Use OpenCMIS CMISQL grammar and integrate into ANTLR query walker</li>
+<li>Use predefined query walker and integrate into interface
<code>IQueryConditionProcessor</code>.</li>
+</ol>
<p><a name="QueryIntegration-Implementqueryinthediscoveryservice"></a></p>
<h2 id="implement_query_in_the_discovery_service">Implement query in the
discovery service</h2>
-<p>The first way is to implement the query() method like any other service
+<p>The first way is to implement the <code>query()</code> method like any
other service
method on your own. This gives you the maximum flexibility including using
a parser tool of your choice and extensions of the query grammar as you
like. This is also the method with the highest implementation effort.</p>
@@ -233,109 +234,109 @@ SQL query statement. Because ANTLR has s
predefined walker that does a simple one pass depth-first traversal. If
this is sufficient this interface hides most of the complexity of ANTLR.
All you have to do is to implement a Java interface
-(IQueryConditionProcessor). You can refer to the unit tests for example
-code. The class TestQueryProcessor nested in the unit test ProcessQueryTest
+(<code>IQueryConditionProcessor</code>). You can refer to the unit tests for
example
+code. The class <code>TestQueryProcessor</code> nested in the unit test
<code>ProcessQueryTest</code>
provides an example of such a walker. Some utility methods like for example
-parsing literals like "abc", -123 to Java objects like String and Integer
+parsing literals like <code>"abc"</code>, <code>-123</code> to Java objects
like <code>String</code> and <code>Integer</code>
are common tasks. Therefore this is implemented in an abstract class
-AbstractQueryConditionProcessor. This declares all interface methods as
+<code>AbstractQueryConditionProcessor</code>. This declares all interface
methods as
abstract and provides default implementations for common tasks. In most
cases you will derive your implementation from
-AbstractQueryConditionProcessor and not directly implement the interface.</p>
+<code>AbstractQueryConditionProcessor</code> and not directly implement the
interface.</p>
<p>Note: There is currently no predefined walker for the JOIN statements. If
you need to support JOINS you have to build your own walker for this part
as outlined in the previous section.</p>
<p><a name="QueryIntegration-UsingQueryObject"></a></p>
<h2 id="using_queryobject">Using QueryObject</h2>
-<p>The class QueryObject provides all the basic functionality for resolving
-types and properties and performs common validation tasks. The QueryObject
-processes the SELECT and FROM parts as well as all property references from
-the WHERE part. It maintains a list of Java objects and interface that you
+<p>The class <code>QueryObject</code> provides all the basic functionality for
resolving
+types and properties and performs common validation tasks. The
<code>QueryObject</code>
+processes the <code>SELECT</code> and <code>FROM</code> parts as well as all
property references from
+the <code>WHERE</code> part. It maintains a list of Java objects and interface
that you
can use to access the property and type definitions given your current
position in the statement. For an example refer to the class
-StoreManagerImpl of the InMemory Server and method query(). To be able to
-use this object QueryObj needs to get access to the types contained in your
-repository. For this purpose you need to pass an interface to a TypeManager
+<code>StoreManagerImpl</code> of the InMemory Server and method
<code>query()</code>.
+To be able to use this object <code>QueryObj</code> needs to get access to the
types contained in your
+repository. For this purpose you need to pass an interface to a
<code>TypeManager</code>
as input parameter. The second parameter is your query walker implementing
-IQueryConditionProcessor. Your code will typically look like this:</p>
-<div class="codehilite"><pre><span class="n">TypeManager</span> <span
class="n">tm</span> <span class="o">=</span> <span class="k">new</span> <span
class="n">MyTypeManager</span><span class="p">();</span> <span
class="sr">//</span> <span class="n">implements</span> <span
class="n">interface</span> <span class="n">TypeManager</span>
+<code>IQueryConditionProcessor</code>. Your code will typically look like
this:</p>
+<div class="codehilite"><pre><span class="n">TypeManager</span> <span
class="n">tm</span> <span class="o">=</span> <span class="k">new</span> <span
class="n">MyTypeManager</span><span class="o">();</span> <span class="c1">//
implements interface TypeManager</span>
-<span class="n">IQueryConditionProcessor</span> <span
class="n">myWalker</span> <span class="o">=</span> <span class="k">new</span>
<span class="n">MyWalker</span><span class="p">();</span> <span
class="sr">//</span> <span class="n">implements</span> <span
class="n">interface</span>
- <span class="n">IQueryConditionProcessor</span> <span class="ow">or</span>
<span class="n">extends</span> <span
class="n">AbstractQueryConditionProcessor</span>
+<span class="n">IQueryConditionProcessor</span> <span
class="n">myWalker</span> <span class="o">=</span> <span class="k">new</span>
<span class="n">MyWalker</span><span class="o">();</span> <span class="c1">//
implements interface</span>
+ <span class="n">IQueryConditionProcessor</span> <span class="n">or</span>
<span class="kd">extends</span> <span
class="n">AbstractQueryConditionProcessor</span>
-<span class="n">queryObj</span> <span class="o">=</span> <span
class="k">new</span> <span class="n">QueryObject</span><span
class="p">(</span><span class="n">tm</span><span class="p">,</span> <span
class="n">myWalker</span><span class="p">);</span>
+<span class="n">queryObj</span> <span class="o">=</span> <span
class="k">new</span> <span class="n">QueryObject</span><span
class="o">(</span><span class="n">tm</span><span class="o">,</span> <span
class="n">myWalker</span><span class="o">);</span>
</pre></div>
-<p>queryObj then will process the statement and call the interface methods of
+<p><code>queryObj</code> then will process the statement and call the
interface methods of
your walker:</p>
-<div class="codehilite"><pre><span class="n">try</span> <span
class="p">{</span>
+<div class="codehilite"><pre><span class="k">try</span> <span
class="o">{</span>
- <span class="n">CmisQueryWalker</span> <span class="n">walker</span> <span
class="o">=</span> <span class="n">QueryObject</span><span
class="o">.</span><span class="n">getWalker</span><span class="p">(</span><span
class="n">statement</span><span class="p">);</span>
- <span class="n">walker</span><span class="o">.</span><span
class="n">query</span><span class="p">(</span><span
class="n">queryObj</span><span class="p">);</span>
+ <span class="n">CmisQueryWalker</span> <span class="n">walker</span> <span
class="o">=</span> <span class="n">QueryObject</span><span
class="o">.</span><span class="na">getWalker</span><span
class="o">(</span><span class="n">statement</span><span class="o">);</span>
+ <span class="n">walker</span><span class="o">.</span><span
class="na">query</span><span class="o">(</span><span
class="n">queryObj</span><span class="o">);</span>
-<span class="p">}</span> <span class="n">catch</span> <span
class="p">(</span><span class="n">RecognitionException</span> <span
class="n">e</span><span class="p">)</span> <span class="p">{</span>
+<span class="o">}</span> <span class="k">catch</span> <span
class="o">(</span><span class="n">RecognitionException</span> <span
class="n">e</span><span class="o">)</span> <span class="o">{</span>
- <span class="n">throw</span> <span class="k">new</span> <span
class="n">RuntimeException</span><span class="p">(</span><span
class="s">"Walking of statement failed with</span>
-<span class="s"> RecognitionException error: \n "</span> <span
class="o">+</span> <span class="n">e</span><span class="p">);</span>
+ <span class="k">throw</span> <span class="k">new</span> <span
class="nf">RuntimeException</span><span class="o">(</span><span
class="s">"Walking of statement failed with</span>
+<span class="s"> RecognitionException error: \n "</span> <span
class="o">+</span> <span class="n">e</span><span class="o">);</span>
-<span class="p">}</span> <span class="n">catch</span> <span
class="p">(</span><span class="n">Exception</span> <span
class="n">e</span><span class="p">)</span> <span class="p">{</span>
- <span class="n">throw</span> <span class="k">new</span> <span
class="n">RuntimeException</span><span class="p">(</span><span
class="s">"Walking of statement failed with exception:</span>
-<span class="s"> \n "</span> <span class="o">+</span> <span
class="n">e</span><span class="p">);</span>
-<span class="p">}</span>
+<span class="o">}</span> <span class="k">catch</span> <span
class="o">(</span><span class="n">Exception</span> <span
class="n">e</span><span class="o">)</span> <span class="o">{</span>
+ <span class="k">throw</span> <span class="k">new</span> <span
class="nf">RuntimeException</span><span class="o">(</span><span
class="s">"Walking of statement failed with exception:</span>
+<span class="s"> \n "</span> <span class="o">+</span> <span
class="n">e</span><span class="o">);</span>
+<span class="o">}</span>
</pre></div>
<p>After this method returns you may for example ask your walker object
-myWalker for the generated SQL string.</p>
+<code>myWalker</code> for the generated SQL string.</p>
<p><a
name="QueryIntegration-Processinganodeandreferencingtypesandproperties"></a></p>
<h2 id="processing_a_node_and_referencing_types_and_properties">Processing a
node and referencing types and properties</h2>
<p>While traversing the tree you often will need to access the property and
-type definitions that are referenced in the where clause. The QueryObject
+type definitions that are referenced in the where clause. The
<code>QueryObject</code>
provides the necessary information for resolving the references. For
example the statement</p>
<p>... WHERE x < 123</p>
-<p>will result in calling the method onLessThan() in your walker callback
+<p>will result in calling the method <code>onLessThan()</code> in your walker
callback
implementation:</p>
-<div class="codehilite"><pre><span class="n">public</span> <span
class="n">void</span> <span class="n">onLessThan</span><span
class="p">(</span><span class="n">Tree</span> <span
class="n">ltNode</span><span class="p">,</span> <span class="n">Tree</span>
<span class="n">leftNode</span><span class="p">,</span> <span
class="n">Tree</span> <span class="n">rightNode</span><span class="p">)</span>
<span class="p">{</span>
+<div class="codehilite"><pre><span class="kd">public</span> <span
class="kt">void</span> <span class="nf">onLessThan</span><span
class="o">(</span><span class="n">Tree</span> <span
class="n">ltNode</span><span class="o">,</span> <span class="n">Tree</span>
<span class="n">leftNode</span><span class="o">,</span> <span
class="n">Tree</span> <span class="n">rightNode</span><span class="o">)</span>
<span class="o">{</span>
- <span class="n">Object</span> <span class="n">rVal</span> <span
class="o">=</span> <span class="n">onLiteral</span><span
class="p">(</span><span class="n">rightChild</span><span class="p">);</span>
- <span class="n">ColumnReference</span> <span class="n">colRef</span><span
class="p">;</span>
+ <span class="n">Object</span> <span class="n">rVal</span> <span
class="o">=</span> <span class="n">onLiteral</span><span
class="o">(</span><span class="n">rightChild</span><span class="o">);</span>
+ <span class="n">ColumnReference</span> <span class="n">colRef</span><span
class="o">;</span>
- <span class="n">CmisSelector</span> <span class="n">sel</span> <span
class="o">=</span> <span class="n">queryObj</span><span class="o">.</span><span
class="n">getColumnReference</span><span class="p">(</span><span
class="n">columnNode</span>
- <span class="o">.</span><span
class="n">getTokenStartIndex</span><span class="p">());</span>
+ <span class="n">CmisSelector</span> <span class="n">sel</span> <span
class="o">=</span> <span class="n">queryObj</span><span class="o">.</span><span
class="na">getColumnReference</span><span class="o">(</span><span
class="n">columnNode</span>
+ <span class="o">.</span><span
class="na">getTokenStartIndex</span><span class="o">());</span>
- <span class="k">if</span> <span class="p">(</span><span
class="n">null</span> <span class="o">==</span> <span class="n">sel</span><span
class="p">)</span>
- <span class="n">throw</span> <span class="k">new</span> <span
class="n">RuntimeException</span><span class="p">(</span><span
class="s">"Unknown property query name "</span> <span
class="o">+</span>
- <span class="n">columnNode</span><span class="o">.</span><span
class="n">getChild</span><span class="p">(</span><span class="mi">0</span><span
class="p">));</span>
- <span class="k">else</span> <span class="k">if</span> <span
class="p">(</span><span class="n">sel</span> <span class="n">instanceof</span>
<span class="n">ColumnReference</span><span class="p">)</span>
- <span class="n">colRef</span> <span class="o">=</span> <span
class="p">(</span><span class="n">ColumnReference</span><span
class="p">)</span> <span class="n">sel</span><span class="p">;</span>
+ <span class="k">if</span> <span class="o">(</span><span
class="kc">null</span> <span class="o">==</span> <span
class="n">sel</span><span class="o">)</span>
+ <span class="k">throw</span> <span class="k">new</span> <span
class="nf">RuntimeException</span><span class="o">(</span><span
class="s">"Unknown property query name "</span> <span
class="o">+</span>
+ <span class="n">columnNode</span><span class="o">.</span><span
class="na">getChild</span><span class="o">(</span><span
class="mi">0</span><span class="o">));</span>
+ <span class="k">else</span> <span class="nf">if</span> <span
class="o">(</span><span class="n">sel</span> <span class="k">instanceof</span>
<span class="n">ColumnReference</span><span class="o">)</span>
+ <span class="n">colRef</span> <span class="o">=</span> <span
class="o">(</span><span class="n">ColumnReference</span><span
class="o">)</span> <span class="n">sel</span><span class="o">;</span>
- <span class="n">TypeDefinition</span> <span class="n">td</span> <span
class="o">=</span> <span class="n">colRef</span><span class="o">.</span><span
class="n">getTypeDefinition</span><span class="p">();</span>
+ <span class="n">TypeDefinition</span> <span class="n">td</span> <span
class="o">=</span> <span class="n">colRef</span><span class="o">.</span><span
class="na">getTypeDefinition</span><span class="o">();</span>
<span class="n">PropertyDefinition</span> <span class="n">pd</span> <span
class="o">=</span>
- <span class="n">td</span><span class="o">.</span><span
class="n">getPropertyDefinitions</span><span class="p">()</span><span
class="o">.</span><span class="n">get</span><span class="p">(</span><span
class="n">colRef</span><span class="o">.</span><span
class="n">getPropertyId</span><span class="p">());</span>
+ <span class="n">td</span><span class="o">.</span><span
class="na">getPropertyDefinitions</span><span class="o">().</span><span
class="na">get</span><span class="o">(</span><span class="n">colRef</span><span
class="o">.</span><span class="na">getPropertyId</span><span
class="o">());</span>
- <span class="sr">//</span> <span class="err">â¦</span> <span
class="n">process</span> <span class="n">the</span> <span
class="n">statement</span><span class="p">,</span> <span class="k">for</span>
<span class="n">example</span> <span class="n">append</span> <span
class="n">it</span> <span class="n">to</span> <span class="n">a</span> <span
class="n">WHERE</span>
- <span class="sr">//</span> <span class="n">in</span> <span
class="n">your</span> <span class="n">generated</span> <span
class="n">SQL</span> <span class="n">statement</span><span class="o">.</span>
-<span class="p">}</span>
+ <span class="c1">// ⦠process the statement, for example append it to a
WHERE</span>
+ <span class="c1">// in your generated SQL statement.</span>
+<span class="o">}</span>
</pre></div>
<p>The right child node is a literal and you will get an Integer object with
value 123. The left node is a reference to property and
-getColumnReference() will either give you a function (currently the only
-supported function is SCORE()) or a reference to a property in a type of
+<code>getColumnReference()</code> will either give you a function (currently
the only
+supported function is <code>SCORE()</code>) or a reference to a property in a
type of
your type system. The query object maintains several maps to resolve
references. The key to the map is always the token index in the incoming
token stream (an integer value). You can get the token index for each node
-by calling getTokenStartIndex() on the node.</p>
+by calling <code>getTokenStartIndex()</code> on the node.</p>
<p><a name="QueryIntegration-Buildingtheresultlist"></a></p>
<h2 id="building_the_result_list">Building the result list</h2>
-<p>After processing the query an ObjectList has to be returned containing the
+<p>After processing the query an <code>ObjectList</code> has to be returned
containing the
requested properties and function results. You can ask the query object for
the requested information:</p>
-<div class="codehilite"><pre><span class="n">Map</span> <span
class="n">props</span> <span class="o">=</span> <span
class="n">queryObj</span><span class="o">.</span><span
class="n">getRequestedProperties</span><span class="p">();</span>
-<span class="n">Map</span> <span class="n">funcs</span> <span
class="o">=</span> <span class="n">queryObj</span><span class="o">.</span><span
class="n">getRequestedFuncs</span><span class="p">();</span>
+<div class="codehilite"><pre><span class="n">Map</span> <span
class="n">props</span> <span class="o">=</span> <span
class="n">queryObj</span><span class="o">.</span><span
class="na">getRequestedProperties</span><span class="o">();</span>
+<span class="n">Map</span> <span class="n">funcs</span> <span
class="o">=</span> <span class="n">queryObj</span><span class="o">.</span><span
class="na">getRequestedFuncs</span><span class="o">();</span>
</pre></div>
