Return-Path: 
 <commits-return-13014-apmail-cayenne-commits-archive=cayenne.apache.org@cayenne.apache.org>
X-Original-To: apmail-cayenne-commits-archive@www.apache.org
Delivered-To: apmail-cayenne-commits-archive@www.apache.org
Received: from mail.apache.org (hermes.apache.org [140.211.11.3])
	by minotaur.apache.org (Postfix) with SMTP id 9CC17E115
	for <apmail-cayenne-commits-archive@www.apache.org>;
 Tue, 19 Feb 2013 13:19:23 +0000 (UTC)
Received: (qmail 81983 invoked by uid 500); 19 Feb 2013 13:19:23 -0000
Delivered-To: apmail-cayenne-commits-archive@cayenne.apache.org
Received: (qmail 81959 invoked by uid 500); 19 Feb 2013 13:19:23 -0000
Mailing-List: contact commits-help@cayenne.apache.org; run by ezmlm
Precedence: bulk
List-Help: <mailto:commits-help@cayenne.apache.org>
List-Unsubscribe: <mailto:commits-unsubscribe@cayenne.apache.org>
List-Post: <mailto:commits@cayenne.apache.org>
List-Id: <commits.cayenne.apache.org>
Reply-To: dev@cayenne.apache.org
Delivered-To: mailing list commits@cayenne.apache.org
Received: (qmail 81949 invoked by uid 99); 19 Feb 2013 13:19:23 -0000
Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136)
    by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 19 Feb 2013 13:19:23 +0000
X-ASF-Spam-Status: No, hits=-2000.0 required=5.0
	tests=ALL_TRUSTED
X-Spam-Check-By: apache.org
Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4)
    by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 19 Feb 2013 13:19:22 +0000
Received: from eris.apache.org (localhost [127.0.0.1])
	by eris.apache.org (Postfix) with ESMTP id 468CC23888CD;
	Tue, 19 Feb 2013 13:19:03 +0000 (UTC)
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r1447704 -
 /cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/queries.xml
Date: Tue, 19 Feb 2013 13:19:03 -0000
To: commits@cayenne.apache.org
From: aadamchik@apache.org
X-Mailer: svnmailer-1.0.8-patched
Message-Id: <20130219131903.468CC23888CD@eris.apache.org>
X-Virus-Checked: Checked by ClamAV on apache.org

Author: aadamchik
Date: Tue Feb 19 13:19:02 2013
New Revision: 1447704

URL: http://svn.apache.org/r1447704
Log:
docs

* SQLTemplate #result

Modified:
    cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/queries.xml

Modified: cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/queries.xml
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/queries.xml?rev=1447704&r1=1447703&r2=1447704&view=diff
==============================================================================
--- cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/queries.xml (original)
+++ cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/queries.xml Tue Feb 19 13:19:02 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>