cayenne-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From aadamc...@apache.org
Subject svn commit: r554413 [11/17] - in /cayenne/main/trunk/docs/doc/src/main/resources/doc: ./ Documentation/ Documentation/Cayenne Guide/ Documentation/Cayenne Guide/Ant Tasks/ Documentation/Cayenne Guide/Ant Tasks/cdataport/ Documentation/Cayenne Guide/Ant...
Date Sun, 08 Jul 2007 19:11:53 GMT
Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/SQLTemplate Query/Scripting SQLTemplate/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Queries/SQLTemplate%20Query/Scripting%20SQLTemplate/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/SQLTemplate Query/Scripting SQLTemplate/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/SQLTemplate Query/Scripting SQLTemplate/index.html Sun Jul  8 12:11:31 2007
@@ -0,0 +1,296 @@
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+ 
+     http://www.apache.org/licenses/LICENSE-2.0
+ 
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.
+-->
+<html>
+  <head>
+    <title>Apache Cayenne Documentation - Scripting SQLTemplate</title>
+    <style type="text/css">@import "../../../../../style.css";</style>
+  </head>
+<body>
+  <div class="header">
+    <div style="float: left;"><a href="http://cayenne.apache.org/"><img src="../../../../../images/logo.gif" align="absmiddle" border="0"></a></div>
+    <span class="logoSpaceLink"><a href="../../../../../index.html">Cayenne User Documentation</a></span><br />
+    <span class="pagetitle">Scripting SQLTemplate</span>
+  </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../../../Documentation/Cayenne Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Design/index.html">Design</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/index.html">Queries</a><ul>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/SelectQuery/index.html">SelectQuery</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/SQLTemplate Query/index.html">SQLTemplate Query</a><ul>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/SQLTemplate Query/SQLTemplate Basics/index.html">SQLTemplate Basics</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/SQLTemplate Query/Scripting SQLTemplate/index.html">Scripting SQLTemplate</a><ul>
+</ul>
+</li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/SQLTemplate Query/Advanced SQLTemplate/index.html">Advanced SQLTemplate</a></li>
+</ul>
+</li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/EJBQLQuery/index.html">EJBQLQuery</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/NamedQuery/index.html">NamedQuery</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/ObjectIdQuery/index.html">ObjectIdQuery</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/QueryChain/index.html">QueryChain</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/RelationshipQuery/index.html">RelationshipQuery</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/Queries Stored in DataMap/index.html">Queries Stored in DataMap</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/Caching Query Results/index.html">Caching Query Results</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/Customizing Queries/index.html">Customizing Queries</a></li>
+</ul>
+</li>
+<li><a href="../../../../../Documentation/Cayenne Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Lifecycle Callbacks/index.html">Lifecycle Callbacks</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Performance Tuning/index.html">Performance Tuning</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Caching and Fresh Data/index.html">Caching and Fresh Data</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Maven2 Plugins/index.html">Maven2 Plugins</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Customization/index.html">Customization</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><p>SQLTemplate's internal SQL string is a dynamic script that is processed at runtime to generate PreparedStatement SQL code. Dynamic nature of SQLTemplate makes possible a few important things - it allows to bind parameters on the fly; it provides a way to pass extra information to Cayenne that is not included in the SQL text; it supports including/excluding chunks of SQL depending on runtime parameters.</p>
+
+<p>Scripting of SQL strings is done using <span class="nobr"><a href="http://jakarta.apache.org/velocity" title="Visit page outside Confluence" rel="nofollow">Jakarta Velocity<sup><img class="rendericon" src="../../../../../images/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"/></sup></a></span>. Velocity was chosen primarily for its concise template language (no XML tags within SQL!) that doesn't conflict with the SQL syntax. When creating dynamic SQL template, all standard Velocity directives are available, including <tt>#set</tt>, <tt>#foreach</tt>, <tt>#if</tt>. However due to the nature of the SQL and the need to integrate it with Cayenne runtime, only a few Cayenne custom directives are normally used. These directives (<tt>#bind</tt>..., <tt>#result</tt>, <tt>#chain</tt>, <tt>#chunk</tt>) are described below.</p>
+<table cellpadding='5' width='85%' cellspacing='8px' class='noteMacro' border="0" align='center'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="../../../../../images/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b class="strong">Directive Syntax Note</b><br />Velocity directives start with pound sign (#) and have their parameters separated by space, not comma. E.g. <tt>#bind('SOMESTRING' 'VARCHAR')</tt>.</td></tr></table>
+
+<h3><a name="ScriptingSQLTemplate-NamedParameters"></a>Named Parameters</h3>
+<p><tt>SQLTemplate.setParameters(java.util.Map)</tt> allows setting a number of named parameters that are used to build parts of the query. During template processing by Velocity all keys in the parameters map are available as variables. For example if the map contains a key "name", its value can be referenced as "$name" in the template. Value of the parameter will be inserted in the SQL unmodified:</p>
+
+<h5><a name="ScriptingSQLTemplate-NamedParametersExample"></a>Named Parameters Example</h5>
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-comment">// build SQLTemplate
+</span><span class="code-object">String</span> sql = <span class="code-quote">"delete from $tableName"</span>;
+SQLTemplate delete = <span class="code-keyword">new</span> SQLTemplate(Artist.class, sql, <span class="code-keyword">false</span>);
+...
+<span class="code-comment">// <span class="code-keyword">this</span> will create a query <span class="code-quote">"delete from ARTIST"</span>
+</span>delete.setParameters(Collections.singletonMap(<span class="code-quote">"tableName"</span>, <span class="code-quote">"ARTIST"</span>));
+...
+<span class="code-comment">// <span class="code-keyword">this</span> will create a query <span class="code-quote">"delete from PAINTING"</span>
+</span>delete.setParameters(Collections.singletonMap(<span class="code-quote">"tableName"</span>, <span class="code-quote">"PAINTING"</span>));</pre>
+</div></div>
+
+<h3><a name="ScriptingSQLTemplate-DescribingtheResults%23resultDirective"></a>Describing the Results - #result Directive</h3>
+
+<p><tt>#result</tt> directive is used in selecting SQLTemplates to quickly map an arbitrary ResultSet to a DataObject (or a data row with known keys), and also to control Java types of result values. #result directive has a variable number of arguments:</p>
+
+<ul>
+	<li><tt>#result(columnName)</tt> - e.g. <tt>#result('ARTIST_NAME')</tt></li>
+	<li><tt>#result(columnName javaType)</tt> - e.g. <tt>#result('DATE_OF_BIRTH' 'java.util.Date')</tt></li>
+	<li><tt>#result(columnName javaType columnAlias)</tt> - e.g. <tt>#result('DATE_OF_BIRTH' 'java.util.Date' 'DOB')</tt> - in this case returned data row will use "DOB" instead of "DATE_OF_BIRTH" for the result value.</li>
+</ul>
+
+
+<table cellpadding='5' width='85%' cellspacing='8px' class='noteMacro' border="0" align='center'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="../../../../../images/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>Generally "javaType" argument is a fully-qualified Java class name for a given result column. However for simplicity most common Java types used in JDBC can be specified without a package. These include all numeric types, primitives, String, SQL dates, BigDecimal and BigInteger. So "#result('A' 'String')", "#result('B' 'java.lang.String')" and "#result('C' 'int')" are all valid.</td></tr></table>
+
+<p>While "select * from" queries may work just fine, in most cases it is a good idea to explicitly describe results.</p>
+
+<h5><a name="ScriptingSQLTemplate-%23resultExamples"></a>#result Examples</h5>
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-comment">// build selecting SQLTemplate
+</span><span class="code-object">String</span> sql = <span class="code-quote">"SELECT"</span>
+   + <span class="code-quote">" #result('ARTIST_ID' '<span class="code-object">int</span>'),"</span>
+   + <span class="code-quote">" #result('ARTIST_NAME' '<span class="code-object">String</span>'),"</span>
+   + <span class="code-quote">" #result('DATE_OF_BIRTH' 'java.util.Date')"</span>
+   + <span class="code-quote">" FROM ARTIST"</span>;
+SQLTemplate select = <span class="code-keyword">new</span> SQLTemplate(Artist.class, sql, <span class="code-keyword">true</span>);
+...
+DataContext context...;
+List artists = context.performQuery(select);</pre>
+</div></div>
+
+<h3><a name="ScriptingSQLTemplate-BindingParameters%23bindDirective"></a>Binding Parameters - #bind Directive</h3>
+<p>SQLTemplate uses <tt>#bind</tt> directive to indicate value binding. It has the same meaning as PreparedStatement question mark ("?"), however it also tells Cayenne about the nature of the bound value, so it should be used for all bindings. <tt>#bind()</tt> directive can have a variable number of arguments. The following are the valid invocation formats:</p>
+
+<ul>
+	<li><tt>#bind(value)</tt> - e.g. <tt>#bind($xyz)</tt> or <tt>#bind('somestring')</tt></li>
+	<li><tt>#bind(value jdbcTypeName)</tt> - e.g. <tt>#bind($xyz 'VARCHAR')</tt>. Second argument is the name of JDBC type for this binding. Valid JDBC types are defined in java.sql.Types class. This form is the the most common and useful. It is generally preferred to the single argument form, as it explicitly tells what type of JDBC value this binding is.</li>
+	<li><tt>#bind(value jdbcTypeName precision)</tt> - e.g. <tt>#bind($xyz 'DECIMAL' 2)</tt></li>
+</ul>
+
+
+<h5><a name="ScriptingSQLTemplate-%23binddirectiveexample"></a>#bind directive example</h5>
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-comment">// build SQLTemplate
+</span><span class="code-object">String</span> sql = <span class="code-quote">"update ARTIST set ARTIST_NAME = #bind($name) where ARTIST_ID = #bind($id)"</span>;
+SQLTemplate update = <span class="code-keyword">new</span> SQLTemplate(Artist.class, sql, <span class="code-keyword">false</span>);
+...
+<span class="code-comment">// set parameters and run it...
+</span>Map parameters = <span class="code-keyword">new</span> HashMap();
+parameters.put(<span class="code-quote">"name"</span>, <span class="code-quote">"Publo Picasso"</span>);
+parameters.put(<span class="code-quote">"id"</span>, <span class="code-keyword">new</span> <span class="code-object">Integer</span>(1001));
+update.setParameters(parameters);
+
+DataContext context...;
+context.performNonSelectingQuery(update);</pre>
+</div></div>
+
+<p>SQLTemplate also supports binding Collections for building <tt>IN ( .. )</tt> queries. In any of the <tt>#bind</tt> invocation formats above, you may specify a Collection of values in place of <tt>value</tt>, and Cayenne will automatically expand it.</p>
+
+<h5><a name="ScriptingSQLTemplate-Collectionexample"></a>Collection example</h5>
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-comment">// build SQLTemplate
+</span><span class="code-object">String</span> sql = "SELECT ARTIST_ID, ARTIST_NAME FROM ARTIST WHERE ARTIST_NAME IN (#bind($names))
+SQLTemplate select = <span class="code-keyword">new</span> SQLTemplate(Artist.class, sql, <span class="code-keyword">false</span>);
+...
+<span class="code-comment">// set parameters and run it...
+</span>Map parameters = <span class="code-keyword">new</span> HashMap();
+parameters.put(<span class="code-quote">"names"</span>, Arrays.asList(<span class="code-keyword">new</span> <span class="code-object">String</span>[] { <span class="code-quote">"Monet"</span>, <span class="code-quote">"Publo Picasso"</span>}));
+select.setParameters(parameters);
+
+DataContext context...;
+List artists = context.performQuery(select);</pre>
+</div></div>
+
+
+<h3><a name="ScriptingSQLTemplate-NullValuesinBindings%23bindEqualand%23bindNotEqualDirectives"></a>Null Values in Bindings - #bindEqual and #bindNotEqual Directives</h3>
+<p>Sometimes when a parameter is NULL, SQL code has to be changed. For example, instead of "WHERE COLUMN = ?", PreparedStatement should be rewritten as "WHERE COLUMN IS NULL", and instead of "WHERE COLUMN &lt;&gt; ?" - as "WHERE COLUMN IS NOT NULL". <tt>#bindEqual</tt> and <tt>#bindNotEqual</tt> directives are used to dynamically generate correct SQL string in this case. Their semantics is the same as #bind directive above, except that they do not require "=", "!=" or "&lt;&gt;" in front of them:</p>
+
+<ul>
+	<li><tt>#bindEqual(value)</tt>, <tt>#bindNotEqual(value)</tt></li>
+	<li><tt>#bindEqual(value jdbcTypeName)</tt>, <tt>#bindNotEqual(value jdbcTypeName)</tt></li>
+	<li><tt>#bindEqual(value jdbcTypeName precision)</tt>, <tt>#bindNotEqual(value jdbcTypeName precision)</tt></li>
+</ul>
+
+
+<h5><a name="ScriptingSQLTemplate-NullValueExamples"></a>Null Value Examples</h5>
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-comment">// build SQLTemplate
+</span><span class="code-comment">// note that <span class="code-quote">"="</span> is ommitted <span class="code-keyword">for</span> the second binding, since it is a part of the directive
+</span><span class="code-object">String</span> sql = "update ARTIST set ARTIST_NAME = #bind($name) where ARTIST_ID #bindEqual($id);
+SQLTemplate update = <span class="code-keyword">new</span> SQLTemplate(Artist.class, sql, <span class="code-keyword">false</span>);
+...
+<span class="code-comment">// set parameters and run it...
+</span>Map parameters = <span class="code-keyword">new</span> HashMap();
+parameters.put(<span class="code-quote">"name"</span>, <span class="code-quote">"Publo Picasso"</span>);
+parameters.put(<span class="code-quote">"id"</span>, <span class="code-keyword">new</span> <span class="code-object">Integer</span>(1001));
+update.setParameters(parameters);
+
+DataContext context...;
+
+<span class="code-comment">// after binding processing PrepapredStatement SQL will look like 
+</span><span class="code-comment">// <span class="code-quote">"update ARTIST set ARTIST_NAME = ? where ARTIST_ID = ?"</span>
+</span>context.performNonSelectingQuery(update);</pre>
+</div></div>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-comment">// build SQLTemplate
+</span><span class="code-comment">// note that <span class="code-quote">"!="</span> is omitted <span class="code-keyword">for</span> the second binding, since it is a part of the directive
+</span><span class="code-object">String</span> sql = <span class="code-quote">"update ARTIST set ARTIST_NAME = #bind($name) where ARTIST_ID #bindNotEqual($id)"</span>;
+SQLTemplate update = <span class="code-keyword">new</span> SQLTemplate(Artist.class, sql, <span class="code-keyword">false</span>);
+...
+<span class="code-comment">// set parameters and run it...
+</span>Map parameters = <span class="code-keyword">new</span> HashMap();
+parameters.put(<span class="code-quote">"name"</span>, <span class="code-quote">"Publo Picasso"</span>);
+parameters.put(<span class="code-quote">"id"</span>, <span class="code-keyword">null</span>);
+update.setParameters(parameters);
+
+DataContext context...;
+
+<span class="code-comment">// after binding processing PrepapredStatement SQL will look like 
+</span><span class="code-comment">// <span class="code-quote">"update ARTIST set ARTIST_NAME = ? where ARTIST_ID IS NOT NULL"</span>
+</span>context.performNonSelectingQuery(update);</pre>
+</div></div>
+
+<h3><a name="ScriptingSQLTemplate-BindingPersistentObjectValues%23bindObjectEqualand%23bindObjectNotEqualdirectives"></a>Binding Persistent Object Values - #bindObjectEqual and #bindObjectNotEqual directives</h3>
+
+<p>It can be tricky to use a Persistent object (or an ObjectId) in a binding, especially for tables with compound primary keys. There are two directives to help with that - <tt>#bindObjectEqual</tt> and <tt>#bindObjectNotEqual</tt>. Long explicit form of these directives is the following:</p>
+
+<ul>
+	<li><tt>#bindObjectEqual(object columns idColumns)</tt></li>
+	<li><tt>#bindObjectNotEqual(object columns idColumns)</tt></li>
+</ul>
+
+
+<p>An <tt>"object"</tt> argument can be one of Persistent, ObjectId or Map. <tt>"columns"</tt> and <tt>"idColumns"</tt> can be of type Object[], Collection or Object. What these directives do is build the SQL to match <tt>"columns"</tt> (i.e. the columns from the SQL query) against <tt>"idColumns"</tt> (i.e. the names of the PK columns for a given entity) for a given object. E.g.:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-object">String</span> sql = <span class="code-quote">"SELECT * FROM PAINTING t0"</span>
+                + <span class="code-quote">" WHERE #bindObjectEqual($a 't0.ARTIST_ID' 'ARTIST_ID' ) ORDER BY PAINTING_ID"</span>;
+SQLTemplate select = <span class="code-keyword">new</span> SQLTemplate(Artist.class, sql);
+
+Artist a = ....
+select.setParameters(Collections.singletonMap(<span class="code-quote">"a"</span>, a));</pre>
+</div></div>
+
+<p>In case of compound PK, arrays can be used for the last two parameters:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-object">String</span> sql = <span class="code-quote">"SELECT * FROM TABLE_X t0"</span>
+                + <span class="code-quote">" WHERE #bindObjectEqual($a ['t0.FK1', 't0.FK2'] ['PK1', 'PK2'] )"</span>;
+SQLTemplate select = <span class="code-keyword">new</span> SQLTemplate(TableX.class, sql);</pre>
+</div></div>
+
+<p>In the case when SQL columns have the same names as PK columns, and there's no naming conflict that would force to use fully qualified column names, a short form of these directives can be used, where column names are inferred from the ObjectId:</p>
+
+<ul>
+	<li><tt>#bindObjectEqual(object)</tt></li>
+	<li><tt>#bindObjectNotEqual(object)</tt></li>
+</ul>
+
+
+<p>E.g.:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-object">String</span> sql = <span class="code-quote">"SELECT * FROM PAINTING WHERE #bindObjectEqual($a) ORDER BY PAINTING_ID"</span>;
+SQLTemplate select = <span class="code-keyword">new</span> SQLTemplate(Artist.class, sql);</pre>
+</div></div>
+
+<h3><a name="ScriptingSQLTemplate-BuildingDynamicSQL%23chainand%23chunkDirectives"></a>Building Dynamic SQL - #chain and #chunk Directives</h3>
+<p>Often it is desirable to exclude parts of the WHERE clause if some parameters are null or not set. This task is not trivial considering the semantics of a SQL statement. Consider this fairly simple example:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-object">String</span> sql = <span class="code-quote">"SELECT DISTINCT"</span>
+   + <span class="code-quote">" #result('ARTIST_ID' '<span class="code-object">int</span>'),"</span>
+   + <span class="code-quote">" #result('ARTIST_NAME' '<span class="code-object">String</span>'),"</span>
+   + <span class="code-quote">" #result('DATE_OF_BIRTH' 'java.util.Date')"</span>
+   + <span class="code-quote">" FROM ARTIST t0"</span>
+   + <span class="code-quote">" WHERE ARTIST_NAME LIKE #bind($name)"</span>
+   + <span class="code-quote">" OR ARTIST_ID &gt; #bind($id)"</span>;
+SQLTemplate select = <span class="code-keyword">new</span> SQLTemplate(Artist.class, sql);</pre>
+</div></div>
+
+<p>It would be nice to exclude ARTIST_NAME matching if "name" parameter is null, exclude ARTIST_ID matching if "id" is null, and exclude the whole WHERE clause if both are null. <tt>#chain</tt> and <tt>#chunk</tt> directives are used for this purpose. Each logical piece is wrapped in a conditional "chunk", and a number of chunks are grouped in a chain. If chain contains no chunks it doesn't render anything enclosed in it.</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-object">String</span> sql = <span class="code-quote">"SELECT DISTINCT"</span>
+   + <span class="code-quote">" #result('ARTIST_ID' '<span class="code-object">int</span>'),"</span>
+   + <span class="code-quote">" #result('ARTIST_NAME' '<span class="code-object">String</span>'),"</span>
+   + <span class="code-quote">" #result('DATE_OF_BIRTH' 'java.util.Date')"</span>
+   + <span class="code-quote">" FROM ARTIST t0"</span>
+   + " #chain('OR' 'WHERE')                              <span class="code-comment">// start chain prefixed by WHERE, 
+</span>                                                         <span class="code-comment">// and joined by OR
+</span>   + <span class="code-quote">" #chunk($name) ARTIST_NAME LIKE #bind($name) #end"</span> <span class="code-comment">// ARTIST_NAME <span class="code-quote">"chunk"</span>
+</span>   + <span class="code-quote">" #chunk($id) ARTIST_ID &gt; #bind($id) #end"</span>          <span class="code-comment">// ARTIST_ID <span class="code-quote">"chunk"</span>
+</span>   + <span class="code-quote">" #end"</span>;                                            <span class="code-comment">// end of chain
+</span>SQLTemplate select = <span class="code-keyword">new</span> SQLTemplate(Artist.class, sql);</pre>
+</div></div>
+</div>
+</div>
+  <div class="clearer">.</div>
+  <div style="height: 12px; background-image: url('../../../../../images/border_bottom.gif'); background-repeat: repeat-x;"></div>
+
+  <div class="smalltext copyright">
+    Copyright &copy;2001-2007 Apache Software Foundation
+  </div>
+
+</body>
+</html>

