You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cayenne.apache.org by aa...@apache.org on 2013/02/19 14:19:52 UTC
svn commit: r1447705 -
/cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/queries.xml
Author: aadamchik
Date: Tue Feb 19 13:19:52 2013
New Revision: 1447705
URL: http://svn.apache.org/r1447705
Log:
docs
* SQLTemplate #result
(cherry picked from commit 1f30942116382d81008080a35fdcb89a583ccf85)
Modified:
cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/queries.xml
Modified: cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/queries.xml
URL: http://svn.apache.org/viewvc/cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/queries.xml?rev=1447705&r1=1447704&r2=1447705&view=diff
==============================================================================
--- cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/queries.xml (original)
+++ cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/queries.xml Tue Feb 19 13:19:52 2013
@@ -193,7 +193,7 @@ query.setParameters(Collections.singleto
<title>Directives</title>
<para>These are the custom directives used to customize SQLTemplate parsing and
integrate with the JDBC layer:<table frame="void">
- <caption>cgen optional parameters</caption>
+ <caption>SQLTemplate Directives</caption>
<col width="28%"/>
<col width="33%"/>
<col width="39%"/>
@@ -316,6 +316,70 @@ query.setParameters(Collections.singleto
<td>Same as #bindObjectEqual above, only generates "not equal" operator
for value comparison (or IS NOT NULL).</td>
</tr>
+ <tr>
+ <td>
+ <para><code>#result(column)</code></para>
+ <para><code>#result(column javaType)</code></para>
+ <para><code>#result(column javaType alias)</code></para>
+ </td>
+ <td>
+ <para><code>#result('NAME')</code></para>
+ <para><code>#result('DATE_OF_BIRTH' 'java.util.Date') </code></para>
+ <para><code>#result('DOB' 'java.util.Date' 'DATE_OF_BIRTH')
+ </code></para>
+ </td>
+ <td>
+ <para>Renders a column in SELECT clause of the query and maps it to
+ a key in the result DataRow. Also ensures the value read is of
+ the correct type. This allows to create a DataRow (and
+ ultimately - a persistent object) from an arbitrary
+ ResultSet.</para>
+ <para>A <code>javaType</code> argument is a fully-qualified Java
+ class name for a given result column. 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.</para>
+ <para><code>alias</code> argument specifies both the SQL alias of
+ the column and the value key in the DataRow.</para>
+ <para>Here is a complete query example using #result:</para>
+ <para><code>SELECT #result('ID' 'int'), #result('NAME' 'String'),
+ #result('DATE_OF_BIRTH' 'java.util.Date') FROM
+ ARTIST"</code></para>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <para><code>#chain(operator) ... #end</code></para>
+ <para><code>#chain(operator prefix) ... #end</code></para>
+ <para><code>#chunk() ... #end</code></para>
+ <para><code>#chunk(param) ... #end</code></para>
+ </td>
+ <td>
+ <para><code>#chain('OR' 'WHERE') #chunk($name) NAME LIKE
+ #bind($name) #end" #chunk($id) ARTIST_ID > #bind($id) #end"
+ #end" </code></para>
+ </td>
+ <td>
+ <para><code>#chain</code> and <code>#chunk</code> directives are
+ used for conditional inclusion of SQL code. They are often used
+ together with <code>#chain</code> wrapping multiple
+ <code>#chunks</code>.</para>
+ <para>A chunk evaluates its parameter expression and if it is NULL
+ suppresses rendering of the enclosed SQL block. A chain renders
+ its <code>prefix</code> and its chunks joined by the
+ <code>operator</code>. If all the chunks are suppressed, the
+ chain itself is suppressed. </para>
+ <para>This allows to work with otherwise hard to script SQL
+ semantics. E.g. a WHERE clause can contain multiple conditions
+ joined with AND or OR. Application code would like to exclude a
+ condition if its right-hand parameter is not present (similar to
+ Expression pruning discussed above). If all conditions are
+ excluded, the entire WHERE clause should be excluded.
+ chain/chunk allows to do that.</para>
+ </td>
+ </tr>
</tbody>
</table></para>
</section>