cayenne-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From a..@apache.org
Subject cayenne git commit: CAY-1970 Minor Improvements to EJBQL Coverage in "Cayenne Guide"
Date Sat, 22 Nov 2014 11:01:27 GMT
Repository: cayenne
Updated Branches:
  refs/heads/master 177a25bd8 -> 7e36c932c


CAY-1970 Minor Improvements to EJBQL Coverage in "Cayenne Guide"


Project: http://git-wip-us.apache.org/repos/asf/cayenne/repo
Commit: http://git-wip-us.apache.org/repos/asf/cayenne/commit/7e36c932
Tree: http://git-wip-us.apache.org/repos/asf/cayenne/tree/7e36c932
Diff: http://git-wip-us.apache.org/repos/asf/cayenne/diff/7e36c932

Branch: refs/heads/master
Commit: 7e36c932cef7233044af83a5f878c43f9c9f0956
Parents: 177a25b
Author: Andrew Lindesay <apl@lindesay.co.nz>
Authored: Sun Nov 23 00:01:16 2014 +1300
Committer: Andrew Lindesay <apl@lindesay.co.nz>
Committed: Sun Nov 23 00:01:16 2014 +1300

----------------------------------------------------------------------
 .../cayenne-guide/src/docbkx/expressions.xml    | 23 +++++++++++++
 .../src/docbkx/performance-tuning.xml           | 36 ++++++++++++++++++++
 .../cayenne-guide/src/docbkx/queries.xml        | 36 ++++++++++++++++++--
 3 files changed, 92 insertions(+), 3 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/cayenne/blob/7e36c932/docs/docbook/cayenne-guide/src/docbkx/expressions.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/expressions.xml b/docs/docbook/cayenne-guide/src/docbkx/expressions.xml
index 34257f3..7e34f71 100644
--- a/docs/docbook/cayenne-guide/src/docbkx/expressions.xml
+++ b/docs/docbook/cayenne-guide/src/docbkx/expressions.xml
@@ -262,4 +262,27 @@ List&lt;User&gt; filtered = e.filterObjects(unfiltered);</programlisting></para>
             </note>
         </para>
     </section>