Propchange: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/SQLTemplate Query/Scripting SQLTemplate/index.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/SQLTemplate Query/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Queries/SQLTemplate%20Query/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/SQLTemplate Query/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/SQLTemplate Query/index.html Sun Jul  8 12:11:31 2007
@@ -0,0 +1,87 @@
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+ 
+     http://www.apache.org/licenses/LICENSE-2.0
+ 
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.
+-->
+<html>
+  <head>
+    <title>Apache Cayenne Documentation - SQLTemplate Query</title>
+    <style type="text/css">@import "../../../../style.css";</style>
+  </head>
+<body>
+  <div class="header">
+    <div style="float: left;"><a href="http://cayenne.apache.org/"><img src="../../../../images/logo.gif" align="absmiddle" border="0"></a></div>
+    <span class="logoSpaceLink"><a href="../../../../index.html">Cayenne User Documentation</a></span><br />
+    <span class="pagetitle">SQLTemplate Query</span>
+  </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../../Documentation/Cayenne Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Design/index.html">Design</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/index.html">Queries</a><ul>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/SelectQuery/index.html">SelectQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/SQLTemplate Query/index.html">SQLTemplate Query</a><ul>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/SQLTemplate Query/SQLTemplate Basics/index.html">SQLTemplate Basics</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/SQLTemplate Query/Scripting SQLTemplate/index.html">Scripting SQLTemplate</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/SQLTemplate Query/Advanced SQLTemplate/index.html">Advanced SQLTemplate</a></li>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/EJBQLQuery/index.html">EJBQLQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/NamedQuery/index.html">NamedQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/ObjectIdQuery/index.html">ObjectIdQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/QueryChain/index.html">QueryChain</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/RelationshipQuery/index.html">RelationshipQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/Queries Stored in DataMap/index.html">Queries Stored in DataMap</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/Caching Query Results/index.html">Caching Query Results</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/Customizing Queries/index.html">Customizing Queries</a></li>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Lifecycle Callbacks/index.html">Lifecycle Callbacks</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/index.html">Performance Tuning</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Caching and Fresh Data/index.html">Caching and Fresh Data</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Maven2 Plugins/index.html">Maven2 Plugins</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Customization/index.html">Customization</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><p>Not all features of SQL can (or should) be mapped in the object model in terms of Persistent objects. For such cases Cayenne provides a powerful mechanism for running both selecting and non-selecting SQL using scriptable SQLTemplate query. The following chapters describe how SQLTemplates can be created and executed, showing how to build SQL dynamically, bind parameters and describe result sets with SQLTemplate scripting features.</p>
+
+<h3><a name="SQLTemplateQuery-Sections"></a>Sections</h3>
+
+<ol>
+	<li><a href="../../../../Documentation/Cayenne Guide/Queries/SQLTemplate Query/SQLTemplate Basics/index.html" title="SQLTemplate Basics">SQLTemplate Basics</a></li>
+	<li><a href="../../../../Documentation/Cayenne Guide/Queries/SQLTemplate Query/Scripting SQLTemplate/index.html" title="Scripting SQLTemplate">Scripting SQLTemplate</a></li>
+	<li><a href="../../../../Documentation/Cayenne Guide/Queries/SQLTemplate Query/Advanced SQLTemplate/index.html" title="Advanced SQLTemplate">Advanced SQLTemplate</a></li>
+</ol>
+</div>
+</div>
+  <div class="clearer">.</div>
+  <div style="height: 12px; background-image: url('../../../../images/border_bottom.gif'); background-repeat: repeat-x;"></div>
+
+  <div class="smalltext copyright">
+    Copyright &copy;2001-2007 Apache Software Foundation
+  </div>
+
+</body>
+</html>

