openjpa-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r818599 - /openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_query.xml
Date Thu, 24 Sep 2009 19:23:42 GMT
Author: fancy
Date: Thu Sep 24 19:23:40 2009
New Revision: 818599

OPENJPA-1327 Doc update for JPA2 JPQL Query


Modified: openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_query.xml
--- openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_query.xml (original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_query.xml Thu Sep 24 19:23:40
@@ -353,6 +353,45 @@
+        <section id="jpa_overview_query_embeddables">
+            <title>
+                Embeddable Traversal
+            </title>
+            <para>
+Similar to relation traversal, nested embeddable objects can be traversed using Java-like
+For example, if the <classname>Compony</classname> class has a field named "address"
+an embeddable type <classname>Address</classname>, 
+and the <classname>Address</classname> has a field named "geocode" of
+an embeddable type <classname>Geocode</classname>,
+the <literal>geocode</literal> of a company's address can be queried as follows:
+            </para>
+SELECT c.address.geocode FROM Company c WHERE = 'Random House'
+            <note>
+                <para>
+The <literal>geocode</literal> returned by the above query will not be part of
the state of any managed
+entity. Modifications to these embeddable instances are not allowed.
+                </para>
+            </note>
+            <para>
+Traverse into embeddable's state field is also allowed as shown in the following query:
+            </para>
+SELECT c.address.geocode.latitude FROM Company c WHERE = 'Random House'
+            <para>
+Embeddable objects may contain single-valued or collection-valued relations.
+These relations can also be traversed using Java-like syntax.
+For example, if the Address has a relation field named "phoneLists" of 
+an entity type <classname>PhoneNumber</classname>,
+the following query returns the <classname>PhoneNumber</classname> entities of
the <classname>Company</classname>
+ named 'Random House':
+            </para>
+SELECT p FROM Company c, IN(c.address.phoneLists) p WHERE = 'Random House'
+        </section>
         <section id="jpa_overview_join_fetch">
                 Fetch Joins
@@ -377,6 +416,21 @@
+Notice that in the above query, both <literal>articles</literal> and <literal>authors</literal>
+are relation property in <classname>Magazine</classname>.
+JPQL syntax does not allow range variable declared for paths on the right-hand side of 
+<literal>join fetch</literal>.
+Therefore, if <classname>Article</classname> entity has a relation property of

+it is not possible to specify a query
+that returns <classname>Magazine</classname> instances and pre-fetch 
+the <literal>articles</literal> and the <literal>publishers</literal>.
+The following query will result in syntax error:
+SELECT x FROM Magazine x join fetch x.articles a join fetch a.publishers p WHERE x.title
= 'JDJ'
+            </para>
+            <para>
 <note><para> Specifying the <literal>join fetch</literal> declaration
 functionally equivalent to adding the fields to the Query's <classname>
 FetchConfiguration</classname>. See <xref linkend="ref_guide_fetch"/>.
@@ -414,10 +468,12 @@
                             SUBSTRING function
-<literal>SUBSTRING(string, startIndex, length)</literal>: Returns the part of
+<literal>SUBSTRING(string, startIndex, [length])</literal>: Returns the part
 the <literal>string</literal> argument starting at <literal>startIndex</literal>
-(1-based) and ending at <literal>length</literal> characters past <literal>
+(1-based) and optionally ending at <literal>length</literal> characters past
+startIndex</literal>. If the <literal>length</literal> argument is not
+the substring from the <literal>startIndex</literal> to the end of the <literal>string</literal>
+is returned.
 SELECT x FROM Magazine x WHERE SUBSTRING(x.title, 1, 1) = 'J'
@@ -542,6 +598,26 @@
+                            INDEX function
+                        </primary>
+                    </indexterm>
+<literal>INDEX(identification_variable)</literal>: Returns an integer value corresponding
+ to the position of its argument in an ordered list. 
+ The INDEX function can only be applied to identification variables denoting types for
+which an order column has been specified.
+                    </para>
+                    <para>
+In the following example, <literal>studentWaitlist</literal> is a list of students
for which an order column has
+been specified, the query returns the name of the first student on the waitiing list of the
course named 'Calculus':
+                    </para>
+SELECT FROM Course c JOIN c.studentWaitlist w WHERE = ‘Calculus’
AND INDEX(w) = 0
+                </listitem>
+                <listitem>
+                    <para>
+                    <indexterm>
+                        <primary>
                             CURRENT_DATE function
@@ -585,6 +661,10 @@
 Digest</classname> are <classname>Magazine</classname> subclasses.
 <programlisting>SELECT x FROM Magazine x WHERE x.price &lt; 5</programlisting>
+            <para>
+Non-polymorphic queries or queries whose polymorphism is restricted can be specified using
+type expressions in the WHERE clause to restrict the domain of the query.
+            </para>
         <section id="jpa_overview_query_params">

View raw message