svn commit: r787173 - /websites/staging/chemistry/trunk/content/java/how-to/how-to-process-query.html

[bu...@apache.org]

Author: buildbot
Date: Fri Mar 18 12:58:18 2011
New Revision: 787173

Log:
Staging update by buildbot

Modified:
    websites/staging/chemistry/trunk/content/java/how-to/how-to-process-query.html

Modified: websites/staging/chemistry/trunk/content/java/how-to/how-to-process-query.html
==============================================================================
--- websites/staging/chemistry/trunk/content/java/how-to/how-to-process-query.html (original)
+++ websites/staging/chemistry/trunk/content/java/how-to/how-to-process-query.html Fri Mar 18 12:58:18 2011
@@ -183,7 +183,84 @@ Apache Chemistry - Query Integration
            </td>
            <td height="100%">
              <!-- Content -->
-             <div class="wiki-content"></div>
+             <div class="wiki-content"><div class="toc">
+<ul>
+<li><a href="#opencmis_query_integration">OpenCMIS Query Integration</a><ul>
+<li><a href="#implement_query_in_the_discovery_service">Implement query in the discovery service</a></li>
+<li><a href="#use_built-in_antlr_and_antlr_cmisql_grammar">Use built-in ANTLR and ANTLR CMISQL grammar</a></li>
+<li><a href="#use_opencmis_cmsiql_grammar_and_integrate_into_antlr_query_walker">Use OpenCMIS CMSIQL grammar and integrate into ANTLR query walker</a></li>
+<li><a href="#use_predefined_query_walker">Use predefined query walker</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<h1 id="opencmis_query_integration">OpenCMIS Query Integration</h1>
+<p>The CMIS standard contains a powerful query language that supports full
+text and relational metadata query capabilities and is modeled along a
+subset of SQL. Many repositories will have the demand to integrate into
+this query interface. OpenCMIS provides support to make a query integration
+easier. This article explains the various hooks that are provided to
+integrate into the query interface. These hooks provide different levels of
+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:</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>
+<h2 id="implement_query_in_the_discovery_service">Implement query in the discovery service</h2>
+<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>
+<h2 id="use_built-in_antlr_and_antlr_cmisql_grammar">Use built-in ANTLR and ANTLR CMISQL grammar</h2>
+<p>OpenCMIS comes with a build-in integration of ANTLR and provides a grammar
+file for CMISQL. You can reuse this grammar file, modify or extend it and
+integrate query by using the ANTLR mechanisms for parsing and walking the
+abstract syntax tree. Please refer to the ANTLR documentation for further
+information. This is the right level to use if you need custom parser tree
+transformations or would like to extend the grammar with your own
+constructs. For demonstration purposes OpenCMIS provides a sample extended
+grammar as an example.</p>
+<h2 id="use_opencmis_cmsiql_grammar_and_integrate_into_antlr_query_walker">Use OpenCMIS CMSIQL grammar and integrate into ANTLR query walker</h2>
+<p>If the standard CMISQL grammar is sufficient for you there is another level
+of integration. For many repositories there are common tasks for processing
+queries: The columns of the select part need to be evaluated and mapped to
+type and property definitions. The from area needs to be mapped to type
+definitions and some parts of the where part again refer to properties in
+types. In addition all aliases defined in the statement need to be resolved
+and many validations are performed. OpenCMIS provides a class that performs
+these common tasks. You can make use of the resolved types, properties and
+aliases and walk the resulting abstract syntax tree (AST) to evaluate the
+query. You are free to walk the AST as many times as you need and in the
+order you prefer. The basic idea is that the SELECT and FROM parts are
+processed by OpenCMIS and you are responsible for the WHERE part.&nbsp; The
+CMIS InMemory server provides an example for this level of integration: For
+each object contained in the repository the tree is traversed and checked
+if it matches the current query. You can take the InMemory code as an
+example if you decide to use this integration point.</p>
+<h2 id="use_predefined_query_walker">Use predefined query walker</h2>
+<p>For some repositories a simple and one-pass query traversal is sufficient.
+This can be the case if for example your query needs to be translated to a
+SQL query statement. Because ANTLR has some complexity OpenCMIS provides a
+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
+(<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 <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
+<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
+<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></div>
              <!-- Content -->
            </td>
           </tr>