Propchange: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/SQLTemplate Query/index.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/SelectQuery/Parameterized Queries/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Queries/SelectQuery/Parameterized%20Queries/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/SelectQuery/Parameterized Queries/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/SelectQuery/Parameterized Queries/index.html Sun Jul  8 12:11:31 2007
@@ -0,0 +1,154 @@
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+ 
+     http://www.apache.org/licenses/LICENSE-2.0
+ 
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.
+-->
+<html>
+  <head>
+    <title>Apache Cayenne Documentation - Parameterized Queries</title>
+    <style type="text/css">@import "../../../../../style.css";</style>
+  </head>
+<body>
+  <div class="header">
+    <div style="float: left;"><a href="http://cayenne.apache.org/"><img src="../../../../../images/logo.gif" align="absmiddle" border="0"></a></div>
+    <span class="logoSpaceLink"><a href="../../../../../index.html">Cayenne User Documentation</a></span><br />
+    <span class="pagetitle">Parameterized Queries</span>
+  </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../../../Documentation/Cayenne Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Design/index.html">Design</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/index.html">Queries</a><ul>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/SelectQuery/index.html">SelectQuery</a><ul>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/SelectQuery/Parameterized Queries/index.html">Parameterized Queries</a><ul>
+</ul>
+</li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/SelectQuery/Qualifier Expressions/index.html">Qualifier Expressions</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/SelectQuery/Using Orderings/index.html">Using Orderings</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/SelectQuery/SelectQuery Customization/index.html">SelectQuery Customization</a></li>
+</ul>
+</li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/SQLTemplate Query/index.html">SQLTemplate Query</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/EJBQLQuery/index.html">EJBQLQuery</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/NamedQuery/index.html">NamedQuery</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/ObjectIdQuery/index.html">ObjectIdQuery</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/QueryChain/index.html">QueryChain</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/RelationshipQuery/index.html">RelationshipQuery</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/Queries Stored in DataMap/index.html">Queries Stored in DataMap</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/Caching Query Results/index.html">Caching Query Results</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/Customizing Queries/index.html">Customizing Queries</a></li>
+</ul>
+</li>
+<li><a href="../../../../../Documentation/Cayenne Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Lifecycle Callbacks/index.html">Lifecycle Callbacks</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Performance Tuning/index.html">Performance Tuning</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Caching and Fresh Data/index.html">Caching and Fresh Data</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Maven2 Plugins/index.html">Maven2 Plugins</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Customization/index.html">Customization</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><p>SelectQuery objects can be rather complex. They may contain long qualifiers and lots of tuning parameters. Parameterized Queries feature addresses reusability of complex queries. With this feature, for each group of queries that differ only in the values used in the qualifier, a developer may create a single shared "prototype" or "template" query, and use it later as a factory for other queries. All settings configured in the prototype object will be passed to the final queries. Qualifier of the prototype query may use named parameters that are substituted for real values when a final query is created from the prototype.</p>
+<table cellpadding='5' width='85%' cellspacing='8px' class='infoMacro' border="0" align='center'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="../../../../../images/emoticons/information.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>"Prototype" queries are normally created in CayenneModeler and stored in the DataMap XML file. "Queries Stored in DataMap" chapter describes how to use such templates. This chapter shows how to create them on the spot using the API calls.</td></tr></table>
+
+<p>Building a prototype query using <tt>Expression.fromString(..)</tt>:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">import</span> org.apache.cayenne.exp.Expression;
+<span class="code-keyword">import</span> org.apache.cayenne.query.SelectQuery;
+...
+<span class="code-comment">// create a qualifier with two named parameters: <span class="code-quote">"pname"</span> and <span class="code-quote">"aname"</span>
+</span>Expression qual = Expression.fromString(<span class="code-quote">"paintingTitle = $pname or toArtist.artistName = $aname"</span>);
+
+<span class="code-comment">// build a query prototype of a query - simply another select query
+</span>SelectQuery proto = <span class="code-keyword">new</span> SelectQuery(Painting.class, qual);
+proto.setDistinct(<span class="code-keyword">true</span>);</pre>
+</div></div>
+
+<p>Same example but using ExpressionFactory:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">import</span> java.util.*;
+<span class="code-keyword">import</span> org.apache.cayenne.exp.Expression;
+<span class="code-keyword">import</span> org.apache.cayenne.exp.ExpressionFactory;
+<span class="code-keyword">import</span> org.apache.cayenne.exp.ExpressionParameter;
+<span class="code-keyword">import</span> org.apache.cayenne.query.SelectQuery;
+...
+<span class="code-comment">// create a qualifier with two named parameters: 
+</span><span class="code-comment">//  <span class="code-quote">"pname"</span> and <span class="code-quote">"aname"</span>
+</span>List list = <span class="code-keyword">new</span> ArrayList();
+list.add(ExpressionFactory.matchExp(<span class="code-quote">"paintingTitle"</span>, 
+         <span class="code-keyword">new</span> ExpressionParameter(<span class="code-quote">"pname"</span>)));
+list.add(ExpressionFactory.matchExp(<span class="code-quote">"toArtist.artistName"</span>, 
+         <span class="code-keyword">new</span> ExpressionParameter(<span class="code-quote">"aname"</span>)));
+Expression qual = ExpressionFactory.joinExp(Expression.OR, list);
+
+<span class="code-comment">// build a query prototype of a query - simply another select query
+</span>SelectQuery proto = <span class="code-keyword">new</span> SelectQuery(Painting.class, qual);
+proto.setDistinct(<span class="code-keyword">true</span>);</pre>
+</div></div>
+<p>Prototype built in the example above can be used to create other queries. Relevalnt API is:</p>
+
+<ul>
+	<li>public SelectQuery <b>SelectQuery.queryWithParameters</b>(Map parameters, boolean pruneMissing)<br/>
+      Creates and returns a new SelectQuery using current query as a prototype. Map of parameters is used to substitute named parameters in the qualifier with the real values. Returned query is a separate instance and can be further customized without affecting the prototype. If <tt>pruneMissing</tt> is true and some of the named parameters are missing from the parameters map, Cayenne would prune expressions that can not be resolved. If pruneMissing is set to false, the method would throw an exception unless all the named parameters can be resolved.</li>
+	<li>public SelectQuery <b>SelectQuery.queryWithParameters</b>(Map parameters)<br/>
+      A shortcut for <tt>public SelectQuery queryWithParameters(Map parameters, true)</tt>.</li>
+</ul>
+
+
+<p>Example of using queryWithParameters is shown below:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">import</span> java.util.Map;
+<span class="code-keyword">import</span> java.util.HashMap;
+<span class="code-keyword">import</span> org.apache.cayenne.query.SelectQuery;
+...
+SelectQuery proto = ... <span class="code-comment">// <span class="code-keyword">this</span> was built in the example above
+</span>
+<span class="code-comment">// create a query
+</span>Map params1 = <span class="code-keyword">new</span> HashMap();
+params1.put(<span class="code-quote">"aname"</span>, <span class="code-quote">"Dali"</span>);
+SelectQuery query1 = proto.queryWithParameters(params1);
+
+<span class="code-comment">// further customize returned query 
+</span><span class="code-comment">// without affecting the prototype
+</span>query1.setFetchLimit(100);
+... 
+<span class="code-comment">// create another query with a different set of parameters
+</span>Map params2 = <span class="code-keyword">new</span> HashMap();
+params2.put(<span class="code-quote">"aname"</span>, <span class="code-quote">"Monet"</span>);
+params2.put(<span class="code-quote">"pname"</span>, <span class="code-quote">"The Beach at Trouville"</span>);
+SelectQuery query2 = proto.queryWithParameters(params2);
+...</pre>
+</div></div></div>
+</div>
+  <div class="clearer">.</div>
+  <div style="height: 12px; background-image: url('../../../../../images/border_bottom.gif'); background-repeat: repeat-x;"></div>
+
+  <div class="smalltext copyright">
+    Copyright &copy;2001-2007 Apache Software Foundation
+  </div>
+
+</body>
+</html>

