You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cayenne.apache.org by ap...@apache.org on 2014/11/22 12:01:27 UTC
cayenne git commit: CAY-1970 Minor Improvements to EJBQL Coverage in
"Cayenne Guide"
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 <ap...@lindesay.co.nz>
Authored: Sun Nov 23 00:01:16 2014 +1300
Committer: Andrew Lindesay <ap...@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<User> 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<Object> params = new ArrayList<Object>();
+EJBQLQuery query = new EJBQLQuery("SELECT p FROM Pkg p WHERE " + e.toEJBQL(params,"p");
+
+for(int i=0;i<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 "FETCH"
+ 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<String> names = context.performQuery(query);</programlisting>While
+List<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<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>