+
+    <section xml:id="expressions-to-ejbql">
+        <title>Translating Expressions to EJBQL</title>
+        <para>
+            <link linkend="ejbqlquery">EJBQL</link> is a textual query language
that can be used with Cayenne.
+            In some situations, it is convenient to be able to convert Expression instances
into EJBQL.
+            Expressions support this conversion.  An example is shown below.
+
+            <programlisting>String serial = ...
+Expression e = ExpressionFactory.matchExp(Pkg.SERIAL_PROPERTY, serial);
+List&lt;Object&gt; params = new ArrayList&lt;Object&gt;();
+EJBQLQuery query = new EJBQLQuery("SELECT p FROM Pkg p WHERE " + e.toEJBQL(params,&quot;p&quot;);
+
+for(int i=0;i&lt;params.size();i++) {
+  query.setParameter(i+1, params.get(i));
+}</programlisting>
+
+            This would be equivalent to the following purely EJBQL querying logic;
+
+            <programlisting>EJBQLQuery query = new EJBQLQuery("SELECT p FROM Pkg p
WHERE p.serial = ?1");
+query.setParameter(1,serial);</programlisting>
+        </para>
+    </section>
 </chapter>

http://git-wip-us.apache.org/repos/asf/cayenne/blob/7e36c932/docs/docbook/cayenne-guide/src/docbkx/performance-tuning.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/performance-tuning.xml b/docs/docbook/cayenne-guide/src/docbkx/performance-tuning.xml
index e54c6ff..b331e83 100644
--- a/docs/docbook/cayenne-guide/src/docbkx/performance-tuning.xml
+++ b/docs/docbook/cayenne-guide/src/docbkx/performance-tuning.xml
@@ -112,6 +112,22 @@ query.addPrefetch("paintings").setSemantics(
                 application server and the database, and more data processing that needs
to be done
                 on the Cayenne side.</para>
         </section>
+        <section xml:id="prefetching-with-ejbql">
+            <title>Similar Behaviours Using EJBQL</title>
+            <para>It is possible to achieve similar behaviours with
+            <link linkend="ejbqlquery">EJBQLQuery</link> queries by employing
the &quot;FETCH&quot;
+                keyword.</para>
+
+            <screen>SELECT a FROM Artist a LEFT JOIN FETCH a.paintings</screen>
+
+            <para>
+                In this case, the Paintings that exist for the Artist will be obtained at
the same time
+                as the Artists are fetched.  Refer to third-party query language documentation
for further
+                detail on this mechanism.
+            </para>
+
+        </section>
+
     </section>
     <section xml:id="datarows">
         <title>Data Rows</title>
@@ -145,6 +161,26 @@ for(DataRow row : rows) {
     }
 }</programlisting></para>
     </section>
+
+    <section xml:id="specific-attributes-with-ejbql">
+        <title>Specific Attributes and Relationships with EJBQL</title>
+        <para>
+            It is possible to fetch specific attributes and relationships from a model
+            using <link linkend="ejbqlquery">EJBQLQuery</link>.
+            The following example would return a java.util.List of String objects;
+        </para>
+
+        <screen>SELECT a.name FROM Artist a</screen>
+
+        <para>The following will yield a java.util.List containing Object[] instances,
each of which
+            would contain the name followed by the dateOfBirth value.</para>
+
+        <screen>SELECT a.name, a.dateOfBirth FROM Artist a</screen>
+
+        <para>Refer to third-party query language documentation for further
+            detail on this mechanism.</para>
+    </section>
+
     <section xml:id="iterated-queries">
         <title>Iterated Queries</title>
         <para>While contemporary hardware may easily allow applications to fetch hundreds
of

http://git-wip-us.apache.org/repos/asf/cayenne/blob/7e36c932/docs/docbook/cayenne-guide/src/docbkx/queries.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/queries.xml b/docs/docbook/cayenne-guide/src/docbkx/queries.xml
index dfbad2f..eb1f38b 100644
--- a/docs/docbook/cayenne-guide/src/docbkx/queries.xml
+++ b/docs/docbook/cayenne-guide/src/docbkx/queries.xml
@@ -111,9 +111,38 @@ for(Object[] artistWithCount : result) {
             elements, where each entry in an Object[] is either a DataObject or a scalar,
depending
             on the query SELECT clause. A result can also be a list of
             scalars:<programlisting language="java">EJBQLQuery query = new EJBQLQuery("select
a.name FROM Artist a");
-List&lt;String> names = context.performQuery(query);</programlisting>While
+List&lt;String> names = context.performQuery(query);</programlisting>
+
+            EJBQLQuery supports an "IN" clause with three different usage-patterns.  The
following
+            example would require three individual positional parameters (named
+            parameters could also have been used) to be supplied.
+
+            <screen>select p from Painting p where p.paintingTitle in (?1,?2,?3)</screen>
+
+            The following example requires a single positional parameter to be supplied.
 The
+            parameter can be any concrete implementation of the java.util.Collection interface
such as
+            java.util.List or java.util.Set.
+
+            <screen>select p from Painting p where p.paintingTitle in ?1</screen>
+
+            The following example is functionally identical to the one prior.
+
+            <screen>select p from Painting p where p.paintingTitle in (?1)</screen>
+
+            <para>
+                It is
+                <link linkend="expressions-to-ejbql">possible to convert</link>
+                an
+                <link linkend="expressions">Expression</link>
+                object used with a
+                <link linkend="selectquery">SelectQuery</link>
+                to EJBQL.  Use the Expression#appendAsEJBQL methods for this purpose.
+            </para>
+
+            While
             Cayenne Expressions discussed previously can be thought of as identical to JPQL
WHERE
-            clause, and indeed they are very close, there are a few noteable differences:<itemizedlist>
+            clause, and indeed they are very close, there are a few noteable differences:
+            <itemizedlist>
                 <listitem>
                     <para>Null handling: SelectQuery would translate the expressions
matching NULL
                         values to the corresponding "X IS NULL" or "X IS NOT NULL" SQL syntax.
@@ -126,7 +155,8 @@ List&lt;String> names = context.performQuery(query);</programlisting>While
                         (e.g. "$myParam"), while EJBQL uses ":" (e.g. ":myParam"). Also EJBQL
                         supports positional parameters denoted by the question mark: "?3".</para>
                 </listitem>
-            </itemizedlist></para>
+            </itemizedlist>
+        </para>
     </section>
     <section xml:id="sqltemplate">
         <title>SQLTemplate</title>


Mime
View raw message