Propchange: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/SelectQuery/Parameterized Queries/index.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/SelectQuery/Qualifier Expressions/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Queries/SelectQuery/Qualifier%20Expressions/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/SelectQuery/Qualifier Expressions/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/SelectQuery/Qualifier Expressions/index.html Sun Jul  8 12:11:31 2007
@@ -0,0 +1,97 @@
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+ 
+     http://www.apache.org/licenses/LICENSE-2.0
+ 
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.
+-->
+<html>
+  <head>
+    <title>Apache Cayenne Documentation - Qualifier Expressions</title>
+    <style type="text/css">@import "../../../../../style.css";</style>
+  </head>
+<body>
+  <div class="header">
+    <div style="float: left;"><a href="http://cayenne.apache.org/"><img src="../../../../../images/logo.gif" align="absmiddle" border="0"></a></div>
+    <span class="logoSpaceLink"><a href="../../../../../index.html">Cayenne User Documentation</a></span><br />
+    <span class="pagetitle">Qualifier Expressions</span>
+  </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../../../Documentation/Cayenne Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Design/index.html">Design</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/index.html">Queries</a><ul>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/SelectQuery/index.html">SelectQuery</a><ul>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/SelectQuery/Parameterized Queries/index.html">Parameterized Queries</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/SelectQuery/Qualifier Expressions/index.html">Qualifier Expressions</a><ul>
+</ul>
+</li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/SelectQuery/Using Orderings/index.html">Using Orderings</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/SelectQuery/SelectQuery Customization/index.html">SelectQuery Customization</a></li>
+</ul>
+</li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/SQLTemplate Query/index.html">SQLTemplate Query</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/EJBQLQuery/index.html">EJBQLQuery</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/NamedQuery/index.html">NamedQuery</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/ObjectIdQuery/index.html">ObjectIdQuery</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/QueryChain/index.html">QueryChain</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/RelationshipQuery/index.html">RelationshipQuery</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/Queries Stored in DataMap/index.html">Queries Stored in DataMap</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/Caching Query Results/index.html">Caching Query Results</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/Customizing Queries/index.html">Customizing Queries</a></li>
+</ul>
+</li>
+<li><a href="../../../../../Documentation/Cayenne Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Lifecycle Callbacks/index.html">Lifecycle Callbacks</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Performance Tuning/index.html">Performance Tuning</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Caching and Fresh Data/index.html">Caching and Fresh Data</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Maven2 Plugins/index.html">Maven2 Plugins</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Customization/index.html">Customization</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><table cellpadding='5' width='85%' cellspacing='8px' class='noteMacro' border="0" align='center'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="../../../../../images/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>This chapter is dedicated to the use of expressions as qualifiers. A detailed discussion on expressions in general is provided at <a href="../../../../../Documentation/Cayenne Guide/Expressions/index.html" title="Expressions">Expressions</a>.</td></tr></table>
+
+<p>The previous chapter showed how to build a query to fetch all data from a single table. In most situations though only a subset of data matching a certain criteria is needed. Cayenne provides an expressions package to control the filtering behavior of the queries. Expressions applied to queries are called "qualifiers".</p>
+
+<p>SelectQuery provides a few ways to initialize and modify the qualifier:</p>
+
+<ul>
+	<li>public <b>SelectQuery</b>(Class objectClass, Expression e)<br/>
+      Passing expression as a second argument in constructor.</li>
+	<li>public void <b>setQualifier</b>(Expression qualifier)<br/>
+      Explicitly setting the qualifier expression.</li>
+	<li>public void <b>andQualifier</b>(Expression e)<br/>
+      Adding an expression to an already existing qualifier using logical AND.</li>
+	<li>public void <b>orQualifier</b>(Expression e)<br/>
+      Adding an expression to an already existing qualifier using logical OR.</li>
+</ul>
+</div>
+</div>
+  <div class="clearer">.</div>
+  <div style="height: 12px; background-image: url('../../../../../images/border_bottom.gif'); background-repeat: repeat-x;"></div>
+
+  <div class="smalltext copyright">
+    Copyright &copy;2001-2007 Apache Software Foundation
+  </div>
+
+</body>
+</html>

