You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@openjpa.apache.org by aw...@apache.org on 2006/08/24 22:41:14 UTC
svn commit: r434517 [8/23] - in /incubator/openjpa/trunk:
openjpa-kernel/src/main/java/org/apache/openjpa/meta/
openjpa-lib/src/main/java/org/apache/openjpa/lib/meta/
openjpa-project/src/doc/manual/
Modified: incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_query.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_query.xml?rev=434517&r1=434516&r2=434517&view=diff
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_query.xml (original)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_query.xml Thu Aug 24 13:41:12 2006
@@ -1,569 +1,690 @@
-
- <chapter id="jpa_overview_query">
- <title>JPA Query</title>
- <indexterm zone="jpa_overview_query">
- <primary>JP Query</primary>
- <seealso>JPQL</seealso>
- </indexterm>
- <indexterm>
- <primary>queries</primary>
- <see>Query</see>
- </indexterm>
- <mediaobject>
+<chapter id="jpa_overview_query">
+ <title>
+ JPA Query
+ </title>
+ <indexterm zone="jpa_overview_query">
+ <primary>
+ JP Query
+ </primary>
+ <seealso>
+ JPQL
+ </seealso>
+ </indexterm>
+ <indexterm>
+ <primary>
+ queries
+ </primary>
+ <see>
+ Query
+ </see>
+ </indexterm>
+ <mediaobject>
<imageobject>
-<!-- PNG image data, 292 x 265 (see README) -->
- <imagedata fileref="img/jpa-query.png" width="195px"/>
+ <!-- PNG image data, 292 x 265 (see README) -->
+ <imagedata fileref="img/jpa-query.png" width="195px">
+ </imagedata>
</imageobject>
- </mediaobject>
- <para>
- The <classname>javax.persistence.Query</classname> interface is the
- mechanism for issuing queries in JPA. The primary query language used is
- the Java Persistence Query Language, or <literal>JPQL</literal>. JPQL is
- syntactically very similar to SQL, but is object-oriented rather than
- table-oriented.
- </para>
- <para>
- The API for executing JPQL queries will be discussed in
- <xref linkend="jpa_query_api"/>, and a full language
- reference will be covered in <xref linkend="jpa_langref"/>.
- </para>
- <section id="jpa_query_api">
- <title>JPQL API</title>
+ </mediaobject>
+ <para>
+The <classname>javax.persistence.Query</classname> interface is the mechanism
+for issuing queries in JPA. The primary query language used is the Java
+Persistence Query Language, or <literal>JPQL</literal>. JPQL is syntactically
+very similar to SQL, but is object-oriented rather than table-oriented.
+ </para>
+ <para>
+The API for executing JPQL queries will be discussed in
+<xref linkend="jpa_query_api"></xref>, and a full language reference will be
+covered in <xref linkend="jpa_langref"></xref>.
+ </para>
+ <section id="jpa_query_api">
+ <title>
+ JPQL API
+ </title>
<section id="jpa_overview_query_basic">
- <title>Query Basics</title>
- <programlisting format="linespecific">SELECT x FROM Magazine x</programlisting>
- <para>
- The preceding is a simple JPQL query for all <classname>Magazine
- </classname> entities.
- </para>
- <programlisting format="linespecific">
+ <title>
+ Query Basics
+ </title>
+<programlisting>SELECT x FROM Magazine x
+</programlisting>
+ <para>
+The preceding is a simple JPQL query for all <classname>Magazine</classname>
+entities.
+ </para>
+<programlisting>
public Query createQuery (String jpql);
</programlisting>
- <para>
- The <ulink url="http://java.sun.com/javaee/5/docs/api/javax/persistence/EntityManager.html"><methodname>EntityManager.createQuery</methodname></ulink>
- method creates a <classname>Query</classname> instance from a given
- JPQL string.
- </para>
- <programlisting format="linespecific">
+ <para>
+The
+<ulink url="http://java.sun.com/javaee/5/docs/api/javax/persistence/EntityManager.html">
+<methodname>EntityManager.createQuery</methodname></ulink> method creates a
+<classname>Query</classname> instance from a given JPQL string.
+ </para>
+<programlisting>
public List getResultList ();
</programlisting>
- <para>
- Invoking
- <ulink url="http://java.sun.com/javaee/5/docs/api/javax/persistence/Query.html#getResultList()"><methodname>Query.getResultList</methodname></ulink> executes the query
- and returns a <classname>List</classname> containing the matching
- objects. The following example executes our <classname>Magazine
- </classname> query above:
- </para>
- <programlisting format="linespecific">
+ <para>
+Invoking
+<ulink url="http://java.sun.com/javaee/5/docs/api/javax/persistence/Query.html#getResultList()">
+<methodname>Query.getResultList</methodname></ulink> executes the query and
+returns a <classname>List</classname> containing the matching objects. The
+following example executes our <classname>Magazine</classname> query above:
+ </para>
+<programlisting>
EntityManager em = ...
Query q = em.createQuery ("SELECT x FROM Magazine x");
List<Magazine> results = q.getResultList ();
</programlisting>
- <para>
- A JPQL query has an internal namespace declared in
- the <literal>from</literal> clause of the query. Arbitrary identifiers
- are assigned to entities so that they can be referenced elsewhere in the
- query. In the query example above, the identifier
- <literal>x</literal> is assigned to the entity <classname>
- Magazine</classname>.
- </para>
- <note>
- <para>
- The <literal>as</literal> keyword can optionally be used when
- declaring identifiers in the <literal>from</literal> clause.
- <literal>SELECT x FROM Magazine x</literal> and
- <literal>SELECT x FROM Magazine AS x</literal> are synonymous.
- </para>
- </note>
- <para>
- Following the <literal>select</literal> clause of the query is the
- object or objects that the query returns. In the case of the query
- above, the query's result list will contain instances of the
- <classname>Magazine</classname> class.
- </para>
- <note>
- <para>
- When selecting entities, you can optional use the keyword
- <literal>object</literal>. The clauses <literal>select x</literal>
- and <literal>SELECT OBJECT(x)</literal> are synonymous.
- </para>
- </note>
- <para>
- The optional <literal>where</literal> clause places criteria on
- matching results. For example:
- </para>
- <programlisting format="linespecific">SELECT x FROM Magazine x WHERE x.title = 'JDJ'</programlisting>
- <para>
- Keywords in JPQL expressions are case-insensitive, but
- entity, identifier, and member names are not. For example,
- the expression above could also be expressed as:
- </para>
- <programlisting format="linespecific">SELECT x FROM Magazine x WHERE x.title = 'JDJ'</programlisting>
- <para>
- But it could not be expressed as:
- </para>
- <programlisting format="linespecific">SELECT x FROM Magazine x WHERE x.TITLE = 'JDJ'</programlisting>
- <para>
- As with the <literal>select</literal> clause, alias names in the
- <literal>where</literal> clause are resolved
- to the entity declared in the <literal>from</literal> clause. The query
- above could be described in English as "for all <classname>Magazine
- </classname> instances <literal>x</literal>, return a list of every
- <literal>x</literal> such that <literal>x</literal>'s <literal>title
- </literal> field is equal to 'JDJ'".
- </para>
- <para>
- JPQL uses SQL-like syntax for query criteria. The <literal>and
- </literal> and <literal>or</literal> logical operators chain
- multiple criteria together:
- </para>
- <programlisting format="linespecific">
+ <para>
+A JPQL query has an internal namespace declared in the <literal>from</literal>
+clause of the query. Arbitrary identifiers are assigned to entities so that they
+can be referenced elsewhere in the query. In the query example above, the
+identifier <literal>x</literal> is assigned to the entity <classname> Magazine
+</classname>.
+ </para>
+ <note>
+ <para>
+The <literal>as</literal> keyword can optionally be used when declaring
+identifiers in the <literal>from</literal> clause. <literal>SELECT x FROM
+Magazine x</literal> and <literal>SELECT x FROM Magazine AS x</literal> are
+synonymous.
+ </para>
+ </note>
+ <para>
+Following the <literal>select</literal> clause of the query is the object or
+objects that the query returns. In the case of the query above, the query's
+result list will contain instances of the <classname>Magazine</classname> class.
+ </para>
+ <note>
+ <para>
+When selecting entities, you can optional use the keyword <literal>object
+</literal>. The clauses <literal>select x</literal> and <literal>SELECT
+OBJECT(x)</literal> are synonymous.
+ </para>
+ </note>
+ <para>
+The optional <literal>where</literal> clause places criteria on matching
+results. For example:
+ </para>
+<programlisting>SELECT x FROM Magazine x WHERE x.title = 'JDJ'
+</programlisting>
+ <para>
+Keywords in JPQL expressions are case-insensitive, but entity, identifier, and
+member names are not. For example, the expression above could also be expressed
+as:
+ </para>
+<programlisting>SELECT x FROM Magazine x WHERE x.title = 'JDJ'
+</programlisting>
+ <para>
+But it could not be expressed as:
+ </para>
+<programlisting>SELECT x FROM Magazine x WHERE x.TITLE = 'JDJ'
+</programlisting>
+ <para>
+As with the <literal>select</literal> clause, alias names in the <literal>where
+</literal> clause are resolved to the entity declared in the <literal>from
+</literal> clause. The query above could be described in English as "for all
+<classname>Magazine</classname> instances <literal>x</literal>, return a list
+of every <literal>x</literal> such that <literal>x</literal>'s <literal>title
+</literal> field is equal to 'JDJ'".
+ </para>
+ <para>
+JPQL uses SQL-like syntax for query criteria. The <literal>and</literal> and
+<literal>or</literal> logical operators chain multiple criteria together:
+ </para>
+<programlisting>
SELECT x FROM Magazine x WHERE x.title = 'JDJ' OR x.title = 'JavaPro'
</programlisting>
- <para>
- The <literal>=</literal> operator tests for equality. <literal><>
- </literal> tests for inequality. JPQL also
- supports the following arithmetic operators for numeric comparisons:
- <literal>>, >=, <, <=</literal>. For example:
- </para>
- <programlisting format="linespecific">
+ <para>
+The <literal>=</literal> operator tests for equality. <literal><>
+</literal> tests for inequality. JPQL also supports the following arithmetic
+operators for numeric comparisons: <literal>>, >=, <, <=</literal>.
+For example:
+ </para>
+<programlisting>
SELECT x FROM Magazine x WHERE x.price > 3.00 AND x.price <= 5.00
</programlisting>
- <para>
- This query returns all magazines whose price is greater than 3.00
- and less than or equal to 5.00.
- </para>
- <programlisting format="linespecific">
+ <para>
+This query returns all magazines whose price is greater than 3.00 and less than
+or equal to 5.00.
+ </para>
+<programlisting>
SELECT x FROM Magazine x WHERE x.price <> 3.00
</programlisting>
- <para>
- This query returns all Magazines whose price is not equals to 3.00.
- </para>
- <para>
- You can group expressions together using parentheses in order to
- specify how they are evaluated. This is similar to how parentheses are
- used in Java. For example:
- </para>
- <programlisting format="linespecific">
+ <para>
+This query returns all Magazines whose price is not equals to 3.00.
+ </para>
+ <para>
+You can group expressions together using parentheses in order to specify how
+they are evaluated. This is similar to how parentheses are used in Java. For
+example:
+ </para>
+<programlisting>
SELECT x FROM Magazine x WHERE (x.price > 3.00 AND x.price <= 5.00) OR x.price = 7.00
</programlisting>
- <para>
- This expression would match magazines whose price
- is 4.00, 5.00, or 7.00, but not 6.00. Alternately:
- </para>
- <programlisting format="linespecific">
+ <para>
+This expression would match magazines whose price is 4.00, 5.00, or 7.00, but
+not 6.00. Alternately:
+ </para>
+<programlisting>
SELECT x FROM Magazine x WHERE x.price > 3.00 AND (x.price <= 5.00 OR x.price = 7.00)
</programlisting>
- <para>
- This expression will magazines whose price is 5.00 or 7.00, but
- not 4.00 or 6.00.
- </para>
- <para>
- JPQL also includes the following conditionals:
- </para>
- <itemizedlist>
- <listitem>
- <para><indexterm><primary>BETWEEN expressions</primary></indexterm><literal>[NOT] BETWEEN</literal>: Shorthand for expressing
- that a value falls between two other values.
- The following two statements are synonymous:
- </para>
- <programlisting format="linespecific">
+ <para>
+This expression will magazines whose price is 5.00 or 7.00, but not 4.00 or
+6.00.
+ </para>
+ <para>
+JPQL also includes the following conditionals:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ BETWEEN expressions
+ </primary>
+ </indexterm>
+<literal>[NOT] BETWEEN</literal>: Shorthand for expressing that a value falls
+between two other values. The following two statements are synonymous:
+ </para>
+<programlisting>
SELECT x FROM Magazine x WHERE x.price >= 3.00 AND x.price <= 5.00
</programlisting>
- <programlisting format="linespecific">
+<programlisting>
SELECT x FROM Magazine x WHERE x.price BETWEEN 3.00 AND 5.00
</programlisting>
- </listitem>
- <listitem>
- <para><indexterm><primary>LIKE expressions</primary></indexterm><literal>[NOT] LIKE</literal>: Performs a string comparison
- with wildcard support. The special character '_' in the
- parameter means to match any single character, and the special
- character '%' means to match any sequence of characters.
- The following statement matches title fields "JDJ" and
- "JavaPro", but not "IT Insider":
- </para>
- <programlisting format="linespecific">
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ LIKE expressions
+ </primary>
+ </indexterm>
+<literal>[NOT] LIKE</literal>: Performs a string comparison with wildcard
+support. The special character '_' in the parameter means to match any single
+character, and the special character '%' means to match any sequence of
+characters. The following statement matches title fields "JDJ" and "JavaPro",
+but not "IT Insider":
+ </para>
+<programlisting>
SELECT x FROM Magazine x WHERE x.title LIKE 'J%'
</programlisting>
- <para>
- The following statement matches the title field "JDJ"
- but not "JavaPro":
- </para>
- <programlisting format="linespecific">
+ <para>
+The following statement matches the title field "JDJ" but not "JavaPro":
+ </para>
+<programlisting>
SELECT x FROM Magazine x WHERE x.title LIKE 'J__'
</programlisting>
- </listitem>
- <listitem>
- <para><indexterm><primary>IN expressions</primary></indexterm><literal>[NOT] IN</literal>: Specifies that the member must be
- equal to one element of the provided list.
- The following two statements are synonymous:
- </para>
- <programlisting format="linespecific">
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ IN expressions
+ </primary>
+ </indexterm>
+<literal>[NOT] IN</literal>: Specifies that the member must be equal to one
+element of the provided list. The following two statements are synonymous:
+ </para>
+<programlisting>
SELECT x FROM Magazine x WHERE x.title IN ('JDJ', 'JavaPro', 'IT Insider')
</programlisting>
- <programlisting format="linespecific">SELECT x FROM Magazine x WHERE x.title = 'JDJ' OR x.title = 'JavaPro' OR x.title = 'IT Insider'
+<programlisting>SELECT x FROM Magazine x WHERE x.title = 'JDJ' OR x.title = 'JavaPro' OR x.title = 'IT Insider'
</programlisting>
- </listitem>
- <listitem>
- <para><indexterm><primary>IS EMPTY expressions</primary></indexterm><literal>IS [NOT] EMPTY</literal>: Specifies that the
- collection field holds no elements. For example:
- </para>
- <programlisting format="linespecific">
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ IS EMPTY expressions
+ </primary>
+ </indexterm>
+<literal>IS [NOT] EMPTY</literal>: Specifies that the collection field holds no
+elements. For example:
+ </para>
+<programlisting>
SELECT x FROM Magazine x WHERE x.articles is empty
</programlisting>
- <para>
- This statement will return all magazines whose <literal>
- articles</literal> member contains no elements.
- </para>
- </listitem>
- <listitem>
- <para><indexterm><primary>IS NULL expressions</primary></indexterm><literal>IS [NOT] NULL</literal>: Specifies that the field is
- equal to null. For example:
- </para>
- <programlisting format="linespecific">
+ <para>
+This statement will return all magazines whose <literal> articles</literal>
+member contains no elements.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ IS NULL expressions
+ </primary>
+ </indexterm>
+<literal>IS [NOT] NULL</literal>: Specifies that the field is equal to null.
+For example:
+ </para>
+<programlisting>
SELECT x FROM Magazine x WHERE x.publisher is null
</programlisting>
- <para>
- This statement will return all Magazine instances whose
- "publisher" field is set to <literal>null</literal>.
- </para>
- </listitem>
- <listitem>
- <para><indexterm><primary>NOT expressions</primary></indexterm><literal>NOT</literal>: Negates the contained expression. For
- example, the following two statements are synonymous:
- </para>
- <programlisting format="linespecific">
+ <para>
+This statement will return all Magazine instances whose "publisher" field is set
+to <literal>null</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ NOT expressions
+ </primary>
+ </indexterm>
+<literal>NOT</literal>: Negates the contained expression. For example, the
+following two statements are synonymous:
+ </para>
+<programlisting>
SELECT x FROM Magazine x WHERE NOT(x.price = 10.0)
</programlisting>
- <programlisting format="linespecific">
+<programlisting>
SELECT x FROM Magazine x WHERE x.price <> 10.0
</programlisting>
- </listitem>
- </itemizedlist>
+ </listitem>
+ </itemizedlist>
</section>
<section id="jpa_overview_query_relations">
- <title>Relation Traversal</title>
- <para>
- Relations between objects can be traversed using Java-like syntax.
- For example, if the Magazine class has a field named "publisher" or
- type Company, that relation can be queried as follows:
- </para>
- <programlisting format="linespecific">
+ <title>
+ Relation Traversal
+ </title>
+ <para>
+Relations between objects can be traversed using Java-like syntax. For example,
+if the Magazine class has a field named "publisher" or type Company, that
+relation can be queried as follows:
+ </para>
+<programlisting>
SELECT x FROM Magazine x WHERE x.publisher.name = 'Random House'
</programlisting>
- <para>
- This query returns all <classname>Magazine</classname> instances whose
- <literal>publisher</literal> field is set to a <classname>Company
- </classname> instance whose name is "Random House".
- </para>
- <para>
- Single-valued relation traversal implies that the relation is not null.
- In SQL terms, this is known as an <emphasis>inner join</emphasis>. If
- you want to also include relations that are null, you can specify:
- </para>
- <programlisting format="linespecific">
+ <para>
+This query returns all <classname>Magazine</classname> instances whose <literal>
+publisher</literal> field is set to a <classname>Company</classname> instance
+whose name is "Random House".
+ </para>
+ <para>
+Single-valued relation traversal implies that the relation is not null. In SQL
+terms, this is known as an <emphasis>inner join</emphasis>. If you want to also
+include relations that are null, you can specify:
+ </para>
+<programlisting>
SELECT x FROM Magazine x WHERE x.publisher.name = 'Random House' or x.publisher is null
</programlisting>
- <para>
- You can also traverse collection fields in queries, but you must declare
- each traversal in the <literal>from</literal> clause.
- Consider:
- </para>
- <programlisting format="linespecific">
+ <para>
+You can also traverse collection fields in queries, but you must declare each
+traversal in the <literal>from</literal> clause. Consider:
+ </para>
+<programlisting>
SELECT x FROM Magazine x, IN(x.articles) y WHERE y.authorName = 'John Doe'
</programlisting>
- <para>
- This query says that for each <classname>Magazine</classname> <literal>
- x</literal>, traverse the <literal>articles</literal> relation and
- check each <classname>Article</classname> <literal>y</literal>, and
- pass the filter if <literal>y</literal>'s <literal>authorName</literal>
- field is equal to "John Doe". In short, this query will return all
- magazines that have any articles written by John Doe.
- </para>
- <note>
- <para>
- The <literal>IN()</literal> syntax can also be expressed with the
- keywords <literal>inner join</literal>. The statements
- <literal>SELECT x FROM Magazine x, IN(x.articles) y WHERE
- y.authorName = 'John Doe'</literal> and
- <literal>SELECT x FROM Magazine x inner join x.articles y
- WHERE y.authorName = 'John Doe'</literal> are synonymous.
- </para>
- </note>
+ <para>
+This query says that for each <classname>Magazine</classname><literal> x
+</literal>, traverse the <literal>articles</literal> relation and check each
+<classname>Article</classname><literal>y</literal>, and pass the filter if
+<literal>y</literal>'s <literal>authorName</literal> field is equal to "John
+Doe". In short, this query will return all magazines that have any articles
+written by John Doe.
+ </para>
+ <note>
+ <para>
+The <literal>IN()</literal> syntax can also be expressed with the keywords
+<literal>inner join</literal>. The statements <literal>SELECT x FROM Magazine
+x, IN(x.articles) y WHERE y.authorName = 'John Doe'</literal> and <literal>
+SELECT x FROM Magazine x inner join x.articles y WHERE y.authorName = 'John Doe'
+</literal> are synonymous.
+ </para>
+ </note>
</section>
<section id="jpa_overview_join_fetch">
- <title>Fetch Joins</title>
- <para>
- JPQL queries may specify one or more <literal>join fetch</literal>
- declarations, which allow the query to specify which fields
- in the returned instances will be pre-fetched.
- </para>
- <programlisting format="linespecific">
+ <title>
+ Fetch Joins
+ </title>
+ <para>
+JPQL queries may specify one or more <literal>join fetch</literal> declarations,
+which allow the query to specify which fields in the returned instances will be
+pre-fetched.
+ </para>
+<programlisting>
SELECT x FROM Magazine x join fetch x.articles WHERE x.title = 'JDJ'
</programlisting>
- <para>
- The query above returns <classname>Magazine</classname> instances
- and guarantees that the <literal>articles</literal> field will
- already be fetched in the returned instances.
- </para>
- <para>
- Multiple fields may be specified in separate
- <literal>join fetch</literal> declarations:
-<programlisting format="linespecific">
+ <para>
+The query above returns <classname>Magazine</classname> instances and guarantees
+that the <literal>articles</literal> field will already be fetched in the
+returned instances.
+ </para>
+ <para>
+Multiple fields may be specified in separate <literal>join fetch</literal>
+declarations: <programlisting>
SELECT x FROM Magazine x join fetch x.articles join fetch x.authors WHERE x.title = 'JDJ'
</programlisting>
- </para>
- <para>
- <note>
- <para>
- Specifying the <literal>join fetch</literal> declaration
- is functionally equivalent to adding the fields to
- the Query's <classname>FetchConfiguration</classname>.
- See <xref linkend="ref_guide_fetch"/>.
- </para>
- </note>
- </para>
+ </para>
+ <para>
+<note><para> Specifying the <literal>join fetch</literal> declaration is
+functionally equivalent to adding the fields to the Query's <classname>
+FetchConfiguration</classname>. See <xref linkend="ref_guide_fetch"></xref>.
+ </para>
+ </note>
+ </para>
</section>
<section id="jpa_overview_query_functions">
- <title>JPQL Functions</title>
- <para>
- As well as supporting direct field and relation comparisons,
- JPQL supports a pre-defined set of functions that you can apply.
- </para>
- <itemizedlist>
- <listitem>
- <para><indexterm><primary>CONCAT function</primary></indexterm><literal>CONCAT(string1, string2)</literal>: Concatenates two
- string fields or literals. For example:
- </para>
- <programlisting format="linespecific">
+ <title>
+ JPQL Functions
+ </title>
+ <para>
+As well as supporting direct field and relation comparisons, JPQL supports a
+pre-defined set of functions that you can apply.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ CONCAT function
+ </primary>
+ </indexterm>
+<literal>CONCAT(string1, string2)</literal>: Concatenates two string fields or
+literals. For example:
+ </para>
+<programlisting>
SELECT x FROM Magazine x WHERE CONCAT(x.title, 's') = 'JDJs'
</programlisting>
- </listitem>
- <listitem>
- <para><indexterm><primary>SUBSTRING function</primary></indexterm><literal>SUBSTRING(string, startIndex, length)</literal>:
- Returns the part of the <literal>string</literal> argument
- starting at <literal>startIndex</literal> (1-based) and ending
- at <literal>length</literal> characters past <literal>
- startIndex</literal>.
- </para>
- <programlisting format="linespecific">
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ SUBSTRING function
+ </primary>
+ </indexterm>
+<literal>SUBSTRING(string, startIndex, length)</literal>: Returns the part of
+the <literal>string</literal> argument starting at <literal>startIndex</literal>
+(1-based) and ending at <literal>length</literal> characters past <literal>
+startIndex</literal>.
+ </para>
+<programlisting>
SELECT x FROM Magazine x WHERE SUBSTRING(x.title, 1, 1) = 'J'
</programlisting>
- </listitem>
- <listitem>
- <para><indexterm><primary>TRIM function</primary></indexterm><literal>TRIM([LEADING | TRAILING | BOTH] [character FROM]
- string</literal>: Trims the specified character from
- either the beginning (<literal>LEADING</literal>)
- end (<literal>TRAILING</literal>) or both (<literal>
- BOTH</literal>) of the string argument. If no trim character is
- specified, the space character will be trimmed.
- </para>
- <programlisting format="linespecific">
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ TRIM function
+ </primary>
+ </indexterm>
+<literal>TRIM([LEADING | TRAILING | BOTH] [character FROM] string</literal>:
+Trims the specified character from either the beginning ( <literal>LEADING
+</literal>) end ( <literal>TRAILING</literal>) or both ( <literal> BOTH
+</literal>) of the string argument. If no trim character is specified, the
+space character will be trimmed.
+ </para>
+<programlisting>
SELECT x FROM Magazine x WHERE TRIM(BOTH 'J' FROM x.title) = 'D'
</programlisting>
- </listitem>
- <listitem>
- <para><indexterm><primary>LOWER function</primary></indexterm><literal>LOWER(string)</literal>: Returns the lower-case of the
- specified string argument.
- </para>
- <programlisting format="linespecific">
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ LOWER function
+ </primary>
+ </indexterm>
+<literal>LOWER(string)</literal>: Returns the lower-case of the specified
+string argument.
+ </para>
+<programlisting>
SELECT x FROM Magazine x WHERE LOWER(x.title) = 'jdj'
</programlisting>
- </listitem>
- <listitem>
- <para><indexterm><primary>UPPER function</primary></indexterm><literal>UPPER(string)</literal>: Returns the upper-case of the
- specified string argument.
- </para>
- <programlisting format="linespecific">
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ UPPER function
+ </primary>
+ </indexterm>
+<literal>UPPER(string)</literal>: Returns the upper-case of the specified
+string argument.
+ </para>
+<programlisting>
SELECT x FROM Magazine x WHERE UPPER(x.title) = 'JAVAPRO'
</programlisting>
- </listitem>
- <listitem>
- <para><indexterm><primary>LENGTH function</primary></indexterm><literal>LENGTH(string)</literal>: Returns the number of
- characters in the specified string argument.
- </para>
- <programlisting format="linespecific">
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ LENGTH function
+ </primary>
+ </indexterm>
+<literal>LENGTH(string)</literal>: Returns the number of characters in the
+specified string argument.
+ </para>
+<programlisting>
SELECT x FROM Magazine x WHERE LENGTH(x.title) = 3
</programlisting>
- </listitem>
- <listitem>
- <para><indexterm><primary>LOCATE function</primary></indexterm><literal>LOCATE(searchString, candidateString [,
- startIndex])</literal>: Returns the first index of
- <literal>searchString</literal> in <literal>
- candidateString</literal>. Positions are 1-based.
- If the string is not found, returns 0.
- </para>
- <programlisting format="linespecific">
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ LOCATE function
+ </primary>
+ </indexterm>
+<literal>LOCATE(searchString, candidateString [, startIndex])</literal>:
+Returns the first index of <literal>searchString</literal> in <literal>
+candidateString</literal>. Positions are 1-based. If the string is not found,
+returns 0.
+ </para>
+<programlisting>
SELECT x FROM Magazine x WHERE LOCATE('D', x.title) = 2
</programlisting>
- </listitem>
- <listitem>
- <para><indexterm><primary>ABS function</primary></indexterm><literal>ABS(number)</literal>: Returns the absolute value of
- the argument.
- </para>
- <programlisting format="linespecific">
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ ABS function
+ </primary>
+ </indexterm>
+<literal>ABS(number)</literal>: Returns the absolute value of the argument.
+ </para>
+<programlisting>
SELECT x FROM Magazine x WHERE ABS(x.price) >= 5.00
</programlisting>
- </listitem>
- <listitem>
- <para><indexterm><primary>SQRT function</primary></indexterm><literal>SQRT(number)</literal>: Returns the square root of
- the argument.
- </para>
- <programlisting format="linespecific">
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ SQRT function
+ </primary>
+ </indexterm>
+<literal>SQRT(number)</literal>: Returns the square root of the argument.
+ </para>
+<programlisting>
SELECT x FROM Magazine x WHERE SQRT(x.price) >= 1.00
</programlisting>
- </listitem>
- <listitem>
- <para><indexterm><primary>MOD function</primary></indexterm><literal>MOD(number, divisor)</literal>: Returns the modulo of
- <literal>number</literal> and <literal>divisor</literal>.
- </para>
- <programlisting format="linespecific">
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ MOD function
+ </primary>
+ </indexterm>
+<literal>MOD(number, divisor)</literal>: Returns the modulo of <literal>number
+</literal> and <literal>divisor</literal>.
+ </para>
+<programlisting>
SELECT x FROM Magazine x WHERE MOD(x.price, 10) = 0
</programlisting>
- </listitem>
- <listitem>
- <para><indexterm><primary>CURRENT_DATE function</primary></indexterm><literal>CURRENT_DATE</literal>: Returns the current date.
- </para>
- </listitem>
- <listitem>
- <para><indexterm><primary>CURRENT_TIME function</primary></indexterm><literal>CURRENT_TIME</literal>: Returns the current time.
- </para>
- </listitem>
- <listitem>
- <para><indexterm><primary>CURRENT_TIMESTAMP function</primary></indexterm><literal>CURRENT_TIMESTAMP</literal>: Returns the current
- timestamp.
- </para>
- </listitem>
- </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ CURRENT_DATE function
+ </primary>
+ </indexterm>
+<literal>CURRENT_DATE</literal>: Returns the current date.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ CURRENT_TIME function
+ </primary>
+ </indexterm>
+<literal>CURRENT_TIME</literal>: Returns the current time.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ CURRENT_TIMESTAMP function
+ </primary>
+ </indexterm>
+<literal>CURRENT_TIMESTAMP</literal>: Returns the current timestamp.
+ </para>
+ </listitem>
+ </itemizedlist>
</section>
<section id="jpa_overview_query_inheritance">
- <title>Polymorphic Queries</title>
- <para>
- All JPQL queries are polymorphic, which means the <literal>from
- </literal> clause of a query includes not only instances of the
- specific entity class to which it refers, but all subclasses of that
- class as well. The instances returned by a query include instances
- of the subclasses that satisfy the query conditions.
- For example, the following query may return instances of <classname>
- Magazine</classname>, as well as <classname>Tabloid</classname> and
- <classname>Digest</classname> instances, where <classname>Tabloid
- </classname> and <classname>Digest</classname> are <classname>Magazine
- </classname> subclasses.
- </para>
- <programlisting format="linespecific">SELECT x FROM Magazine x WHERE x.price < 5</programlisting>
+ <title>
+ Polymorphic Queries
+ </title>
+ <para>
+All JPQL queries are polymorphic, which means the <literal>from</literal> clause
+of a query includes not only instances of the specific entity class to which it
+refers, but all subclasses of that class as well. The instances returned by a
+query include instances of the subclasses that satisfy the query conditions. For
+example, the following query may return instances of <classname> Magazine
+</classname>, as well as <classname>Tabloid</classname> and <classname>Digest
+</classname> instances, where <classname>Tabloid</classname> and <classname>
+Digest</classname> are <classname>Magazine</classname> subclasses.
+ </para>
+<programlisting>SELECT x FROM Magazine x WHERE x.price < 5
+</programlisting>
</section>
<section id="jpa_overview_query_params">
- <title>Query Parameters</title>
- <para>
- JPQL provides support for parameterized queries. Either
- named parameters or positional parameters may be specified in
- the query string. Parameters allow you to re-use query templates where
- only the input parameters vary. A single query can
- declare either named parameters or positional parameters, but
- is not allowed to declare both named and positional parameters.
- </para>
- <programlisting format="linespecific">
+ <title>
+ Query Parameters
+ </title>
+ <para>
+JPQL provides support for parameterized queries. Either named parameters or
+positional parameters may be specified in the query string. Parameters allow you
+to re-use query templates where only the input parameters vary. A single query
+can declare either named parameters or positional parameters, but is not allowed
+to declare both named and positional parameters.
+ </para>
+<programlisting>
public Query setParameter (int pos, Object value);
</programlisting>
- <para>
- Specify positional parameters in your JPQL string using an integer
- prefixed by a question mark. You can then populate the
- <classname>Query</classname> object with positional parameter values
- via calls to the <methodname>setParameter</methodname> method above.
- The method returns the <classname>Query</classname> instance for
- optional method chaining.
- </para>
- <programlisting format="linespecific">
+ <para>
+Specify positional parameters in your JPQL string using an integer prefixed by a
+question mark. You can then populate the <classname>Query</classname> object
+with positional parameter values via calls to the <methodname>setParameter
+</methodname> method above. The method returns the <classname>Query</classname>
+instance for optional method chaining.
+ </para>
+<programlisting>
EntityManager em = ...
Query q = em.createQuery ("SELECT x FROM Magazine x WHERE x.title = ?1 and x.price > ?2");
q.setParameter (1, "JDJ").setParameter (2, 5.0);
List<Magazine> results = q.getResultList ();
</programlisting>
- <para>
- This code will substitute <literal>JDJ</literal> for the <literal>?1
- </literal> parameter and <literal>5.0</literal> for the <literal>?2
- </literal> parameter, then execute the query with those values.
- </para>
- <programlisting format="linespecific">
+ <para>
+This code will substitute <literal>JDJ</literal> for the <literal>?1</literal>
+parameter and <literal>5.0</literal> for the <literal>?2</literal> parameter,
+then execute the query with those values.
+ </para>
+<programlisting>
public Query setParameter (String name, Object value);
</programlisting>
- <para>
- Named parameter are denoted by prefixing an arbitrary name with
- a colon in your JPQL string. You can then populate the <classname>
- Query</classname> object with parameter values using the method above.
- Like the positional parameter method, this method returns the
- <classname>Query</classname> instance for optional method chaining.
- </para>
- <programlisting format="linespecific">
+ <para>
+Named parameter are denoted by prefixing an arbitrary name with a colon in your
+JPQL string. You can then populate the <classname> Query</classname> object with
+parameter values using the method above. Like the positional parameter method,
+this method returns the <classname>Query</classname> instance for optional
+method chaining.
+ </para>
+<programlisting>
EntityManager em = ...
Query q = em.createQuery ("SELECT x FROM Magazine x WHERE x.title = :titleParam and x.price > :priceParam");
q.setParameter ("titleParam", "JDJ").setParameter ("priceParam", 5.0);
List<Magazine> results = q.getResultList ();
</programlisting>
- <para>
- This code substitutes <literal>JDJ</literal> for the <literal>
- :titleParam</literal> parameter and <literal>5.0</literal> for the
- <literal>:priceParam</literal> parameter, then executes the
- query with those values.
- </para>
+ <para>
+This code substitutes <literal>JDJ</literal> for the <literal> :titleParam
+</literal> parameter and <literal>5.0</literal> for the <literal>:priceParam
+</literal> parameter, then executes the query with those values.
+ </para>
</section>
<section id="jpa_overview_query_ordering">
- <title>Ordering</title>
- <para>
- JPQL queries may optionally contain an <literal>order by</literal>
- clause which specifies one or more fields to order by when returning
- query results. You may follow the <literal>order by field</literal>
- clause with the <literal>asc</literal> or <literal>desc</literal>
- keywords, which indicate that ordering should be ascending or
- descending, respectively. If the direction is omitted, ordering is
- ascending by default.
- </para>
- <programlisting format="linespecific">
+ <title>
+ Ordering
+ </title>
+ <para>
+JPQL queries may optionally contain an <literal>order by</literal> clause which
+specifies one or more fields to order by when returning query results. You may
+follow the <literal>order by field</literal> clause with the <literal>asc
+</literal> or <literal>desc</literal> keywords, which indicate that ordering
+should be ascending or descending, respectively. If the direction is omitted,
+ordering is ascending by default.
+ </para>
+<programlisting>
SELECT x FROM Magazine x order by x.title asc, x.price desc
</programlisting>
- <para>
- The query above returns <classname>Magazine</classname> instances
- sorted by their title in ascending order. In cases where the
- titles of two or more magazines are the same, those instances will be
- sorted by price in descending order.
- </para>
+ <para>
+The query above returns <classname>Magazine</classname> instances sorted by
+their title in ascending order. In cases where the titles of two or more
+magazines are the same, those instances will be sorted by price in descending
+order.
+ </para>
</section>
<section id="jpa_overview_query_aggregates">
- <title>Aggregates</title>
- <para>
- JPQL queries can select aggregate data as well as objects.
- JPQL includes the
- <literal>min</literal>, <literal>max</literal>,
- <literal>avg</literal>, and <literal>count</literal> aggregates. These
- functions can be used for reporting and summary queries.
- </para>
- <para>
- The following query will return the average of all the
- prices of all the magazines:
- </para>
- <programlisting format="linespecific">
+ <title>
+ Aggregates
+ </title>
+ <para>
+JPQL queries can select aggregate data as well as objects. JPQL includes the
+<literal>min</literal>, <literal>max</literal>, <literal>avg</literal>, and
+<literal>count</literal> aggregates. These functions can be used for reporting
+and summary queries.
+ </para>
+ <para>
+The following query will return the average of all the prices of all the
+magazines:
+ </para>
+<programlisting>
EntityManager em = ...
Query q = em.createQuery ("SELECT AVG(x.price) FROM Magazine x");
Number result = (Number) q.getSingleResult ();
</programlisting>
- <para>
- The following query will return the highest price of all
- the magazines titled "JDJ":
- </para>
- <programlisting format="linespecific">
+ <para>
+The following query will return the highest price of all the magazines titled
+"JDJ":
+ </para>
+<programlisting>
EntityManager em = ...
Query q = em.createQuery ("SELECT MAX(x.price) FROM Magazine x WHERE x.title = 'JDJ'");
Number result = (Number) q.getSingleResult ();
</programlisting>
</section>
<section id="jpa_overview_query_named">
- <title>Named Queries</title>
- <para>
- Query templates can be statically declared using the <literal>
- NamedQuery</literal> and <literal>NamedQueries</literal> annotations.
- For example:
- </para>
- <programlisting format="linespecific">
+ <title>
+ Named Queries
+ </title>
+ <para>
+Query templates can be statically declared using the <literal> NamedQuery
+</literal> and <literal>NamedQueries</literal> annotations. For example:
+ </para>
+<programlisting>
@Entity
@NamedQueries({
@NamedQuery(name="magsOverPrice",
@@ -576,24 +697,24 @@
...
}
</programlisting>
- <para>
- These declarations will define two named queries called
- <literal>magsOverPrice</literal> and <literal>magsByTitle</literal>.
- </para>
- <programlisting format="linespecific">
+ <para>
+These declarations will define two named queries called <literal>magsOverPrice
+</literal> and <literal>magsByTitle</literal>.
+ </para>
+<programlisting>
public Query createNamedQuery (String name);
</programlisting>
- <para>
- You retrieve named queries with the above <classname>EntityManager
- </classname> method. For example:
- </para>
- <programlisting format="linespecific">
+ <para>
+You retrieve named queries with the above <classname>EntityManager</classname>
+method. For example:
+ </para>
+<programlisting>
EntityManager em = ...
Query q = em.createNamedQuery ("magsOverPrice");
q.setParameter (1, 5.0f);
List<Magazine> results = q.getResultList ();
</programlisting>
- <programlisting format="linespecific">
+<programlisting>
EntityManager em = ...
Query q = em.createNamedQuery ("magsByTitle");
q.setParameter ("titleParam", "JDJ");
@@ -601,339 +722,688 @@
</programlisting>
</section>
<section id="jpa_overview_query_delete">
- <title>Delete By Query</title>
- <para>
- Queries are useful not only for finding objects, but for efficiently
- deleting them as well. For example, you might delete all records
- created before a certain date. Rather than bring these objects into
- memory and delete them individually, JPA allows you to perform a single
- bulk delete based on JPQL criteria.
- </para>
- <para>
- Delete by query uses the same JPQL syntax as normal queries, with one
- exception: begin your query string with the <literal>delete</literal>
- keyword instead of the <literal>select</literal> keyword. To then
- execute the delete, you call the following <classname>Query</classname>
- method:
- </para>
- <programlisting format="linespecific">
+ <title>
+ Delete By Query
+ </title>
+ <para>
+Queries are useful not only for finding objects, but for efficiently deleting
+them as well. For example, you might delete all records created before a certain
+date. Rather than bring these objects into memory and delete them individually,
+JPA allows you to perform a single bulk delete based on JPQL criteria.
+ </para>
+ <para>
+Delete by query uses the same JPQL syntax as normal queries, with one exception:
+begin your query string with the <literal>delete</literal> keyword instead of
+the <literal>select</literal> keyword. To then execute the delete, you call the
+following <classname>Query</classname> method:
+ </para>
+<programlisting>
public int executeUpdate ();
</programlisting>
- <para>
- This method returns the number of objects deleted.
- The following example deletes all subscriptions whose
- expiration date has passed.
- </para>
- <example id="jpa_overview_query_deleteex">
- <title>Delete by Query</title>
- <programlisting format="linespecific">
+ <para>
+This method returns the number of objects deleted. The following example deletes
+all subscriptions whose expiration date has passed.
+ </para>
+ <example id="jpa_overview_query_deleteex">
+ <title>
+ Delete by Query
+ </title>
+<programlisting>
Query q = em.createQuery ("DELETE s FROM Subscription s WHERE s.subscriptionDate < :today");
q.setParameter ("today", new Date ());
int deleted = q.executeUpdate ();
</programlisting>
- </example>
+ </example>
</section>
<section id="jpa_overview_query_update">
- <title>Update By Query</title>
- <para>
- Similar to bulk deletes, it is sometimes necessary to perform
- updates against a large number of queries in a single operation,
- without having to bring all the instances down to the client.
- Rather than bring these objects into memory and modifying
- them individually, JPA allows you to perform a single
- bulk update based on JPQL criteria.
- </para>
- <para>
- Update by query uses the same JPQL syntax as normal queries, except
- that the query string begins with the <literal>update</literal>
- keyword instead of <literal>select</literal>. To
- execute the update, you call the following <classname>Query</classname>
- method:
- </para>
- <programlisting format="linespecific">
+ <title>
+ Update By Query
+ </title>
+ <para>
+Similar to bulk deletes, it is sometimes necessary to perform updates against a
+large number of queries in a single operation, without having to bring all the
+instances down to the client. Rather than bring these objects into memory and
+modifying them individually, JPA allows you to perform a single bulk update
+based on JPQL criteria.
+ </para>
+ <para>
+Update by query uses the same JPQL syntax as normal queries, except that the
+query string begins with the <literal>update</literal> keyword instead of
+<literal>select</literal>. To execute the update, you call the following
+<classname>Query</classname> method:
+ </para>
+<programlisting>
public int executeUpdate ();
</programlisting>
- <para>
- This method returns the number of objects updated.
- The following example updates all subscriptions whose
- expiration date has passed to have the "paid" field set to true..
- </para>
- <example id="jpa_overview_query_updateex">
- <title>Update by Query</title>
- <programlisting format="linespecific">
+ <para>
+This method returns the number of objects updated. The following example updates
+all subscriptions whose expiration date has passed to have the "paid" field set
+to true..
+ </para>
+ <example id="jpa_overview_query_updateex">
+ <title>
+ Update by Query
+ </title>
+<programlisting>
Query q = em.createQuery ("UPDATE Subscription s SET s.paid = :paid WHERE s.subscriptionDate < :today");
q.setParameter ("today", new Date ());
q.setParameter ("paid", true);
int updated = q.executeUpdate ();
</programlisting>
- </example>
+ </example>
</section>
- </section>
- <section id="jpa_langref">
- <title>JPQL Language Reference</title>
+ </section>
+ <section id="jpa_langref">
+ <title>
+ JPQL Language Reference
+ </title>
<para>
- The Java Persistence query language (JPQL) is used to define searches
- against persistent entities independent of the mechanism used to
- store those entities. As such, JPQL is "portable", and not constrained to
- any particular data store. The Java
- Persistence query language is an extension of the Enterprise JavaBeans
- query language, <literal>EJB QL</literal>, adding operations such
- as bulk deletes and updates, join operations, aggregates, projections,
- and subqueries. Furthermore, JPQL queries can be declared statically in
- metadata, or can be dynamically built in code. This chapter provides the full
- definition of the language.
-
- <note><para>
- Much of this section is paraphrased or taken directly
- from Chapter 4 of the JSR 220 specification.
- </para></note>
-
- </para>
+The Java Persistence Query Language (JPQL) is used to define searches against
+persistent entities independent of the mechanism used to store those entities.
+As such, JPQL is "portable", and not constrained to any particular data store.
+The Java Persistence query language is an extension of the Enterprise JavaBeans
+query language, <literal>EJB QL</literal>, adding operations such as bulk
+deletes and updates, join operations, aggregates, projections, and subqueries.
+Furthermore, JPQL queries can be declared statically in metadata, or can be
+dynamically built in code. This chapter provides the full definition of the
+language. <note><para> Much of this section is paraphrased or taken directly
+from Chapter 4 of the JSR 220 specification.
+ </para>
+ </note>
+ </para>
<section id="jpa_langref_stmnttypes">
- <title>JPQL Statement Types</title>
- <para>
- A JPQL statement
- may be either a <literal>SELECT</literal> statement, an <literal>UPDATE</literal>
- statement, or a <literal>DELETE</literal> statement. This chapter refers to all
- such statements as "queries". Where
- it is important to distinguish among statement types, the specific
- statement type is referenced. In BNF syntax, a query language statement
- is defined as:
-
-<itemizedlist><listitem><para>QL_statement ::= select_statement | update_statement | delete_statement</para></listitem></itemizedlist>
+ <title>
+ JPQL Statement Types
+ </title>
+ <para>
+A JPQL statement may be either a <literal>SELECT</literal> statement, an
+<literal>UPDATE</literal> statement, or a <literal>DELETE</literal> statement.
+This chapter refers to all such statements as "queries". Where it is important
+to distinguish among statement types, the specific statement type is referenced.
+In BNF syntax, a query language statement is defined as: <itemizedlist>
+<listitem><para>QL_statement ::= select_statement | update_statement |
+delete_statement
+ </para>
+ </listitem>
+ </itemizedlist>
+
- The complete BNF for JPQL is defined in <xref linkend="jpa_langref_bnf"/>.
+ The complete BNF for JPQL is defined in
+ <xref linkend="jpa_langref_bnf">
+ </xref>
+ .
Any JPQL statement may be constructed
dynamically or may be statically defined in a metadata annotation or
XML descriptor element. All statement types may have parameters, as
- discussed in <xref linkend="jpa_langref_input_params"/>.
-
- </para>
- <section id="jpa_langref_select">
- <title>JPQL Select Statement</title>
- <para>
- A select statement is a string which consists of the following clauses:
+ discussed in
+ <xref linkend="jpa_langref_input_params">
+ </xref>
+ .
- <itemizedlist><listitem><para>
- a <literal>SELECT</literal> clause, which determines the type of the objects or values
- to be selected.
- </para></listitem><listitem><para>
- a <literal>FROM</literal> clause, which provides declarations that designate the domain to
- which the expressions specified in the other clauses of the query apply.
- </para></listitem><listitem><para>
- an optional <literal>WHERE</literal> clause, which may be used to restrict the results
- that are returned by the query.
- </para></listitem><listitem><para>
- an optional <literal>GROUP BY</literal> clause, which allows query results to be aggregated
- in terms of groups.
- </para></listitem><listitem><para>
- an optional <literal>HAVING</literal> clause, which allows filtering over aggregated
- groups.
- </para></listitem><listitem><para>
- an optional <literal>ORDER BY</literal> clause, which may be used to order the
- results that are returned by the query.
- </para></listitem></itemizedlist>
+
+ </para>
+ <section id="jpa_langref_select">
+ <title>
+ JPQL Select Statement
+ </title>
+ <para>
+A select statement is a string which consists of the following clauses:
+<itemizedlist><listitem><para> a <literal>SELECT</literal> clause, which
+determines the type of the objects or values to be selected.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+a <literal>FROM</literal> clause, which provides declarations that designate the
+domain to which the expressions specified in the other clauses of the query
+apply.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+an optional <literal>WHERE</literal> clause, which may be used to restrict the
+results that are returned by the query.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+an optional <literal>GROUP BY</literal> clause, which allows query results to be
+aggregated in terms of groups.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+an optional <literal>HAVING</literal> clause, which allows filtering over
+aggregated groups.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+an optional <literal>ORDER BY</literal> clause, which may be used to order the
+results that are returned by the query.
+ </para>
+ </listitem>
+ </itemizedlist>
+
In BNF syntax, a select statement is defined as:
-<itemizedlist><listitem><para>select_statement ::= select_clause from_clause [where_clause] [groupby_clause] [having_clause] [orderby_clause]</para></listitem></itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>
+select_statement ::= select_clause from_clause [where_clause] [groupby_clause]
+[having_clause] [orderby_clause]
+ </para>
+ </listitem>
+ </itemizedlist>
+
A select statement
- must always have a <literal>SELECT</literal>
- and a <literal>FROM</literal> clause. The square brackets []
+ must always have a
+ <literal>
+ SELECT
+ </literal>
+
+ and a
+ <literal>
+ FROM
+ </literal>
+ clause. The square brackets []
indicate that the other clauses are optional.
- </para>
- </section>
- <section id="jpa_langref_bulk">
- <title>JPQL Update and Delete Statements</title>
- <para>
- Update and delete statements provide bulk operations over sets of entities.
- In BNF syntax, these operations are defined as:
-
-<itemizedlist><listitem><para>update_statement ::= update_clause [where_clause]</para></listitem><listitem><para>delete_statement ::= delete_clause [where_clause]</para></listitem></itemizedlist>
+
+ </para>
+ </section>
+ <section id="jpa_langref_bulk">
+ <title>
+ JPQL Update and Delete Statements
+ </title>
+ <para>
+Update and delete statements provide bulk operations over sets of entities. In
+BNF syntax, these operations are defined as: <itemizedlist><listitem><para>
+update_statement ::= update_clause [where_clause]
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+delete_statement ::= delete_clause [where_clause]
+ </para>
+ </listitem>
+ </itemizedlist>
+
The update and delete clauses determine
the type of the entities to be updated or deleted.
- The <literal>WHERE</literal> clause may
+ The
+ <literal>
+ WHERE
+ </literal>
+ clause may
be used to restrict the scope of the update or delete operation. Update
and delete statements are described further in
- <xref linkend="jpa_langref_bulk_ops"/>.
- </para>
- </section>
+
+ <xref linkend="jpa_langref_bulk_ops">
+ </xref>
+ .
+
+ </para>
+ </section>
</section>
<section id="jpa_langref_schematypes">
- <title>JPQL Abstract Schema Types and Query Domains</title>
- <para>
- The Java Persistence query
- language is a typed language, and every expression has a type. The
- type of an expression is derived from the structure of the expression,
- the abstract schema types of the identification variable declarations,
- the types to which the persistent fields and relationships evaluate,
- and the types of literals. The abstract schema type of an entity is
- derived from the entity class and the metadata information provided by
- Java language annotations or in the XML descriptor.
- </para>
- <para>
- Informally, the abstract schema type of an entity can be characterized
- as follows:
-
- <itemizedlist><listitem><para>
- For every persistent field or get accessor method (for a persistent
- property) of the entity class, there is a field ("state-field") whose
- abstract schema type corresponds to that of the field or the result type
- of the accessor method.
- </para></listitem><listitem><para>
- For every persistent relationship field or get accessor method (for a
- persistent relationship property) of the entity class, there is a field
- ("association-field") whose type is the abstract schema type of the
- related entity (or, if the relationship is a one-to-many or many-to-many,
- a collection of such). Abstract schema types are specific to the query
- language data model. The persistence provider is not required to implement
- or otherwise materialize an abstract schema type. The domain of a query
- consists of the abstract schema types of all entities that are defined
- in the same persistence unit. The domain of a query may be restricted
- by the navigability of the relationships of the entity on which it
- is based. The association-fields of an entity's abstract schema type
- determine navigability. Using the association-fields and their values,
- a query can select related entities and use their abstract schema types
- in the query.
- </para></listitem></itemizedlist>
-
- </para>
- <section id="jpa_langref_schemanaming">
- <title>JPQL Entity Naming</title>
+ <title>
+ JPQL Abstract Schema Types and Query Domains
+ </title>
+ <para>
+The Java Persistence query language is a typed language, and every expression
+has a type. The type of an expression is derived from the structure of the
+expression, the abstract schema types of the identification variable
+declarations, the types to which the persistent fields and relationships
+evaluate, and the types of literals. The abstract schema type of an entity is
+derived from the entity class and the metadata information provided by Java
+language annotations or in the XML descriptor.
+ </para>
<para>
- Entities are designated in query strings by their entity
- names. The entity name is defined by the name element of the Entity
- annotation (or the entity-name XML descriptor element), and defaults to
- the unqualified name of the entity class. Entity names are scoped within
- the persistence unit and must be unique within the persistence unit.
-
- </para>
- </section>
- <section id="jpa_langref_schemaexample">
- <title>JPQL Schema Example</title>
- <para>
- This example assumes that the application developer
- provides several entity classes, representing magazines, publishers,
- authors, and articles.
- The abstract schema
- types for these entities are <literal>Magazine</literal>,
- <literal>Publisher</literal>, <literal>Author</literal>,
- and <literal>Article</literal>.
- </para>
- <para>
- Several Entities with Abstract Persistence Schemas Defined in the Same
- Persistence Unit. The entity <literal>Publisher</literal> has a
- one-to-many relationships with <literal>Magazine</literal>.
- There is also a one-to-many
- relationship between <literal>Magazine</literal> and
- <literal>Article</literal>. The entity <literal>Article</literal>
- is related to <literal>Author</literal> in a one-to-one relationship.
-
- </para>
- <para>
- Queries to select magazines can be defined by navigating over the
- association-fields and state-fields defined by Magazine and Author. A query
- to find all magazines that have unpublished articles is as follows:
-
-<programlisting format="linespecific">SELECT DISTINCT mag FROM Magazine AS mag JOIN mag.articles AS art WHERE art.published = FALSE</programlisting>
-
- This query navigates over the association-field authors of the
- abstract schema type <literal>Magazine</literal> to find articles,
- and uses the state-field
- <literal>published</literal> of <literal>Article</literal> to select those
- magazines that have at least one article that is published.
- Although predefined reserved identifiers,
- such as <literal>DISTINCT</literal>, <literal>FROM</literal>, <literal>AS</literal>,
- <literal>JOIN</literal>, <literal>WHERE</literal>, and <literal>FALSE</literal> appear in upper case
- in this example, predefined reserved identifiers are case insensitive. The
- <literal>SELECT</literal> clause of this example designates the return type of this query to
- be of type Magazine. Because the same persistence unit defines the abstract
- persistence schemas of the related entities, the developer can also
- specify a query over <literal>articles</literal> that utilizes the abstract
- schema type for
- products, and hence the state-fields and association-fields of both the
- abstract schema types Magazine and Author. For example, if the abstract
- schema type Author has a state-field named firstName, a query over
- articles can be specified using this state-field. Such a query might be
- to find all magazines that have articles authored by someone with the
- first name "John".
-
-<programlisting format="linespecific">SELECT DISTINCT mag FROM Magazine mag
- JOIN mag.articles art JOIN art.author auth WHERE auth.firstName = 'John'</programlisting>
-
- Because Magazine is related to Author by means of the relationships between
- Magazine and Article and between Article and Author, navigation using
- the association-fields authors and product is used to express the
- query. This query is specified by using the abstract schema name Magazine,
- which designates the abstract schema type over which the query ranges. The
- basis for the navigation is provided by the association-fields authors
- and product of the abstract schema types Magazine and Article respectively.
-
-
- </para>
- </section>
+Informally, the abstract schema type of an entity can be characterized as
+follows: <itemizedlist><listitem><para> For every persistent field or get
+accessor method (for a persistent property) of the entity class, there is a
+field ("state-field") whose abstract schema type corresponds to that of the
+field or the result type of the accessor method.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+For every persistent relationship field or get accessor method (for a persistent
+relationship property) of the entity class, there is a field
+("association-field") whose type is the abstract schema type of the related
+entity (or, if the relationship is a one-to-many or many-to-many, a collection
+of such). Abstract schema types are specific to the query language data model.
+The persistence provider is not required to implement or otherwise materialize
+an abstract schema type. The domain of a query consists of the abstract schema
+types of all entities that are defined in the same persistence unit. The domain
+of a query may be restricted by the navigability of the relationships of the
+entity on which it is based. The association-fields of an entity's abstract
+schema type determine navigability. Using the association-fields and their
+values, a query can select related entities and use their abstract schema types
+in the query.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <section id="jpa_langref_schemanaming">
+ <title>
+ JPQL Entity Naming
+ </title>
+ <para>
+Entities are designated in query strings by their entity names. The entity name
+is defined by the name element of the Entity annotation (or the entity-name XML
+descriptor element), and defaults to the unqualified name of the entity class.
+Entity names are scoped within the persistence unit and must be unique within
+the persistence unit.
+ </para>
+ </section>
+ <section id="jpa_langref_schemaexample">
+ <title>
+ JPQL Schema Example
+ </title>
+ <para>
+This example assumes that the application developer provides several entity
+classes, representing magazines, publishers, authors, and articles. The abstract
+schema types for these entities are <literal>Magazine</literal>, <literal>
+Publisher</literal>, <literal>Author</literal>, and <literal>Article</literal>.
+ </para>
+ <para>
+Several Entities with Abstract Persistence Schemas Defined in the Same
+Persistence Unit. The entity <literal>Publisher</literal> has a one-to-many
+relationships with <literal>Magazine</literal>. There is also a one-to-many
+relationship between <literal>Magazine</literal> and <literal>Article</literal>
+. The entity <literal>Article</literal> is related to <literal>Author</literal>
+in a one-to-one relationship.
+ </para>
+ <para>
+Queries to select magazines can be defined by navigating over the
+association-fields and state-fields defined by Magazine and Author. A query to
+find all magazines that have unpublished articles is as follows:
+<programlisting>SELECT DISTINCT mag FROM Magazine AS mag JOIN mag.articles AS art WHERE art.published = FALSE
+</programlisting> This query navigates over the association-field authors of the
+abstract schema type <literal>Magazine</literal> to find articles, and uses the
+state-field <literal>published</literal> of <literal>Article</literal> to select
+those magazines that have at least one article that is published. Although
+predefined reserved identifiers, such as <literal>DISTINCT</literal>, <literal>
+FROM</literal>, <literal>AS</literal>, <literal>JOIN</literal>, <literal>WHERE
+</literal>, and <literal>FALSE</literal> appear in upper case in this example,
+predefined reserved identifiers are case insensitive. The <literal>SELECT
+</literal> clause of this example designates the return type of this query to be
+of type Magazine. Because the same persistence unit defines the abstract
+persistence schemas of the related entities, the developer can also specify a
+query over <literal>articles</literal> that utilizes the abstract schema type
+for products, and hence the state-fields and association-fields of both the
+abstract schema types Magazine and Author. For example, if the abstract schema
+type Author has a state-field named firstName, a query over articles can be
+specified using this state-field. Such a query might be to find all magazines
+that have articles authored by someone with the first name "John".
+<programlisting>SELECT DISTINCT mag FROM Magazine mag
+ JOIN mag.articles art JOIN art.author auth WHERE auth.firstName = 'John'
+</programlisting> Because Magazine is related to Author by means of the
+relationships between Magazine and Article and between Article and Author,
+navigation using the association-fields authors and product is used to express
+the query. This query is specified by using the abstract schema name Magazine,
+which designates the abstract schema type over which the query ranges. The basis
+for the navigation is provided by the association-fields authors and product of
+the abstract schema types Magazine and Article respectively.
+ </para>
+ </section>
</section>
<section id="jpa_langref_fromclause">
- <title>JPQL FROM Clause and Navigational Declarations</title>
- <para>
- The <literal>FROM</literal> clause of
- a query defines the domain of the query by declaring identification
- variables. An identification variable is an identifier declared in the
- <literal>FROM</literal> clause of a query. The domain of the query may be constrained by
- path expressions. Identification variables designate instances of a
- particular entity abstract schema type. The <literal>FROM</literal> clause can contain
- multiple identification variable declarations separated by a comma (,).
- </para>
- <para>
- <itemizedlist>
- <listitem>
- <para>from_clause ::= FROM identification_variable_declaration {, {identification_variable_declaration | collection_member_declaration}}*</para>
- </listitem>
- <listitem>
- <para>identification_variable_declaration ::= range_variable_declaration { join | fetch_join }* </para>
- </listitem>
- <listitem>
- <para>range_variable_declaration ::= abstract_schema_name [AS] identification_variable</para>
- </listitem>
- <listitem>
- <para>join ::= join_spec join_association_path_expression [AS] identification_variable</para>
- </listitem>
- <listitem>
- <para>fetch_join ::= join_spec FETCH join_association_path_expression </para>
- </listitem>
- <listitem>
- <para>join_association_path_expression ::= join_collection_valued_path_expression | join_single_valued_association_path_expression </para>
- </listitem>
- <listitem>
- <para>join_spec ::= [ LEFT [OUTER] | INNER ] JOIN </para>
- </listitem>
- <listitem>
- <para>collection_member_declaration ::= IN (collection_valued_path_expression) [AS] identification_variable</para>
- </listitem>
- </itemizedlist>
- </para>
- <section id="jpa_langref_from_identifiers">
- <title>JPQL FROM Identifiers</title>
- <para>
- An identifier is a character sequence of unlimited
- length. The character sequence must begin with a Java identifier
- start character, and all other characters must be Java identifier
- part characters. An identifier start character is any character for
- which the method <methodname>Character.isJavaIdentifierStart</methodname>
- returns <literal>true</literal>. This
- includes the underscore (_) character and the dollar sign ($)
- character. An identifier part character is any character for which
- the method <methodname>Character.isJavaIdentifierPart</methodname>
- returns <literal>true</literal>. The question
- mark (?) character is reserved for use by the Java Persistence query
- language. The following are reserved identifiers:
-
- <itemizedlist><listitem><para><literal>SELECT</literal></para></listitem><listitem><para><literal>FROM</literal></para></listitem><listitem><para><literal>WHERE</literal></para></listitem><listitem><para><literal>UPDATE</literal></para></listitem><listitem><para><literal>DELETE</literal></para></listitem><listitem><para><literal>JOIN</literal></para></listitem><listitem><para><literal>OUTER</literal></para></listitem><listitem><para><literal>INNER</literal></para></listitem><listitem><para><literal>LEFT</literal></para></listitem><listitem><para><literal>GROUP</literal></para></listitem><listitem><para><literal>BY</literal></para></listitem><listitem><para><literal>HAVING</literal></para></listitem><listitem><para><literal>FETCH</literal></para></listitem><listitem><para><literal>DISTINCT</literal></para></listitem><listitem><para><literal>OBJECT</literal></para></listitem><listitem><para><literal>NULL</literal></para></listitem><listitem><para><literal>TRUE</literal><
/para></listitem><listitem><para><literal>FALSE</literal></para></listitem><listitem><para><literal>NOT</literal></para></listitem><listitem><para><literal>AND</literal></para></listitem><listitem><para><literal>OR</literal></para></listitem><listitem><para><literal>BETWEEN</literal></para></listitem><listitem><para><literal>LIKE</literal></para></listitem><listitem><para><literal>IN</literal></para></listitem><listitem><para><literal>AS</literal></para></listitem><listitem><para><literal>UNKNOWN</literal></para></listitem><listitem><para><literal>EMPTY</literal></para></listitem><listitem><para><literal>MEMBER</literal></para></listitem><listitem><para><literal>OF</literal></para></listitem><listitem><para><literal>IS</literal></para></listitem><listitem><para><literal>AVG</literal></para></listitem><listitem><para><literal>MAX</literal></para></listitem><listitem><para><literal>MIN</literal></para></listitem><listitem><para><literal>SUM</literal></para></listitem><listitem
><para><literal>COUNT</literal></para></listitem><listitem><para><literal>ORDER</literal></para></listitem><listitem><para><literal>BY</literal></para></listitem><listitem><para><literal>ASC</literal></para></listitem><listitem><para><literal>DESC</literal></para></listitem><listitem><para><literal>MOD</literal></para></listitem><listitem><para><literal>UPPER</literal></para></listitem><listitem><para><literal>LOWER</literal></para></listitem><listitem><para><literal>TRIM</literal></para></listitem><listitem><para><literal>POSITION</literal></para></listitem><listitem><para><literal>CHARACTER_LENGTH</literal></para></listitem><listitem><para><literal>CHAR_LENGTH</literal></para></listitem><listitem><para><literal>BIT_LENGTH</literal></para></listitem><listitem><para><literal>CURRENT_TIME</literal></para></listitem><listitem><para><literal>CURRENT_DATE</literal></para></listitem><listitem><para><literal>CURRENT_TIMESTAMP</literal></para></listitem><listitem><para><literal>NEW
</literal></para></listitem><listitem><para><literal>EXISTS</literal></para></listitem><listitem><para><literal>ALL</literal></para></listitem><listitem><para><literal>ANY</literal></para></listitem><listitem><para><literal>SOME</literal></para></listitem></itemizedlist>
+ <title>
+ JPQL FROM Clause and Navigational Declarations
+ </title>
+ <para>
+The <literal>FROM</literal> clause of a query defines the domain of the query by
+declaring identification variables. An identification variable is an identifier
+declared in the <literal>FROM</literal> clause of a query. The domain of the
+query may be constrained by path expressions. Identification variables designate
+instances of a particular entity abstract schema type. The <literal>FROM
+</literal> clause can contain multiple identification variable declarations
+separated by a comma (,).
+ </para>
+ <para>
+<itemizedlist><listitem><para>from_clause ::= FROM
+identification_variable_declaration {, {identification_variable_declaration |
+collection_member_declaration}}*
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+identification_variable_declaration ::= range_variable_declaration { join |
+fetch_join }*
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+range_variable_declaration ::= abstract_schema_name [AS] identification_variable
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+join ::= join_spec join_association_path_expression [AS] identification_variable
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+fetch_join ::= join_spec FETCH join_association_path_expression
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+join_association_path_expression ::= join_collection_valued_path_expression |
+join_single_valued_association_path_expression
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+join_spec ::= [ LEFT [OUTER] | INNER ] JOIN
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+collection_member_declaration ::= IN (collection_valued_path_expression) [AS]
+identification_variable
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <section id="jpa_langref_from_identifiers">
+ <title>
+ JPQL FROM Identifiers
+ </title>
+ <para>
+An identifier is a character sequence of unlimited length. The character
+sequence must begin with a Java identifier start character, and all other
+characters must be Java identifier part characters. An identifier start
+character is any character for which the method <methodname>
+Character.isJavaIdentifierStart</methodname> returns <literal>true</literal>.
+This includes the underscore (_) character and the dollar sign ($) character. An
+identifier part character is any character for which the method <methodname>
+Character.isJavaIdentifierPart</methodname> returns <literal>true</literal>.
+The question mark (?) character is reserved for use by the Java Persistence
+query language. The following are reserved identifiers: <itemizedlist>
+<listitem><para><literal>SELECT</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>FROM</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>WHERE</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>UPDATE</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>DELETE</literal>
+ </para>
+ </listitem>
[... 3756 lines stripped ...]