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/CAY-1946_1 Commit: 7e36c932cef7233044af83a5f878c43f9c9f0956 Parents: 177a25b Author: Andrew Lindesay <a...@lindesay.co.nz> Authored: Sun Nov 23 00:01:16 2014 +1300 Committer: Andrew Lindesay <a...@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>