Propchange: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/SelectQuery/Qualifier Expressions/index.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/SelectQuery/SelectQuery Customization/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Queries/SelectQuery/SelectQuery%20Customization/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/SelectQuery/SelectQuery Customization/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/SelectQuery/SelectQuery Customization/index.html Sun Jul  8 12:11:31 2007
@@ -0,0 +1,96 @@
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+ 
+     http://www.apache.org/licenses/LICENSE-2.0
+ 
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.
+-->
+<html>
+  <head>
+    <title>Apache Cayenne Documentation - SelectQuery Customization</title>
+    <style type="text/css">@import "../../../../../style.css";</style>
+  </head>
+<body>
+  <div class="header">
+    <div style="float: left;"><a href="http://cayenne.apache.org/"><img src="../../../../../images/logo.gif" align="absmiddle" border="0"></a></div>
+    <span class="logoSpaceLink"><a href="../../../../../index.html">Cayenne User Documentation</a></span><br />
+    <span class="pagetitle">SelectQuery Customization</span>
+  </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../../../Documentation/Cayenne Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Design/index.html">Design</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/index.html">Queries</a><ul>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/SelectQuery/index.html">SelectQuery</a><ul>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/SelectQuery/Parameterized Queries/index.html">Parameterized Queries</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/SelectQuery/Qualifier Expressions/index.html">Qualifier Expressions</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/SelectQuery/Using Orderings/index.html">Using Orderings</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/SelectQuery/SelectQuery Customization/index.html">SelectQuery Customization</a><ul>
+</ul>
+</li>
+</ul>
+</li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/SQLTemplate Query/index.html">SQLTemplate Query</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/EJBQLQuery/index.html">EJBQLQuery</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/NamedQuery/index.html">NamedQuery</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/ObjectIdQuery/index.html">ObjectIdQuery</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/QueryChain/index.html">QueryChain</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/RelationshipQuery/index.html">RelationshipQuery</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/Queries Stored in DataMap/index.html">Queries Stored in DataMap</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/Caching Query Results/index.html">Caching Query Results</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/Customizing Queries/index.html">Customizing Queries</a></li>
+</ul>
+</li>
+<li><a href="../../../../../Documentation/Cayenne Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Lifecycle Callbacks/index.html">Lifecycle Callbacks</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Performance Tuning/index.html">Performance Tuning</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Caching and Fresh Data/index.html">Caching and Fresh Data</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Maven2 Plugins/index.html">Maven2 Plugins</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Customization/index.html">Customization</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><p><a href="../../../../../Documentation/Cayenne Guide/Queries/SelectQuery/index.html" title="SelectQuery">SelectQueries</a> allow to fine tune the behavior of the fetch using the following API:</p>
+<ul>
+	<li>public void <b>setFetchLimit</b>(int fetchLimit)<br/>
+ If set to a value greater than zero, tells Cayenne that query should never retrieve more than X objects (X == fetchLimit) from the database. If a result set contains more rows, they are simply ignored and never read. This is a "safety" feature that can be used to prevent the application from crashing when an unexpectedly high number of records exists for a given query.</li>
+</ul>
+
+
+<ul>
+	<li>public void <b>setDistinct</b>(boolean distinct)<br/>
+ If set to true (default is false), tells Cayenne that query should fetch distinct rows.</li>
+	<li>public void <b>setFetchingDataRows</b>(boolean flag)<br/>
+ If set to true (default is false), tells Cayenne that instead of creating DataObjects, it should fetch "data rows" - dictionaries containing database values, using table column names for the keys. "Performance Tuning" chapter explains how data rows can improve performance and how and when to use them.</li>
+	<li>public void <b>setPageSize</b>(int pageSize)<br/>
+ If set to a value greater than zero, tells Cayenne that query should do a "lazy" fetch, breaking result into "pages". <a href="../../../../../Documentation/Cayenne Guide/Performance Tuning/index.html" title="Performance Tuning">Performance Tuning</a> has a detailed discussion of paged queries.</li>
+</ul>
+</div>
+</div>
+  <div class="clearer">.</div>
+  <div style="height: 12px; background-image: url('../../../../../images/border_bottom.gif'); background-repeat: repeat-x;"></div>
+
+  <div class="smalltext copyright">
+    Copyright &copy;2001-2007 Apache Software Foundation
+  </div>
+
+</body>
+</html>

