svn commit: r1447814 - /cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/queries.xml

[aa...@apache.org]

Author: aadamchik
Date: Tue Feb 19 16:58:49 2013
New Revision: 1447814

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

* ProcedureQuery
(cherry picked from commit b515e35c3a4b02070174015e43ef64f3da3a2276)

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=1447814&r1=1447813&r2=1447814&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 16:58:49 2013
@@ -519,6 +519,46 @@ List objects = context.performQuery(quer
     </section>
     <section xml:id="procedurequery">
         <title>ProcedureQuery</title>
+        <para>Stored procedures are mapped as separate objects in CayenneModeler. ProcedureQuery
+            provides a way to execute them with a certain set of parameters. Just like with
+            SQLTemplate, the outcome of a procedure can be anything - a single result set, mutliple
+            result sets, some data modification (returned as an update count), or a combination of
+            these. So use "performQuery" to get a single result set, and use "performGenericQuery"
+            for anything
+            else:<programlisting>ProcedureQuery query = new ProcedureQuery("my_procedure", Artist.class);
+
+// Set "IN" parameter values
+query.addParam("p1", "abc");
+query.addParam("p2", 3000);
+
+List&lt;Artist> result = context.performQuery(query);</programlisting><programlisting>// here we do not bother with root class. 
+// Procedure name gives us needed routing information
+ProcedureQuery query = new ProcedureQuery("my_procedure");
+
+query.addParam("p1", "abc");
+query.addParam("p2", 3000);
+
+QueryResponse response = context.performGenericQuery(query); </programlisting></para>
+        <para>A stored procedure can return data back to the application as result sets or via OUT
+            parameters. To simplify the processing of the query output, QueryResponse treats OUT
+            parameters as if it was a separate result set. If a stored procedure declares any OUT or
+            INOUT parameters, QueryResponse will contain their returned values in the very first
+            result
+            list:<programlisting>ProcedureQuery query = new ProcedureQuery("my_procedure");
+QueryResponse response = context.performGenericQuery(query);
+
+// read OUT parameters
+List out = response.firstList();
+
+if(!out.isEmpty()) {
+    Map outParameterValues = (Map) outList.get(0);
+}</programlisting></para>
+        <para>There maybe a situation when a stored procedure handles its own transactions, but an
+            application is configured to use Cayenne-managed transactions. This is obviously
+            conflicting and undesirable behavior. In this case ProcedureQueries should be executed
+            explicitly wrapped in an "external" Transaction. This is one of the few cases when a
+            user should worry about transactions at all. See Transactions section for more
+            details.</para>
     </section>
     <section xml:id="namedquery">
         <title>NamedQuery</title>