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<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>