Propchange: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/SelectQuery/SelectQuery Customization/index.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/SelectQuery/Using Orderings/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Queries/SelectQuery/Using%20Orderings/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/SelectQuery/Using Orderings/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/SelectQuery/Using Orderings/index.html Sun Jul  8 12:11:31 2007
@@ -0,0 +1,121 @@
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+ 
+     http://www.apache.org/licenses/LICENSE-2.0
+ 
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.
+-->
+<html>
+  <head>
+    <title>Apache Cayenne Documentation - Using Orderings</title>
+    <style type="text/css">@import "../../../../../style.css";</style>
+  </head>
+<body>
+  <div class="header">
+    <div style="float: left;"><a href="http://cayenne.apache.org/"><img src="../../../../../images/logo.gif" align="absmiddle" border="0"></a></div>
+    <span class="logoSpaceLink"><a href="../../../../../index.html">Cayenne User Documentation</a></span><br />
+    <span class="pagetitle">Using Orderings</span>
+  </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../../../Documentation/Cayenne Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Design/index.html">Design</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/index.html">Queries</a><ul>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/SelectQuery/index.html">SelectQuery</a><ul>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/SelectQuery/Parameterized Queries/index.html">Parameterized Queries</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/SelectQuery/Qualifier Expressions/index.html">Qualifier Expressions</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/SelectQuery/Using Orderings/index.html">Using Orderings</a><ul>
+</ul>
+</li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/SelectQuery/SelectQuery Customization/index.html">SelectQuery Customization</a></li>
+</ul>
+</li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/SQLTemplate Query/index.html">SQLTemplate Query</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/EJBQLQuery/index.html">EJBQLQuery</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/NamedQuery/index.html">NamedQuery</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/ObjectIdQuery/index.html">ObjectIdQuery</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/QueryChain/index.html">QueryChain</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/RelationshipQuery/index.html">RelationshipQuery</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/Queries Stored in DataMap/index.html">Queries Stored in DataMap</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/Caching Query Results/index.html">Caching Query Results</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/Customizing Queries/index.html">Customizing Queries</a></li>
+</ul>
+</li>
+<li><a href="../../../../../Documentation/Cayenne Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Lifecycle Callbacks/index.html">Lifecycle Callbacks</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Performance Tuning/index.html">Performance Tuning</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Caching and Fresh Data/index.html">Caching and Fresh Data</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Maven2 Plugins/index.html">Maven2 Plugins</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Customization/index.html">Customization</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><p>To sort SelectQuery results, orderings are used. Orderings use path expressions discussed in the previous section to identify the attributes that must be used in sorting. For example to order results by artist name, the following code can be used:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">import</span> org.apache.cayenne.query.SelectQuery;
+...
+SelectQuery query = <span class="code-keyword">new</span> SelectQuery(<span class="code-quote">"Artist"</span>);
+
+<span class="code-comment">// add ordering by Artist name:
+</span>query.addOrdering(<span class="code-quote">"artistName"</span>, <span class="code-keyword">true</span>);</pre>
+</div></div>
+
+<p>Orderings also support in-memory sorting of lists of Java Beans (all DataObjects are normally Java Beans, since they has set/get method pairs for all the properties). For instance to sort with a single ordering, the following code might be used:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">import</span> org.apache.cayenne.query.Ordering;
+...
+<span class="code-comment">// assume <span class="code-keyword">this</span> is a properly initialized list of Artists
+</span>List list = ...; 
+
+<span class="code-comment">// creates asending ordering by Artist name
+</span>Ordering ordering = <span class="code-keyword">new</span> Ordering(<span class="code-quote">"artistName"</span>, <span class="code-keyword">true</span>);
+
+<span class="code-comment">// orders a list
+</span>ordering.orderList(list);</pre>
+</div></div>
+
+<p>If there is a need to sort on more than one object property, multiple Orderings can be passed as a List to a static method <tt>orderList(List, List)</tt>. The cost of adding new Orderings decreases, as the list of objects ends up being sorted by the first Ordering, then, if any two objects are equal for first Ordering, by the second, and so on.</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">import</span> org.apache.cayenne.query.Ordering;
+...
+<span class="code-comment">// assume <span class="code-keyword">this</span> is a properly initialized list of Paintings
+</span>List list = ...; 
+
+List orderings = <span class="code-keyword">new</span> ArrayList();
+orderings.add(<span class="code-keyword">new</span> Ordering(<span class="code-quote">"paintingTitle"</span>, <span class="code-keyword">true</span>));
+orderings.add(<span class="code-keyword">new</span> Ordering(<span class="code-quote">"estimatedPrice"</span>, <span class="code-keyword">false</span>));
+
+<span class="code-comment">// orders a list aplying multiple orderings
+</span>Ordering.orderList(list, orderings);</pre>
+</div></div></div>
+</div>
+  <div class="clearer">.</div>
+  <div style="height: 12px; background-image: url('../../../../../images/border_bottom.gif'); background-repeat: repeat-x;"></div>
+
+  <div class="smalltext copyright">
+    Copyright &copy;2001-2007 Apache Software Foundation
+  </div>
+
+</body>
+</html>

