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/10/03 00:22:21 UTC
svn commit: r452243 [3/6] - in /incubator/openjpa/trunk:
openjpa-jdbc/src/main/java/org/apache/openjpa/jdbc/kernel/
openjpa-jdbc/src/main/java/org/apache/openjpa/jdbc/schema/
openjpa-kernel/src/main/java/org/apache/openjpa/kernel/
openjpa-kernel/src/ma...
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?view=diff&rev=452243&r1=452242&r2=452243
==============================================================================
--- 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 Mon Oct 2 15:22:18 2006
@@ -51,7 +51,7 @@
entities.
</para>
<programlisting>
-public Query createQuery (String jpql);
+public Query createQuery(String jpql);
</programlisting>
<para>
The
@@ -60,7 +60,7 @@
<classname>Query</classname> instance from a given JPQL string.
</para>
<programlisting>
-public List getResultList ();
+public List getResultList();
</programlisting>
<para>
Invoking
@@ -71,8 +71,8 @@
</para>
<programlisting>
EntityManager em = ...
-Query q = em.createQuery ("SELECT x FROM Magazine x");
-List<Magazine> results = q.getResultList ();
+Query q = em.createQuery("SELECT x FROM Magazine x");
+List<Magazine> results = (List<Magazine>) q.getResultList();
</programlisting>
<para>
A JPQL query has an internal namespace declared in the <literal>from</literal>
@@ -105,20 +105,17 @@
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>
+<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>
+<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>
+<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
@@ -568,8 +565,7 @@
</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>
+<programlisting>SELECT x FROM Magazine x WHERE x.price < 5</programlisting>
</section>
<section id="jpa_overview_query_params">
<title>
@@ -594,9 +590,9 @@
</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 ();
+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 = (List<Magazine>) q.getResultList();
</programlisting>
<para>
This code will substitute <literal>JDJ</literal> for the <literal>?1</literal>
@@ -604,7 +600,7 @@
then execute the query with those values.
</para>
<programlisting>
-public Query setParameter (String name, Object value);
+public Query setParameter(String name, Object value);
</programlisting>
<para>
Named parameter are denoted by prefixing an arbitrary name with a colon in your
@@ -615,9 +611,9 @@
</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 ();
+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 = (List<Magazine>) q.getResultList();
</programlisting>
<para>
This code substitutes <literal>JDJ</literal> for the <literal> :titleParam
@@ -663,8 +659,8 @@
</para>
<programlisting>
EntityManager em = ...
-Query q = em.createQuery ("SELECT AVG(x.price) FROM Magazine x");
-Number result = (Number) q.getSingleResult ();
+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
@@ -672,8 +668,8 @@
</para>
<programlisting>
EntityManager em = ...
-Query q = em.createQuery ("SELECT MAX(x.price) FROM Magazine x WHERE x.title = 'JDJ'");
-Number result = (Number) q.getSingleResult ();
+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">
@@ -692,8 +688,7 @@
@NamedQuery(name="magsByTitle",
query="SELECT x FROM Magazine x WHERE x.title = :titleParam")
})
-public class Magazine
-{
+public class Magazine {
...
}
</programlisting>
@@ -702,7 +697,7 @@
</literal> and <literal>magsByTitle</literal>.
</para>
<programlisting>
-public Query createNamedQuery (String name);
+public Query createNamedQuery(String name);
</programlisting>
<para>
You retrieve named queries with the above <classname>EntityManager</classname>
@@ -710,15 +705,15 @@
</para>
<programlisting>
EntityManager em = ...
-Query q = em.createNamedQuery ("magsOverPrice");
-q.setParameter (1, 5.0f);
-List<Magazine> results = q.getResultList ();
+Query q = em.createNamedQuery("magsOverPrice");
+q.setParameter(1, 5.0f);
+List<Magazine> results = q.getResultList();
</programlisting>
<programlisting>
EntityManager em = ...
-Query q = em.createNamedQuery ("magsByTitle");
-q.setParameter ("titleParam", "JDJ");
-List<Magazine> results = q.getResultList ();
+Query q = em.createNamedQuery("magsByTitle");
+q.setParameter("titleParam", "JDJ");
+List<Magazine> results = q.getResultList();
</programlisting>
</section>
<section id="jpa_overview_query_delete">
@@ -738,7 +733,7 @@
following <classname>Query</classname> method:
</para>
<programlisting>
-public int executeUpdate ();
+public int executeUpdate();
</programlisting>
<para>
This method returns the number of objects deleted. The following example deletes
@@ -749,9 +744,9 @@
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 ();
+Query q = em.createQuery("DELETE s FROM Subscription s WHERE s.subscriptionDate < :today");
+q.setParameter("today", new Date());
+int deleted = q.executeUpdate();
</programlisting>
</example>
</section>
@@ -773,7 +768,7 @@
<classname>Query</classname> method:
</para>
<programlisting>
-public int executeUpdate ();
+public int executeUpdate();
</programlisting>
<para>
This method returns the number of objects updated. The following example updates
@@ -785,10 +780,10 @@
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 ();
+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>
</section>
@@ -806,11 +801,14 @@
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>
+language.
</para>
+ <note>
+ <para>
+Much of this section is paraphrased or taken directly from Chapter 4 of the
+JSR 220 specification.
+ </para>
+ </note>
<section id="jpa_langref_stmnttypes">
<title>
JPQL Statement Types
@@ -820,28 +818,20 @@
<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"/>
-
- .
-
- 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"/>
-
- .
-
-
+In BNF syntax, a query language statement is defined as:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+QL_statement ::= select_statement | update_statement | delete_statement
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+The complete BNF for JPQL is defined in <xref linkend="jpa_langref_bnf"/>.
+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>
@@ -849,71 +839,61 @@
</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>
+ </para>
+ <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>
+ </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>
+ </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>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
an optional <literal>HAVING</literal> clause, which allows filtering over
aggregated groups.
- </para>
- </listitem>
- <listitem>
- <para>
+ </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>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+In BNF syntax, a select statement is defined as:
+ </para>
+ <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 []
- indicate that the other clauses are optional.
-
-
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+A select statement 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">
@@ -922,32 +902,25 @@
</title>
<para>
Update and delete statements provide bulk operations over sets of entities. In
-BNF syntax, these operations are defined as: <itemizedlist><listitem><para>
+BNF syntax, these operations are defined as:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
update_statement ::= update_clause [where_clause]
- </para>
- </listitem>
- <listitem>
- <para>
+ </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
- 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>
+ </listitem>
+ </itemizedlist>
+ <para>
+The update and delete clauses determine the type of the entities to be updated
+or deleted. 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>
</section>
@@ -966,14 +939,19 @@
</para>
<para>
Informally, the abstract schema type of an entity can be characterized as
-follows: <itemizedlist><listitem><para> For every persistent field or get
+follows:
+ </para>
+ <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>
+ </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
@@ -987,10 +965,9 @@
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>
+ </para>
+ </listitem>
+ </itemizedlist>
<section id="jpa_langref_schemanaming">
<title>
JPQL Entity Naming
@@ -1025,27 +1002,35 @@
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
+ </para>
+<programlisting>
+SELECT DISTINCT mag FROM Magazine AS mag JOIN mag.articles AS art WHERE art.published = FALSE
+</programlisting>
+ <para>
+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
+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".
+ </para>
+<programlisting>
+SELECT DISTINCT mag FROM Magazine mag JOIN mag.articles art JOIN art.author auth WHERE auth.firstName = 'John'
+</programlisting>
+ <para>
+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,
@@ -1068,41 +1053,42 @@
</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>
+ <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>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
range_variable_declaration ::= abstract_schema_name [AS] identification_variable
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
join ::= join_spec join_association_path_expression [AS] identification_variable
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
fetch_join ::= join_spec FETCH join_association_path_expression
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
join_association_path_expression ::= join_collection_valued_path_expression |
join_single_valued_association_path_expression
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
join_spec ::= [ LEFT [OUTER] | INNER ] JOIN
</para>
</listitem>
@@ -1110,10 +1096,9 @@
<para>
collection_member_declaration ::= IN (collection_valued_path_expression) [AS]
identification_variable
- </para>
- </listitem>
- </itemizedlist>
- </para>
+ </para>
+ </listitem>
+ </itemizedlist>
<section id="jpa_langref_from_identifiers">
<title>
JPQL FROM Identifiers
@@ -1128,157 +1113,161 @@
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>
+query language. The following are reserved identifiers:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>SELECT</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
<literal>FROM</literal>
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
<literal>WHERE</literal>
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
<literal>UPDATE</literal>
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
<literal>DELETE</literal>
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
<literal>JOIN</literal>
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
<literal>OUTER</literal>
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
<literal>INNER</literal>
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
<literal>LEFT</literal>
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
<literal>GROUP</literal>
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
<literal>BY</literal>
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
<literal>HAVING</literal>
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
<literal>FETCH</literal>
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
<literal>DISTINCT</literal>
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
<literal>OBJECT</literal>
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
<literal>NULL</literal>
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
<literal>TRUE</literal>
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
<literal>FALSE</literal>
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
<literal>NOT</literal>
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
<literal>AND</literal>
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
<literal>OR</literal>
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
<literal>BETWEEN</literal>
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
<literal>LIKE</literal>
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
<literal>IN</literal>
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
<literal>AS</literal>
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
<literal>UNKNOWN</literal>
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
<literal>EMPTY</literal>
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
<literal>MEMBER</literal>
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
<literal>OF</literal>
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
<literal>IS</literal>
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
<literal>AVG</literal>
</para>
</listitem>
@@ -1400,18 +1389,14 @@
<listitem>
<para>
<literal>SOME</literal>
- </para>
- </listitem>
- </itemizedlist>
-
-
- Reserved identifiers are
- case insensitive. Reserved identifiers must not be used as identification
- variables. It is recommended that other SQL reserved words also not
- be as identification variables in queries because they may be used as
- reserved identifiers in future releases of the specification.
-
-
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+Reserved identifiers are case insensitive. Reserved identifiers must not be
+used as identification variables. It is recommended that other SQL reserved
+words also not be as identification variables in queries because they may be
+used as reserved identifiers in future releases of the specification.
</para>
</section>
<section id="jpa_langref_from_vars">
@@ -1453,13 +1438,16 @@
</title>
<para>
The syntax for declaring an identification variable as a range variable is
-similar to that of SQL; optionally, it uses the AS keyword. <itemizedlist>
-<listitem><para>range_variable_declaration ::= abstract_schema_name [AS]
-identification_variable
- </para>
- </listitem>
- </itemizedlist>
+similar to that of SQL; optionally, it uses the AS keyword.
</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+range_variable_declaration ::= abstract_schema_name [AS]
+identification_variable
+ </para>
+ </listitem>
+ </itemizedlist>
<para>
Range variable declarations allow the developer to designate a "root" for
objects which may not be reachable by navigation. In order to select values by
@@ -1473,10 +1461,12 @@
of two different identification variables in the <literal>FROM</literal> clause,
both of the abstract schema type Magazine. The <literal>SELECT</literal> clause
of this query determines that it is the magazines with prices greater than those
-of "Adventure" publisher's that are returned. <programlisting>SELECT DISTINCT mag1 FROM Magazine mag1, Magazine mag2
+of "Adventure" publisher's that are returned.
+ </para>
+<programlisting>
+SELECT DISTINCT mag1 FROM Magazine mag1, Magazine mag2
WHERE mag1.price > mag2.price AND mag2.publisher.name = 'Adventure'
</programlisting>
- </para>
</section>
<section id="jpa_langref_path">
<title>
@@ -1497,9 +1487,11 @@
the result. The syntax for single-valued path expressions and collection valued
path expressions is as follows:
</para>
- <para>
-<itemizedlist><listitem><para>single_valued_path_expression ::=
-state_field_path_expression | single_valued_association_path_expression
+ <itemizedlist>
+ <listitem>
+ <para>
+single_valued_path_expression ::= state_field_path_expression |
+single_valued_association_path_expression
</para>
</listitem>
<listitem>
@@ -1523,10 +1515,9 @@
<listitem>
<para>
state_field ::= {embedded_class_state_field.}*simple_state_field
- </para>
- </listitem>
- </itemizedlist>
- </para>
+ </para>
+ </listitem>
+ </itemizedlist>
<para>
A single_valued_association_field is designated by the name of an
association-field in a one-to-one or many-to-one relationship. The type of a
@@ -1569,13 +1560,14 @@
<para>
The syntax for explicit join operations is as follows:
</para>
- <para>
-<itemizedlist><listitem><para>join ::= join_spec
-join_association_path_expression [AS] identification_variable
- </para>
- </listitem>
- <listitem>
- <para>
+ <itemizedlist>
+ <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>
@@ -1588,10 +1580,9 @@
<listitem>
<para>
join_spec ::= [ LEFT [OUTER] | INNER ] JOIN
- </para>
- </listitem>
- </itemizedlist>
- </para>
+ </para>
+ </listitem>
+ </itemizedlist>
<para>
The following inner and outer join operation types are supported.
</para>
@@ -1604,16 +1595,25 @@
[ INNER ] JOIN join_association_path_expression [AS] identification_variable
</programlisting> For example, the query below joins over the relationship
between publishers and magazines. This type of join typically equates to a join
-over a foreign key relationship in the database. <programlisting>SELECT pub FROM Publisher pub JOIN pub.magazines mag WHERE pub.revenue > 1000000
+over a foreign key relationship in the database.
+ </para>
+<programlisting>
+SELECT pub FROM Publisher pub JOIN pub.magazines mag WHERE pub.revenue > 1000000
</programlisting>
+ <para>
+The keyword <literal>INNER</literal> may optionally be used:
</para>
+<programlisting>
+SELECT pub FROM Publisher pub INNER JOIN pub.magazines mag WHERE pub.revenue > 1000000
+</programlisting>
<para>
-The keyword <literal>INNER</literal> may optionally be used: <programlisting>SELECT pub FROM Publisher pub INNER JOIN pub.magazines mag WHERE pub.revenue > 1000000
-</programlisting> This is equivalent to the following query using the earlier
+This is equivalent to the following query using the earlier
<literal>IN</literal> construct. It selects those publishers with revenue of
-over 1 million for which at least one magazine exists: <programlisting>SELECT OBJECT(pub) FROM Publisher pub, IN(pub.magazines) mag WHERE pub.revenue > 1000000
-</programlisting>
+over 1 million for which at least one magazine exists:
</para>
+<programlisting>
+SELECT OBJECT(pub) FROM Publisher pub, IN(pub.magazines) mag WHERE pub.revenue > 1000000
+</programlisting>
</section>
<section id="jpa_langref_outer_joins">
<title>
Modified: incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_sqlquery.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_sqlquery.xml?view=diff&rev=452243&r1=452242&r2=452243
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_sqlquery.xml (original)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_sqlquery.xml Mon Oct 2 15:22:18 2006
@@ -81,8 +81,8 @@
creating SQL queries:
</para>
<programlisting>
-public Query createNativeQuery (String sqlString, Class resultClass);
-public Query createNativeQuery (String sqlString, String resultSetMapping);
+public Query createNativeQuery(String sqlString, Class resultClass);
+public Query createNativeQuery(String sqlString, String resultSetMapping);
</programlisting>
<para>
The first method is used to create a new <classname>Query</classname> instance
@@ -99,8 +99,8 @@
</title>
<programlisting>
EntityManager em = ...;
-Query query = em.createNativeQuery ("SELECT * FROM MAG", Magazine.class);
-processMagazines (query.getResultList ());
+Query query = em.createNativeQuery("SELECT * FROM MAG", Magazine.class);
+processMagazines(query.getResultList());
</programlisting>
</example>
<note>
@@ -182,7 +182,6 @@
<imageobject>
<!-- PNG image data, 320 x 149 (see README) -->
<imagedata fileref="img/sqlquery-model.png" width="213px"/>
-
</imageobject>
</mediaobject>
<example id="jpa_overview_sqlquery_objex">
@@ -190,11 +189,11 @@
Retrieving Persistent Objects
</title>
<programlisting>
-Query query = em.createNativeQuery ("SELECT ISBN, TITLE, PRICE, "
+Query query = em.createNativeQuery("SELECT ISBN, TITLE, PRICE, "
+ "VERS FROM MAG WHERE PRICE > 5 AND PRICE < 10", Magazine.class);
-List<Magazine> results = query.getResultList ();
+List<Magazine> results = (List<Magazine>) query.getResultList();
for (Magazine mag : results)
- processMagazine (mag);
+ processMagazine(mag);
</programlisting>
</example>
<para>
@@ -207,13 +206,13 @@
SQL Query Parameters
</title>
<programlisting>
-Query query = em.createNativeQuery ("SELECT ISBN, TITLE, PRICE, "
+Query query = em.createNativeQuery("SELECT ISBN, TITLE, PRICE, "
+ "VERS FROM MAG WHERE PRICE > ?1 AND PRICE < ?2", Magazine.class);
-query.setParameter (1, 5d);
-query.setParameter (2, 10d);
+query.setParameter(1, 5d);
+query.setParameter(2, 10d);
-List<Magazine> results = query.getResultList ();
+List<Magazine> results = (List<Magazine>) query.getResultList();
for (Magazine mag : results)
processMagazine (mag);
</programlisting>
Modified: incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_trans.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_trans.xml?view=diff&rev=452243&r1=452242&r2=452243
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_trans.xml (original)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_trans.xml Mon Oct 2 15:22:18 2006
@@ -140,10 +140,9 @@
something like this:
</para>
<programlisting>
-public void transferFunds (User from, User to, double amnt)
-{
- from.decrementAccount (amnt);
- to.incrementAccount (amnt);
+public void transferFunds(User from, User to, double amnt) {
+ from.decrementAccount(amnt);
+ to.incrementAccount(amnt);
}
</programlisting>
<para>
@@ -280,8 +279,8 @@
OpenJPA uses optimistic semantics by default, but supports both optimistic and
datastore transactions. OpenJPA also offers advanced locking and versioning APIs
for fine-grained control over database resource allocation and object
-versioning. See <xref linkend="ref_guide_locking"/> of the Reference Guide for details
-on locking. <xref linkend="jpa_overview_meta_version"/>
+versioning. See <xref linkend="ref_guide_locking"/> of the Reference Guide for
+details on locking. <xref linkend="jpa_overview_meta_version"/>
of this document covers standard object versioning, while
<xref linkend="ref_guide_mapping_jpa"/> of the Reference Guide discusses
additional versioning strategies available in OpenJPA.
@@ -312,13 +311,13 @@
allowing you to use the container's declarative transaction demarcation and its
Java Transaction API (JTA) implementation for transaction management. Outside of
a container, though, you must demarcate transactions manually through JPA. The
-<classname> EntityTransaction</classname> interface controls unmanaged
+<classname>EntityTransaction</classname> interface controls unmanaged
transactions in JPA.
</para>
<programlisting>
-public void begin ();
-public void commit ();
-public void rollback ();
+public void begin();
+public void commit();
+public void rollback();
</programlisting>
<para>
<indexterm>
@@ -376,7 +375,7 @@
<classname>EntityManager</classname>.
</para>
<programlisting>
-public boolean isActive ();
+public boolean isActive();
</programlisting>
<para>
<indexterm>
@@ -388,31 +387,30 @@
</secondary>
</indexterm>
Finally, the <methodname>isActive</methodname> method returns <literal>true
-</literal> if the transaction is in progress ( <methodname>begin</methodname>
+</literal> if the transaction is in progress (<methodname>begin</methodname>
has been called more recently than <methodname>commit</methodname> or
-<methodname>rollback</methodname> ), and <literal>false</literal> otherwise.
+<methodname>rollback</methodname>), and <literal>false</literal> otherwise.
</para>
<example id="jpa_overview_trans_group">
<title>
Grouping Operations with Transactions
</title>
<programlisting>
-public void transferFunds (EntityManager em, User from, User to, double amnt)
-{
+public void transferFunds(EntityManager em, User from, User to, double amnt) {
// note: it would be better practice to move the transaction demarcation
// code out of this method, but for the purposes of example...
- Transaction trans = em.getTransaction ();
- trans.begin ();
+ Transaction trans = em.getTransaction();
+ trans.begin();
try
{
- from.decrementAccount (amnt);
- to.incrementAccount (amnt);
- trans.commit ();
+ from.decrementAccount(amnt);
+ to.incrementAccount(amnt);
+ trans.commit();
}
catch (RuntimeException re)
{
- if (trans.isActive ())
- trans.rollback (); // or could attempt to fix error and retry
+ if (trans.isActive())
+ trans.rollback(); // or could attempt to fix error and retry
throw re;
}
}
Modified: incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_why.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_why.xml?view=diff&rev=452243&r1=452242&r2=452243
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_why.xml (original)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_why.xml Mon Oct 2 15:22:18 2006
@@ -287,9 +287,7 @@
</row>
<row>
<entry colname="sup">
-
- Relational and Non-Relational Stores
-
+ Relational and Non-Relational Stores
</entry>
<entry colname="ser">
No
Modified: incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_resources.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_resources.xml?view=diff&rev=452243&r1=452242&r2=452243
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_resources.xml (original)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_resources.xml Mon Oct 2 15:22:18 2006
@@ -22,7 +22,7 @@
</listitem>
<listitem>
<para>
-<ulink url="../../api/index.html">OpenJPA API Javadoc</ulink>
+<ulink url="../apidocs/index.html">OpenJPA API Javadoc</ulink>
</para>
</listitem>
<listitem>
Modified: incubator/openjpa/trunk/openjpa-project/src/doc/manual/manual.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/manual.xml?view=diff&rev=452243&r1=452242&r2=452243
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/manual.xml (original)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/manual.xml Mon Oct 2 15:22:18 2006
@@ -37,7 +37,7 @@
]>
<book id="manual">
<bookinfo>
- <title>OpenJPA Developers Guide</title>
+ <title>OpenJPA User's Guide</title>
</bookinfo>
<part id="introduction">
@@ -62,13 +62,16 @@
&jpa_overview_conclusion.xml;
</part>
+ <!--
+ ### TUTORIAL
<part id="tutorials">
<title>Tutorials</title>
&jpa_tutorials.xml;
</part>
+ -->
<part id="ref_guide">
- <title>OpenJPA <phrase>JPA</phrase> Reference Guide</title>
+ <title>Reference Guide</title>
&ref_guide_intro.xml;
&ref_guide_conf.xml;
&ref_guide_logging.xml;
@@ -84,10 +87,12 @@
&ref_guide_optimization.xml;
</part>
+ <!--
<part id="samples_guide_part">
- <title>OpenJPA <phrase>JPA</phrase> Samples</title>
+ <title>Samples</title>
&samples_guide.xml;
</part>
+ -->
&jpa_resources.xml;
&supported_databases.xml;
Modified: incubator/openjpa/trunk/openjpa-project/src/doc/manual/openjpa_intro.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/openjpa_intro.xml?view=diff&rev=452243&r1=452242&r2=452243
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/openjpa_intro.xml (original)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/openjpa_intro.xml Mon Oct 2 15:22:18 2006
@@ -1,30 +1,27 @@
<chapter id="openjpa_intro">
<title>
OpenJPA
- <phrase>
- JPA
- </phrase>
</title>
<indexterm zone="openjpa_intro">
<primary>
OpenJPA
- <phrase>
- JPA
- </phrase>
</primary>
</indexterm>
<para>
-OpenJPA is Apache's implementation of Sun's <phrase>Java Persistence API (JPA)
-specification</phrase> for the transparent persistence of Java objects. This
-document provides an overview of <phrase>the JPA standard</phrase> and technical
+OpenJPA is Apache's implementation of Sun's Java Persistence API (JPA)
+specification for the transparent persistence of Java objects. This
+document provides an overview of the JPA standard and technical
details on the use of OpenJPA.
</para>
+<!--
+### TUTORIAL
<para>
-To quickly get started with JPA, you may want to begin at
+To quickly get started with OpenJPA, you may want to begin at
<xref linkend="jpa_tutorial"/>. If you would prefer to start with an
-introduction to the concepts of JPA, begin with
+introduction to the JPA specification, begin with
<xref linkend="jpa_overview_intro"/>.
</para>
+-->
<section id="openjpa_intro_about">
<title>
About This Document
@@ -36,25 +33,27 @@
<listitem>
<para>
The <link linkend="jpa_overview_intro">JPA Overview</link> describes the
-fundamentals of JPA.
+fundamentals of the JPA specification.
</para>
</listitem>
+<!--
+### TUTORIAL
<listitem>
<para>
-In the <link linkend="tutorials">OpenJPA <phrase>JPA</phrase> Tutorials</link>
-you will develop simple persistent applications using OpenJPA. Through the
+In the <link linkend="tutorials">OpenJPA Tutorials</link> you will develop
+simple persistent applications using OpenJPA. Through the
tutorials' hands-on approach, you will become comfortable with the core tools
-and development processes under OpenJPA <phrase>JPA</phrase>.
+and development processes under OpenJPA.
</para>
</listitem>
+-->
<listitem>
<para>
-The <link linkend="ref_guide_intro">OpenJPA <phrase>JPA</phrase> Reference Guide
-</link> contains detailed documentation on all aspects of OpenJPA <phrase>JPA
-</phrase>. Browse through this guide to familiarize yourself with the many
-advanced features and customization opportunities OpenJPA provides. Later, you
-can use the guide when you need details on a specific aspect of OpenJPA <phrase>
-JPA</phrase>.
+The <link linkend="ref_guide_intro">OpenJPA Reference Guide</link> contains
+detailed documentation on all aspects of OpenJPA. Browse through this guide
+to familiarize yourself with the many advanced features and customization
+opportunities OpenJPA provides. Later, you can use the guide when you need
+details on a specific aspect of OpenJPA.
</para>
</listitem>
</itemizedlist>
Modified: incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_caching.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_caching.xml?view=diff&rev=452243&r1=452242&r2=452243
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_caching.xml (original)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_caching.xml Mon Oct 2 15:22:18 2006
@@ -289,7 +289,8 @@
<para>
Rather than use the low-level <literal>org.apache.openjpa.datacache</literal>
package APIs, JPA users should typically access the data cache through OpenJPA's
-high-level <ulink url="../../api/openjpa/persistence/StoreCache.html">
+high-level
+<ulink url="../apidocs/org/apache/openjpa/persistence/StoreCache.html">
<classname>org.apache.openjpa.persistence.StoreCache</classname></ulink> facade.
This facade has methods to pin and unpin records, evict data from the cache, and
more.
@@ -309,7 +310,7 @@
</para>
<para>
If you know that you want to access a certain data cache and no others, the
-<ulink url="../../api/openjpa/persistence/OpenJPAEntityManagerFactory.html">
+<ulink url="../apidocs/org/apache/openjpa/persistence/OpenJPAEntityManagerFactory.html">
<methodname>OpenJPAEntityManagerFactory.getStoreCache(String name)</methodname>
</ulink> method returns a <classname>StoreCache</classname> interface to a
particular named data cache.
@@ -381,8 +382,8 @@
</example>
<para>
See the <classname>StoreCache</classname>
-<ulink url="../../api/openjpa/persistence/StoreCache.html">Javadoc</ulink> for
-information on additional functionality it provides. Also,
+<ulink url="../apidocs/org/apache/openjpa/persistence/StoreCache.html">
+Javadoc</ulink> for information on additional functionality it provides. Also,
<xref linkend="ref_guide_runtime"/> discusses OpenJPA's other extensions
to the standard set of JPA runtime interfaces.
</para>
@@ -445,10 +446,10 @@
</para>
<para>
OpenJPA exposes a high-level interface to the query cache through the
-<ulink url="../../api/openjpa/persistence/QueryResultCache.html"><classname>
-org.apache.openjpa.persistence.QueryResultCache</classname></ulink> class. You
-can access this class through the <classname> OpenJPAEntityManagerFactory
-</classname>.
+<ulink url="../apidocs/org/apache/openjpa/persistence/QueryResultCache.html">
+<classname>org.apache.openjpa.persistence.QueryResultCache</classname></ulink>
+class. You can access this class through the <classname>
+OpenJPAEntityManagerFactory</classname>.
</para>
<example id="ref_guide_cache_queryaccess">
<title>
@@ -825,8 +826,8 @@
<listitem>
<para>
<literal>ClearOnClose</literal>: Whether the Tangosol named cache should be
-completely cleared when the <phrase><classname>EntityManagerFactory</classname>
-</phrase> is closed. Defaults to <literal>false</literal>.
+completely cleared when the <classname>EntityManagerFactory</classname>
+is closed. Defaults to <literal>false</literal>.
</para>
</listitem>
</itemizedlist>