Propchange: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/SelectQuery/Using Orderings/index.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/SelectQuery/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Queries/SelectQuery/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/SelectQuery/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/SelectQuery/index.html Sun Jul  8 12:11:31 2007
@@ -0,0 +1,150 @@
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+ 
+     http://www.apache.org/licenses/LICENSE-2.0
+ 
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.
+-->
+<html>
+  <head>
+    <title>Apache Cayenne Documentation - SelectQuery</title>
+    <style type="text/css">@import "../../../../style.css";</style>
+  </head>
+<body>
+  <div class="header">
+    <div style="float: left;"><a href="http://cayenne.apache.org/"><img src="../../../../images/logo.gif" align="absmiddle" border="0"></a></div>
+    <span class="logoSpaceLink"><a href="../../../../index.html">Cayenne User Documentation</a></span><br />
+    <span class="pagetitle">SelectQuery</span>
+  </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../../Documentation/Cayenne Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Design/index.html">Design</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/index.html">Queries</a><ul>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/SelectQuery/index.html">SelectQuery</a><ul>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/SelectQuery/Parameterized Queries/index.html">Parameterized Queries</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/SelectQuery/Qualifier Expressions/index.html">Qualifier Expressions</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/SelectQuery/Using Orderings/index.html">Using Orderings</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/SelectQuery/SelectQuery Customization/index.html">SelectQuery Customization</a></li>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/SQLTemplate Query/index.html">SQLTemplate Query</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/EJBQLQuery/index.html">EJBQLQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/NamedQuery/index.html">NamedQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/ObjectIdQuery/index.html">ObjectIdQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/QueryChain/index.html">QueryChain</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/RelationshipQuery/index.html">RelationshipQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/Queries Stored in DataMap/index.html">Queries Stored in DataMap</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/Caching Query Results/index.html">Caching Query Results</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/Customizing Queries/index.html">Customizing Queries</a></li>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Lifecycle Callbacks/index.html">Lifecycle Callbacks</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/index.html">Performance Tuning</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Caching and Fresh Data/index.html">Caching and Fresh Data</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Maven2 Plugins/index.html">Maven2 Plugins</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Customization/index.html">Customization</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><p>The most commonly used query is SelectQuery. It is a descriptor that allows DataContext to fetch lists of DataObjects of the right type matching the specified criteria. SelectQuery together with the DataMap provides just enough information to the Cayenne runtime objects to build the right SQL SELECT statement and control various execution parameters.</p>
+
+<h3><a name="SelectQuery-SelectQueryParts"></a>SelectQuery Parts</h3>
+
+<p>A SelectQuery consists of a root object, qualifier expression and orderings list. Here is a logical correspondence of Cayenne SelectQuery parts and SQL constructs:</p>
+<table class='confluenceTable'><tbody>
+<tr>
+<th class='confluenceTh'> Cayenne SelectQuery </th>
+<th class='confluenceTh'> SQL SELECT statement </th>
+<th class='confluenceTh'> Required </th>
+</tr>
+<tr>
+<td class='confluenceTd'> Root </td>
+<td class='confluenceTd'> FROM clause </td>
+<td class='confluenceTd'> yes </td>
+</tr>
+<tr>
+<td class='confluenceTd'> Qualifier Expression </td>
+<td class='confluenceTd'> WHERE clause </td>
+<td class='confluenceTd'> no </td>
+</tr>
+<tr>
+<td class='confluenceTd'> Orderings </td>
+<td class='confluenceTd'> ORDER BY clause </td>
+<td class='confluenceTd'> no </td>
+</tr>
+</tbody></table>
+<p>The only required query part is root. Query root tells Cayenne what kind of objects to fetch. It can be one of the following:</p>
+<ul>
+	<li><em>(most commonly used)</em> Java class for the type of persistent objects in question.</li>
+	<li>ObjEntity that provides the mapping for the class in question.</li>
+	<li>A String that is an ObjEntity name.</li>
+</ul>
+
+
+<p>SelectQuery provides constructors for all three types. For example:</p>
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">import</span> org.apache.cayenne.query.SelectQuery;
+...
+<span class="code-comment">// <span class="code-keyword">this</span> is a valid Cayenne query that would allow to fetch
+</span><span class="code-comment">// all records from the ARTIST table as Artist objects
+</span>SelectQuery query = <span class="code-keyword">new</span> SelectQuery(Artist.class);</pre>
+</div></div>
+<p>Other components of the SelectQuery are discussed in the following sections.</p>
+
+<h3><a name="SelectQuery-ExecutingSelectQueries"></a>Executing SelectQueries</h3>
+
+<p>As mentioned earlier, queries are executed via <tt>DataContext.performQuery()</tt>. For instance to fetch all Artists existing in the database the following code is used:</p>
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">import</span> org.apache.cayenne.query.SelectQuery;
+<span class="code-keyword">import</span> org.apache.cayenne.access.DataContext;
+<span class="code-keyword">import</span> java.util.List;
+...
+DataContext ctxt; <span class="code-comment">// assume <span class="code-keyword">this</span> exists
+</span>SelectQuery query = <span class="code-keyword">new</span> SelectQuery(Artist.class);
+
+<span class="code-comment">// The query would fetch *ALL* rows from the ARTIST table
+</span><span class="code-comment">// The list returned contains Artist objects, one object per row
+</span>List artists = ctxt.performQuery(query);</pre>
+</div></div>
+<p>There is a special case when a query is run using <tt>DataContext.performIteratedQuery()</tt>. This is discussed in "Performance Tuning" chapter.</p>
+
+<h3><a name="SelectQuery-Sections"></a>Sections</h3>
+
+
+<ol>
+	<li><a href="../../../../Documentation/Cayenne Guide/Queries/SelectQuery/Parameterized Queries/index.html" title="Parameterized Queries">Parameterized Queries</a></li>
+	<li><a href="../../../../Documentation/Cayenne Guide/Queries/SelectQuery/Qualifier Expressions/index.html" title="Qualifier Expressions">Qualifier Expressions</a></li>
+	<li><a href="../../../../Documentation/Cayenne Guide/Queries/SelectQuery/Using Orderings/index.html" title="Using Orderings">Using Orderings</a></li>
+	<li><a href="../../../../Documentation/Cayenne Guide/Queries/SelectQuery/SelectQuery Customization/index.html" title="SelectQuery Customization">SelectQuery Customization</a></li>
+</ol>
+</div>
+</div>
+  <div class="clearer">.</div>
+  <div style="height: 12px; background-image: url('../../../../images/border_bottom.gif'); background-repeat: repeat-x;"></div>
+
+  <div class="smalltext copyright">
+    Copyright &copy;2001-2007 Apache Software Foundation
+  </div>
+
+</body>
+</html>

Propchange: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/SelectQuery/index.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Queries/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/index.html Sun Jul  8 12:11:31 2007
@@ -0,0 +1,116 @@
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+ 
+     http://www.apache.org/licenses/LICENSE-2.0
+ 
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.
+-->
+<html>
+  <head>
+    <title>Apache Cayenne Documentation - Queries</title>
+    <style type="text/css">@import "../../../style.css";</style>
+  </head>
+<body>
+  <div class="header">
+    <div style="float: left;"><a href="http://cayenne.apache.org/"><img src="../../../images/logo.gif" align="absmiddle" border="0"></a></div>
+    <span class="logoSpaceLink"><a href="../../../index.html">Cayenne User Documentation</a></span><br />
+    <span class="pagetitle">Queries</span>
+  </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../Documentation/Cayenne Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Design/index.html">Design</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Queries/index.html">Queries</a><ul>
+<li><a href="../../../Documentation/Cayenne Guide/Queries/SelectQuery/index.html">SelectQuery</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Queries/SQLTemplate Query/index.html">SQLTemplate Query</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Queries/EJBQLQuery/index.html">EJBQLQuery</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Queries/NamedQuery/index.html">NamedQuery</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Queries/ObjectIdQuery/index.html">ObjectIdQuery</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Queries/QueryChain/index.html">QueryChain</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Queries/RelationshipQuery/index.html">RelationshipQuery</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Queries/Queries Stored in DataMap/index.html">Queries Stored in DataMap</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Queries/Caching Query Results/index.html">Caching Query Results</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Queries/Customizing Queries/index.html">Customizing Queries</a></li>
+</ul>
+</li>
+<li><a href="../../../Documentation/Cayenne Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Lifecycle Callbacks/index.html">Lifecycle Callbacks</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Performance Tuning/index.html">Performance Tuning</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Caching and Fresh Data/index.html">Caching and Fresh Data</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Maven2 Plugins/index.html">Maven2 Plugins</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Customization/index.html">Customization</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><h2><a name="Queries-Queries"></a>Queries</h2>
+<p>Queries are Cayenne abstraction for communicating with an external data storage. Queries are Java objects that are generally independent from the SQL dialect used by the target database. Cayenne includes a number of standard queries in the <tt>org.apache.cayenne.query</tt> package. Many of them are only used internally. Here we describe the queries that can be useful in the application.</p>
+
+<h3><a name="Queries-GeneralPurposeQueries"></a>General Purpose Queries</h3>
+
+<ul>
+	<li><a href="../../../Documentation/Cayenne Guide/Queries/SelectQuery/index.html" title="SelectQuery">SelectQuery</a> is an "object query" based on some Java class. All its parameters are specified in terms of the properties of this Java class. It is completely portable and SQL-free. SelectQuery is the most commonly used out of the three queries discussed here, as it stays as close to the object model as possible. For most tasks it should be considered the first choice. Other types of queries should be used only if SelectQuery can't address a particular application need.</li>
+	<li><a href="../../../Documentation/Cayenne Guide/Queries/SQLTemplate Query/index.html" title="SQLTemplate Query">SQLTemplate Query</a> is a scriptable raw SQL query, that can be both selecting and non-selecting. Main use of SQLTemplate is to create complex SQL queries with structure that has no direct correspondence with the object model. SQLTemplate allows customizing SQL dialect code for more than one target database, encapsulating this fact from the callers. Just like other types of queries, SQLTemplates can be mapped in CayenneModeler, so the code can stay free from SQL building.</li>
+	<li><a href="../../../Documentation/Cayenne Guide/Stored Procedures/index.html" title="Stored Procedures">ProcedureQuery</a> is intended to invoke mapped stored procedures. It can be selecting or non-selecting, or even contain multiple result sets and update counts, depending on what the target procedure does.</li>
+	<li><a href="../../../Documentation/Cayenne Guide/Queries/EJBQLQuery/index.html" title="EJBQLQuery">EJBQLQuery</a> is an object query with a SQL-like syntax standardized by the JPA specification. It is a SelectQuery on steroids.</li>
+</ul>
+
+
+<h3><a name="Queries-OtherHelpfulQueries"></a>Other Helpful Queries</h3>
+
+<ul>
+	<li><a href="../../../Documentation/Cayenne Guide/Queries/QueryChain/index.html" title="QueryChain">QueryChain</a> is a Query that is itself a collection of other queries. Its intention is to execute multiple queries in a single batch.</li>
+	<li><a href="../../../Documentation/Cayenne Guide/Queries/ObjectIdQuery/index.html" title="ObjectIdQuery">ObjectIdQuery</a> is a query that selects objects matching an ObjectId.</li>
+	<li><a href="../../../Documentation/Cayenne Guide/Queries/RelationshipQuery/index.html" title="RelationshipQuery">RelationshipQuery</a> is a query that fetches object(s) related to a single given object via a mapped ObjRelationship.</li>
+	<li><a href="../../../Documentation/Cayenne Guide/Queries/NamedQuery/index.html" title="NamedQuery">NamedQuery</a> is a query that is a reference to another query stored in the DataMap.</li>
+</ul>
+
+
+
+<h3><a name="Queries-CustomQueries"></a>Custom Queries</h3>
+
+<p>To extend standard Query functionality, users can create <a href="../../../Documentation/Cayenne Guide/Queries/Customizing Queries/index.html" title="Customizing Queries">Custom Queries</a> that implement <tt>org.apache.cayenne.query.Query</tt> interface.</p>
+
+<h3><a name="Queries-Sections"></a>Sections</h3>
+
+<ol>
+	<li><a href="../../../Documentation/Cayenne Guide/Queries/SelectQuery/index.html" title="SelectQuery">SelectQuery</a></li>
+	<li><a href="../../../Documentation/Cayenne Guide/Queries/SQLTemplate Query/index.html" title="SQLTemplate Query">SQLTemplate Query</a></li>
+	<li><a href="../../../Documentation/Cayenne Guide/Queries/EJBQLQuery/index.html" title="EJBQLQuery">EJBQLQuery</a></li>
+	<li><a href="../../../Documentation/Cayenne Guide/Queries/NamedQuery/index.html" title="NamedQuery">NamedQuery</a></li>
+	<li><a href="../../../Documentation/Cayenne Guide/Queries/ObjectIdQuery/index.html" title="ObjectIdQuery">ObjectIdQuery</a></li>
+	<li><a href="../../../Documentation/Cayenne Guide/Queries/QueryChain/index.html" title="QueryChain">QueryChain</a></li>
+	<li><a href="../../../Documentation/Cayenne Guide/Queries/RelationshipQuery/index.html" title="RelationshipQuery">RelationshipQuery</a></li>
+	<li><a href="../../../Documentation/Cayenne Guide/Queries/Queries Stored in DataMap/index.html" title="Queries Stored in DataMap">Storing Queries in DataMap</a></li>
+	<li><a href="../../../Documentation/Cayenne Guide/Queries/Caching Query Results/index.html" title="Caching Query Results">Caching Query Results</a></li>
+	<li><a href="../../../Documentation/Cayenne Guide/Queries/Customizing Queries/index.html" title="Customizing Queries">Customizing Queries</a></li>
+</ol>
+
+</div>
+</div>
+  <div class="clearer">.</div>
+  <div style="height: 12px; background-image: url('../../../images/border_bottom.gif'); background-repeat: repeat-x;"></div>
+
+  <div class="smalltext copyright">
+    Copyright &copy;2001-2007 Apache Software Foundation
+  </div>
+
+</body>
+</html>

Propchange: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/index.html
------------------------------------------------------------------------------
    svn:eol-style = native



Mime
View raw message