Added:
websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/jpa_langref.html
==============================================================================
---
websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/jpa_langref.html
(added)
+++
websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/jpa_langref.html
Fri Jan 6 19:19:20 2017
@@ -0,0 +1,3863 @@
+<html><head>
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+ <title>2. JPQL Language Reference</title><base href="display"><link
rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator"
content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="manual.html"
title="Apache OpenJPA 2.4 User's Guide"><link rel="up"
href="jpa_overview_query.html" title="Chapter 10. JPA Query"><link
rel="prev" href="jpa_overview_query.html" title="Chapter 10. JPA
Query"><link rel="next" href="jpa_overview_criteria.html"
title="Chapter 11. JPA Criteria"></head><body bgcolor="white"
text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div
class="navheader"><table width="100%" summary="Navigation header"><tr><th
colspan="3" align="center">2.
+ JPQL Language Reference
+ </th></tr><tr><td width="20%" align="left"><a accesskey="p"
href="jpa_overview_query.html">Prev</a> </td><th width="60%"
align="center">Chapter 10.
+ JPA Query
+ </th><td width="20%" align="right"> <a accesskey="n"
href="jpa_overview_criteria.html">Next</a></td></tr></table><hr></div><div
class="section" id="jpa_langref"><div class="titlepage"><div><div><h2
class="title" style="clear: both">2.
+ JPQL Language Reference
+ </h2></div></div></div><div class="toc"><dl class="toc"><dt><span
class="section"><a href="jpa_langref.html#jpa_langref_stmnttypes">2.1.
+ JPQL Statement Types
+ </a></span></dt><dd><dl><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_select">2.1.1.
+ JPQL Select Statement
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_bulk">2.1.2.
+ JPQL Update and Delete Statements
+ </a></span></dt></dl></dd><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_schematypes">2.2.
+ JPQL Abstract Schema Types and Query Domains
+ </a></span></dt><dd><dl><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_schemanaming">2.2.1.
+ JPQL Entity Naming
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_schemaexample">2.2.2.
+ JPQL Schema Example
+ </a></span></dt></dl></dd><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_fromclause">2.3.
+ JPQL FROM Clause and Navigational Declarations
+ </a></span></dt><dd><dl><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_from_identifiers">2.3.1.
+ JPQL FROM Identifiers
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_from_vars">2.3.2.
+ JPQL Identification Variables
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_range">2.3.3.
+ JPQL Range Declarations
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_path">2.3.4.
+ JPQL Path Expressions
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_Joins">2.3.5.
+ JPQL Joins
+ </a></span></dt><dd><dl><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_inner_joins">2.3.5.1.
+ JPQL Inner Joins (Relationship Joins)
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_outer_joins">2.3.5.2.
+ JPQL Outer Joins
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_fetch_joins">2.3.5.3.
+ JPQL Fetch Joins
+ </a></span></dt></dl></dd><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_collection_dec">2.3.6.
+ JPQL Collection Member Declarations
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_from_clause_and_sql">2.3.7.
+ JPQL FROM Clause and SQL
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_polymorph">2.3.8.
+ JPQL Polymorphism
+ </a></span></dt></dl></dd><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_where">2.4.
+ JPQL WHERE Clause
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_cond">2.5.
+ JPQL Conditional Expressions
+ </a></span></dt><dd><dl><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_lit">2.5.1.
+ JPQL Literals
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_idvar">2.5.2.
+ JPQL Identification Variables
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_path_exp">2.5.3.
+ JPQL Path Expressions
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_input_params">2.5.4.
+ JPQL Input Parameters
+ </a></span></dt><dd><dl><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_pos_params">2.5.4.1.
+ JPQL Positional Parameters
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_named_params">2.5.4.2.
+ JPQL Named Parameters
+ </a></span></dt></dl></dd><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_cond_comp">2.5.5.
+ JPQL Conditional Expression Composition
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_operators">2.5.6.
+ JPQL Operators and Operator Precedence
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_comparison_expressions">2.5.7.
+ JPQL Comparison Expressions
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_between">2.5.8.
+ JPQL Between Expressions
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_in_expressions">2.5.9.
+ JPQL In Expressions
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_like">2.5.10.
+ JPQL Like Expressions
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_null">2.5.11.
+ JPQL Null Comparison Expressions
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_empty_comp">2.5.12.
+ JPQL Empty Collection Comparison Expressions
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_collection_member">2.5.13.
+ JPQL Collection Member Expressions
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_exists">2.5.14.
+ JPQL Exists Expressions
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_all_any">2.5.15.
+ JPQL All or Any Expressions
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_subqueries">2.5.16.
+ JPQL Subqueries
+ </a></span></dt></dl></dd><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_scalar_expressions">2.6.
+ JPQL Scalar Expressions
+ </a></span></dt><dd><dl><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_math_expressions">2.6.1.
+ Arithmetic Expressions
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_functional_expressions">2.6.2.
+ String, Arithmetic, and Datetime Functional Expressions
+ </a></span></dt><dd><dl><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_string_fun">2.6.2.1.
+ JPQL String Functions
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_arithmetic">2.6.2.2.
+ JPQL Arithmetic Functions
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_datetime">2.6.2.3.
+ JPQL Datetime Functions
+ </a></span></dt></dl></dd><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_case_expressions">2.6.3.
+ Case Expressions
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_entity_type_expressions">2.6.4.
+ Entity Type Expressions
+ </a></span></dt></dl></dd><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_group">2.7.
+ JPQL GROUP BY, HAVING
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_select_clause">2.8.
+ JPQL SELECT Clause
+ </a></span></dt><dd><dl><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_resulttype">2.8.1.
+ JPQL Result Type of the SELECT Clause
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_constructor">2.8.2.
+ JPQL Constructor Expressions
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_null_select">2.8.3.
+ JPQL Null Values in the Query Result
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_embeddables">2.8.4.
+ JPQL Embeddables in the Query Result
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_aggregates">2.8.5.
+ JPQL Aggregate Functions
+ </a></span></dt><dd><dl><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_agg_examples">2.8.5.1.
+ JPQL Aggregate Examples
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_numeric_expressions_in_select">2.8.5.2.
+ JPQL Numeric Expressions in the SELECT Clause
+ </a></span></dt></dl></dd></dl></dd><dt><span
class="section"><a href="jpa_langref.html#jpa_langref_orderby">2.9.
+ JPQL ORDER BY Clause
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_bulk_ops">2.10.
+ JPQL Bulk Update and Delete
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_null_values">2.11.
+ JPQL Null Values
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_equality">2.12.
+ JPQL Equality and Comparison Semantics
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_bnf">2.13.
+ JPQL BNF
+ </a></span></dt></dl></div>
+
+ <p>
+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, <code class="literal">EJB QL</code>, 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.
+ </p>
+ <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3
class="title">Note</h3>
+ <p>
+Much of this section is paraphrased or taken directly from Chapter 4 of the
+JSR 317 Java Persistence API Specification.
+ </p>
+ </div>
+ <div class="section" id="jpa_langref_stmnttypes"><div
class="titlepage"><div><div><h3 class="title">2.1.
+ JPQL Statement Types
+ </h3></div></div></div><div class="toc"><dl class="toc"><dt><span
class="section"><a href="jpa_langref.html#jpa_langref_select">2.1.1.
+ JPQL Select Statement
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_bulk">2.1.2.
+ JPQL Update and Delete Statements
+ </a></span></dt></dl></div>
+
+ <p>
+A JPQL statement may be either a <code class="literal">SELECT</code>
statement, an
+<code class="literal">UPDATE</code> statement, or a <code
class="literal">DELETE</code> 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:
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist"
style="list-style-type: disc; "><li class="listitem">
+ <p>
+QL_statement ::= select_statement | update_statement | delete_statement
+ </p>
+ </li></ul></div>
+ <p>
+The complete BNF for JPQL is defined in <a class="xref"
href="jpa_langref.html#jpa_langref_bnf" title="2.13. JPQL
BNF">Section 2.13, “
+ JPQL BNF
+ ”</a>.
+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 <a class="xref"
href="jpa_langref.html#jpa_langref_input_params" title="2.5.4. JPQL Input
Parameters">Section 2.5.4, “
+ JPQL Input Parameters
+ ”</a>.
+ </p>
+ <div class="section" id="jpa_langref_select"><div
class="titlepage"><div><div><h4 class="title">2.1.1.
+ JPQL Select Statement
+ </h4></div></div></div>
+
+ <p>
+A select statement is a string which consists of the following clauses:
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist"
style="list-style-type: disc; "><li class="listitem">
+ <p>
+a <code class="literal">SELECT</code> clause, which determines the type of the
objects
+or values to be selected.
+ </p>
+ </li><li class="listitem">
+ <p>
+a <code class="literal">FROM</code> clause, which provides declarations that
designate the
+domain to which the expressions specified in the other clauses of the query
+apply.
+ </p>
+ </li><li class="listitem">
+ <p>
+an optional <code class="literal">WHERE</code> clause, which may be used to
restrict the
+results that are returned by the query.
+ </p>
+ </li><li class="listitem">
+ <p>
+an optional <code class="literal">GROUP BY</code> clause, which allows query
results to be
+aggregated in terms of groups.
+ </p>
+ </li><li class="listitem">
+ <p>
+an optional <code class="literal">HAVING</code> clause, which allows filtering
over
+aggregated groups.
+ </p>
+ </li><li class="listitem">
+ <p>
+an optional <code class="literal">ORDER BY</code> clause, which may be used to
order the
+results that are returned by the query.
+ </p>
+ </li></ul></div>
+ <p>
+In BNF syntax, a select statement is defined as:
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist"
style="list-style-type: disc; "><li class="listitem">
+ <p>
+select_statement ::= select_clause from_clause [where_clause] [groupby_clause]
+[having_clause] [orderby_clause]
+ </p>
+ </li></ul></div>
+ <p>
+A select statement must always have a <code class="literal">SELECT</code> and
a
+<code class="literal">FROM</code> clause. The square brackets [] indicate that
the other
+clauses are optional.
+ </p>
+ </div>
+ <div class="section" id="jpa_langref_bulk"><div
class="titlepage"><div><div><h4 class="title">2.1.2.
+ JPQL Update and Delete Statements
+ </h4></div></div></div>
+
+ <p>
+Update and delete statements provide bulk operations over sets of entities. In
+BNF syntax, these operations are defined as:
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist"
style="list-style-type: disc; "><li class="listitem">
+ <p>
+update_statement ::= update_clause [where_clause]
+ </p>
+ </li><li class="listitem">
+ <p>
+delete_statement ::= delete_clause [where_clause]
+ </p>
+ </li></ul></div>
+ <p>
+The update and delete clauses determine the type of the entities to be updated
+or deleted. The <code class="literal">WHERE</code> clause may be used to
restrict the
+scope of the update or delete operation. Update and delete statements are
+described further in <a class="xref"
href="jpa_langref.html#jpa_langref_bulk_ops" title="2.10. JPQL Bulk
Update and Delete">Section 2.10, “
+ JPQL Bulk Update and Delete
+ ”</a>.
+ </p>
+ </div>
+ </div>
+ <div class="section" id="jpa_langref_schematypes"><div
class="titlepage"><div><div><h3 class="title">2.2.
+ JPQL Abstract Schema Types and Query Domains
+ </h3></div></div></div><div class="toc"><dl class="toc"><dt><span
class="section"><a href="jpa_langref.html#jpa_langref_schemanaming">2.2.1.
+ JPQL Entity Naming
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_schemaexample">2.2.2.
+ JPQL Schema Example
+ </a></span></dt></dl></div>
+
+ <p>
+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.
+ </p>
+ <p>
+The abstract schema type of an entity or embeddable is
+derived from the entity class and the metadata information provided by Java
+language annotations or in the XML descriptor.
+ </p>
+ <p>
+Informally, the abstract schema type of an entity or embeddable can be
characterized as
+follows:
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist"
style="list-style-type: disc; "><li class="listitem">
+ <p>
+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.
+ </p>
+ </li><li class="listitem">
+ <p>
+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).
+ </p>
+ </li></ul></div>
+ <p>
+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.
+ </p>
+ <p>
+The domain of a query consists of the abstract schema
+types of all entities and embeddables that are defined in the same persistence
unit.
+ </p>
+ <p>
+The domain
+of a query may be restricted by the <code class="literal">navigability</code>
of the relationships of the
+entity and associated embeddable classes on which it is based. The
association-fields of an entity's
+or embeddable'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.
+ </p>
+ <div class="section" id="jpa_langref_schemanaming"><div
class="titlepage"><div><div><h4 class="title">2.2.1.
+ JPQL Entity Naming
+ </h4></div></div></div>
+
+ <p>
+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.
+ </p>
+ </div>
+ <div class="section" id="jpa_langref_schemaexample"><div
class="titlepage"><div><div><h4 class="title">2.2.2.
+ JPQL Schema Example
+ </h4></div></div></div>
+
+ <p>
+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 <code class="literal">Magazine</code>,
<code class="literal">
+Publisher</code>, <code class="literal">Author</code>, and <code
class="literal">Article</code>.
+ </p>
+ <p>
+Several Entities with Abstract Persistence Schemas Defined in the Same
+Persistence Unit. The entity <code class="literal">Publisher</code> has a
one-to-many
+relationships with <code class="literal">Magazine</code>. There is also a
one-to-many
+relationship between <code class="literal">Magazine</code> and <code
class="literal">Article</code>
+. The entity <code class="literal">Article</code> is related to <code
class="literal">Author</code>
+in a one-to-one relationship.
+ </p>
+ <p>
+Queries to select magazines can be defined by navigating over the
+association-fields and state-fields defined by <code
class="literal">Magazine</code> and
+<code class="literal">Author</code>. A query to
+find all magazines that have unpublished articles is as follows:
+ </p>
+<pre class="programlisting">
+SELECT DISTINCT mag FROM Magazine AS mag JOIN mag.articles AS art WHERE
art.published = FALSE
+</pre>
+ <p>
+This query navigates over the association-field <code
class="literal">authors</code> of the
+abstract schema type <code class="literal">Magazine</code> to find articles,
and uses the
+state-field <code class="literal">published</code> of <code
class="literal">Article</code> to select
+those magazines that have at least one article that is not published. Although
+predefined reserved identifiers, such as <code
class="literal">DISTINCT</code>, <code class="literal">
+FROM</code>, <code class="literal">AS</code>, <code
class="literal">JOIN</code>, <code class="literal">
+WHERE</code>, and <code class="literal">FALSE</code> appear in upper case in
this
+example, predefined reserved identifiers are case insensitive.
+ </p>
+ <p>
+ The <code class="literal">
+SELECT</code> clause of this example designates the return type of this
+query to be of type <code class="literal">Magazine</code>.
+ </p>
+ <p>
+Because the same persistence unit defines the
+abstract persistence schemas of the related entities, the developer can also
+specify a query over articles that utilizes the abstract
+schema type for products, and hence the state-fields and association-fields of
+both the abstract schema types <code class="literal">Magazine</code> and <code
class="literal">Author</code>.
+For example, if the
+abstract schema type <code class="literal">Author</code> has a state-field
named <code class="literal">firstName</code>,
+ 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".
+ </p>
+<pre class="programlisting">
+SELECT DISTINCT mag FROM Magazine mag JOIN mag.articles art JOIN art.author
auth WHERE auth.firstName = 'John'
+</pre>
+ <p>
+Because <code class="literal">Magazine</code> is related to <code
class="literal">Author</code> by means of the
+relationships between <code class="literal">Magazine</code> and <code
class="literal">Article</code>
+and between <code class="literal">Article</code> and <code
class="literal">Author</code>,
+navigation using the association-fields <code class="literal">authors</code>
and
+<code class="literal">product</code> is used to express
+the query. This query is specified by using the abstract schema name <code
class="literal">Magazine</code>,
+which designates the abstract schema type over which the query ranges. The
basis
+for the navigation is provided by the association-fields <code
class="literal">authors</code>
+and <code class="literal">product</code> of
+the abstract schema types <code class="literal">Magazine</code> and <code
class="literal">Article</code> respectively.
+ </p>
+ </div>
+ </div>
+ <div class="section" id="jpa_langref_fromclause"><div
class="titlepage"><div><div><h3 class="title">2.3.
+ JPQL FROM Clause and Navigational Declarations
+ </h3></div></div></div><div class="toc"><dl class="toc"><dt><span
class="section"><a href="jpa_langref.html#jpa_langref_from_identifiers">2.3.1.
+ JPQL FROM Identifiers
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_from_vars">2.3.2.
+ JPQL Identification Variables
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_range">2.3.3.
+ JPQL Range Declarations
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_path">2.3.4.
+ JPQL Path Expressions
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_Joins">2.3.5.
+ JPQL Joins
+ </a></span></dt><dd><dl><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_inner_joins">2.3.5.1.
+ JPQL Inner Joins (Relationship Joins)
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_outer_joins">2.3.5.2.
+ JPQL Outer Joins
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_fetch_joins">2.3.5.3.
+ JPQL Fetch Joins
+ </a></span></dt></dl></dd><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_collection_dec">2.3.6.
+ JPQL Collection Member Declarations
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_from_clause_and_sql">2.3.7.
+ JPQL FROM Clause and SQL
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_polymorph">2.3.8.
+ JPQL Polymorphism
+ </a></span></dt></dl></div>
+
+ <p>
+The <code class="literal">FROM</code> clause of a query defines the domain of
the query by
+declaring identification variables. An identification variable is an identifier
+declared in the <code class="literal">FROM</code> clause of a query. The
domain of the
+query may be constrained by path expressions (See section <a class="xref"
href="jpa_langref.html#jpa_langref_path" title="2.3.4. JPQL Path
Expressions">Section 2.3.4, “
+ JPQL Path Expressions
+ ”</a>.
+ </p>
+ <p>
+Identification variables designate
+instances of a particular entity abstract schema type. The <code
class="literal">FROM
+</code> clause can contain multiple identification variable declarations
+separated by a comma (,).
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist"
style="list-style-type: disc; "><li class="listitem">
+ <p>
+from_clause ::= FROM identification_variable_declaration {,
+{identification_variable_declaration | collection_member_declaration}}*
+ </p>
+ </li><li class="listitem">
+ <p>
+identification_variable_declaration ::= range_variable_declaration { join |
+fetch_join }*
+ </p>
+ </li><li class="listitem">
+ <p>
+range_variable_declaration ::= abstract_schema_name [AS]
identification_variable
+ </p>
+ </li><li class="listitem">
+ <p>
+join ::= join_spec join_association_path_expression [AS]
identification_variable
+ </p>
+ </li><li class="listitem">
+ <p>
+fetch_join ::= join_spec FETCH join_association_path_expression
+ </p>
+ </li><li class="listitem">
+ <p>
+join_association_path_expression ::= join_collection_valued_path_expression |
+join_single_valued_association_path_expression
+ </p>
+ </li><li class="listitem">
+ <p>
+join_collection_valued_path_expression::=
+identification_variable.{single_valued_embeddable_object_field.}*collection_valued_field
+ </p>
+ </li><li class="listitem">
+ <p>
+join_single_valued_path_expression::=
+identification_variable.{single_valued_embeddable_object_field.}*single_valued_object_field
</p>
+ </li><li class="listitem">
+ <p>
+join_spec ::= [ LEFT [OUTER] | INNER ] JOIN
+ </p>
+ </li><li class="listitem">
+ <p>
+collection_member_declaration ::= IN (collection_valued_path_expression) [AS]
+identification_variable
+ </p>
+ </li></ul></div>
+ <p>
+The following subsections discuss the constructs used in the <code
class="literal">FROM</code> clause.
+ </p>
+ <div class="section" id="jpa_langref_from_identifiers"><div
class="titlepage"><div><div><h4 class="title">2.3.1.
+ JPQL FROM Identifiers
+ </h4></div></div></div>
+
+ <p>
+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 <code class="methodname">
+Character.isJavaIdentifierStart</code> returns <code
class="literal">true</code>.
+This includes the underscore (_) character and the dollar sign ($) character.
An
+identifier part character is any character for which the method <code
class="methodname">
+Character.isJavaIdentifierPart</code> returns <code
class="literal">true</code>.
+The question mark (?) character is reserved for use by the Java Persistence
+query language. The following are reserved identifiers:
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist"
style="list-style-type: disc; "><li class="listitem">
+ <p>
+<code class="literal">ABS</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">ALL</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">AND</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">ANY</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">AS</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">ASC</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">AVG</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">BETWEEN</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">BOTH</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">BY</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">CASE</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">CLASS</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">COALESCE</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">CONCAT</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">COUNT</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">CURRENT_DATE</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">CURRENT_TIME</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">CURRENT_TIMESTAMP</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">DELETE</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">DESC</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">DISTINCT</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">ELSE</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">EMPTY</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">END</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">ENTRY</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">ESCAPE</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">EXISTS</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">FALSE</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">FETCH</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">FROM</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">GROUP</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">HAVING</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">IN</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">INDEX</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">INNER</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">IS</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">JOIN</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">KEY</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">LEADING</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">LEFT</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">LENGTH</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">LIKE</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">LOCATE</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">LOWER</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">MAX</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">MEMBER</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">MIN</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">MOD</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">NEW</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">NOT</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">NULL</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">NULLIF</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">OBJECT</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">OF</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">OR</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">ORDER</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">OUTER</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">SELECT</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">SET</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">SIZE</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">SOME</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">SQRT</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">SIBSTRING</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">SUM</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">THEN</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">TRAILING</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">TRIM</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">TRUE</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">TYPE</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">UPDATE</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">UPPER</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">VALUE</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">WHEN</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">WHERE</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">CHARACTER_LENGTH</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">CHAR_LENGTH</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">BIT_LENGTH</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">POSITION</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">UNKNOWN</code>
+ </p>
+ </li></ul></div>
+ <p>
+Reserved identifiers are case insensitive. Reserved identifiers must not be
+used as identification variables or result variables.
+ </p>
+ <div class="note" style="margin-left: 0.5in; margin-right:
0.5in;"><h3 class="title">Note</h3>
+ <p>
+It is recommended that other SQL reserved
+words also not be used as identification variables in queries because they may
be
+used as reserved identifiers in future releases of the specification.
+ </p>
+ </div>
+ <div class="note" style="margin-left: 0.5in; margin-right:
0.5in;"><h3 class="title">Note</h3>
+ <p>
+BIT_LENGTH, CHAR_LENGTH, CHARACTER_LENGTH, POSITION, and UNKNOWN are not
currently used: they are
+reserved for future use.
+ </p>
+ </div>
+ </div>
+ <div class="section" id="jpa_langref_from_vars"><div
class="titlepage"><div><div><h4 class="title">2.3.2.
+ JPQL Identification Variables
+ </h4></div></div></div>
+
+ <p>
+An identification variable is a valid identifier declared in the <code
class="literal">FROM
+</code> clause of a query.
+ </p>
+ <p>
+All identification variables must be declared in
+the <code class="literal">FROM</code> clause. Identification variables cannot
be declared
+in other clauses.
+ </p>
+ <p>
+An identification variable must not be a reserved identifier
+or have the same name as any entity in the same persistence unit.
+ </p>
+ <p>
+Identification variables are case insensitive.
+ </p>
+ <p>
+An identification variable evaluates to a value
+of the type of the expression used in declaring the variable. For example,
+consider the previous query: </p><pre class="programlisting">SELECT DISTINCT
mag FROM Magazine mag JOIN mag.articles art JOIN art.author auth WHERE
auth.firstName = 'John'
+</pre><p>
+In the <code class="literal">FROM</code> clause declaration <code
class="literal">
+mag.articles</code> <code class="literal">art</code>, the identification
variable
+<code class="literal">art</code> evaluates to any <code
class="literal">Article</code> value
+directly reachable from <code class="literal">Magazine</code>. The
association-field
+<code class="literal">articles</code> is a collection of instances of the
abstract schema
+type <code class="literal">Article</code> and the identification variable
<code class="literal">art
+</code> refers to an element of this collection. The type of <code
class="literal">auth
+</code> is the abstract schema type of <code class="literal">Author</code>.
+ </p>
+ <p>
+An identification variable can range over an entity,
+embeddable, or basic abstract schema type. An
+identification variable designates an instance of an entity abstract schema
type
+or an element of a collection of entity abstract schema type instances.
+ </p>
+ <p>
+Note that for identification variables referring to an instance of an
association or collection represented
+as a <code class="literal">java.util.Map</code>, the identification variable
is of the abstract schema type of the map
+<code class="literal">value</code>.
+ </p>
+ <p>
+An
+identification variable always designates a reference to a single value. It is
+declared in one of three ways: in a range variable declaration, in a join
+clause, or in a collection member declaration. The identification variable
+declarations are evaluated from left to right in the <code
class="literal">FROM</code>
+clause, and an identification variable declaration can use the result of a
+preceding identification variable declaration of the query string.
+ </p>
+ <p>
+All identification variables used in the <code class="literal">SELECT</code>,
+<code class="literal">WHERE</code>,
+<code class="literal">ORDER BY</code>,
+<code class="literal">GROUP BY</code>, or
+<code class="literal">HAVING</code>
+clause of a <code class="literal">SELECT</code> or
+<code class="literal">DELETE</code> statement must be declared in the <code
class="literal">FROM</code> clause.
+The identification
+variables used in the <code class="literal">WHERE</code> clause of
+an <code class="literal">UPDATE</code> statement must be declared in the <code
class="literal">UPDATE</code> clause.
+ </p>
+ <p>
+Identification variables are existentially quantified in these clauses. This
means that an identification
+variable represents a member of a collection or an instance of an
entity’s abstract schema type. An identification
+variable never designates a collection in its entirety.
+ </p>
+ <p>
+An identification variable is scoped to the query (or subquery) in which it is
defined and is also visible
+to any subqueries within that query scope that do not define an identification
variable of the same name.
+ </p>
+ </div>
+ <div class="section" id="jpa_langref_range"><div
class="titlepage"><div><div><h4 class="title">2.3.3.
+ JPQL Range Declarations
+ </h4></div></div></div>
+
+ <p>
+The syntax for declaring an identification variable as a range variable is
+similar to that of SQL; optionally, it uses the AS keyword. A range variable
designates an
+entity abstract schema type.
+ </p>
+ <div class="note" style="margin-left: 0.5in; margin-right:
0.5in;"><h3 class="title">Note</h3>
+ <p>
+A range variable must not designate an embeddable class abstract schema type.
+ </p>
+ </div>
+ <div class="itemizedlist"><ul class="itemizedlist"
style="list-style-type: disc; "><li class="listitem">
+ <p>
+range_variable_declaration ::= entity_name [AS]
+identification_variable
+ </p>
+ </li></ul></div>
+ <p>
+Range variable declarations allow the developer to designate a "root" for
+objects which may not be reachable by navigation.
+ </p>
+ <p>
+In order to select values by
+comparing more than one instance of an entity abstract schema type, more than
+one identification variable ranging over the abstract schema type is needed in
+the <code class="literal">FROM</code> clause.
+ </p>
+ <p>
+The following query returns magazines whose price is greater than the price of
+magazines published by "Adventure" publishers. This example illustrates the use
+of two different identification variables in the <code
class="literal">FROM</code> clause,
+both of the abstract schema type Magazine. The <code
class="literal">SELECT</code> clause
+of this query determines that it is the magazines with prices greater than
those
+of "Adventure" publisher's that are returned.
+ </p>
+<pre class="programlisting">
+SELECT DISTINCT mag1 FROM Magazine mag1, Magazine mag2
+WHERE mag1.price > mag2.price AND mag2.publisher.name = 'Adventure'
+</pre>
+ </div>
+ <div class="section" id="jpa_langref_path"><div
class="titlepage"><div><div><h4 class="title">2.3.4.
+ JPQL Path Expressions
+ </h4></div></div></div>
+
+ <p>
+An identification variable followed by the navigation operator (.) and a
+state-field or association-field is a path expression. The type of the path
+expression is the type computed as the result of navigation; that is, the type
+of the state-field or association-field to which the expression navigates.
+ </p>
+ <p>
+An identification variable qualified by the <code class="literal">KEY</code>,
+<code class="literal">VALUE</code>, or <code class="literal">ENTRY</code>
+operator is a path expression. The
+<code class="literal">KEY</code>, <code class="literal">VALUE</code>,
+and <code class="literal">ENTRY</code> operators may only be applied to
identification variables that correspond to
+map-valued associations or map-valued element collections. The type of the
path expression is the type
+computed as the result of the operation; that is, the abstract schema type of
the field that is the value of
+the <code class="literal">KEY</code>,
+<code class="literal">VALUE</code>, or <code class="literal">ENTRY</code>
+operator (the map key, map value, or map entry respectively).
+ </p>
+ <div class="note" style="margin-left: 0.5in; margin-right:
0.5in;"><h3 class="title">Note</h3>
+ <p>
+Note that use of <code class="literal">VALUE</code> is optional,
+as an identification variable referring to an association of type
+<code class="literal">java.util.Map</code> is of the
+abstract schema type of the map value.
+ </p>
+ </div>
+ <p>
+The syntax for qualified identification variables is as follows.
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist"
style="list-style-type: disc; "><li class="listitem">
+ <p>
+qualified_identification_variable :: =
+KEY(identification_variable) |
+VALUE(identification_variable) |
+ENTRY(identification_variable)
+ </p>
+ </li></ul></div>
+ <p>
+A path expression using the <code class="literal">KEY</code> or <code
class="literal">VALUE</code>
+operator may be further composed. A path expression
+using the <code class="literal">ENTRY</code> operator is terminal.
+It cannot be further composed and can only appear in the
+<code class="literal">SELECT</code> list of a query.
+ </p>
+ <p>
+In the following query, <code class="literal">photos</code> is a map from
photo label to filename.
+ </p>
+<pre class="programlisting">
+SELECT i.name, VALUE(p)
+FROM Item i JOIN i.photos p
+WHERE KEY(p) LIKE ‘egret’
+</pre>
+ <p>
+In the above query the identification variable <code class="literal">p</code>
designates
+an abstract schema type corresponding to the
+map value. The results of <code class="literal">VALUE(p)</code> and <code
class="literal">KEY(p)</code>
+are the map value and the map key associated with
+p, respectively. The following query is equivalent:
+ </p>
+<pre class="programlisting">
+SELECT i.name, p
+FROM Item i JOIN i.photos p
+WHERE KEY(p) LIKE ‘egret’
+</pre>
+ <p>
+Depending on navigability, a path expression that leads to a association-field
+or to a field whose type is an embeddable class
+may be further composed. Path expressions can be composed from other path
+expressions if the original path expression evaluates to a single-valued type
+(not a collection) corresponding to a association-field.
+ </p>
+ <p>
+In the following example, <code class="literal">contactInfo</code> denotes an
embeddable
+class consisting of an address and
+set of phones. <code class="literal">Phone</code> is an entity.
+ </p>
+<pre class="programlisting">
+SELECT p.vendor
+FROM Employee e JOIN e.contactInfo.phones p
+WHERE e.contactInfo.address.zipcode = '95054'
+</pre>
+ <p>
+Path expression
+navigability is composed using "inner join" semantics. That is, if the value of
+a non-terminal association-field in the path expression is null, the path is
+considered to have no value, and does not participate in the determination of
+the result.
+ </p>
+ <p>
+The following query is equivalent to the query above:
+ </p>
+<pre class="programlisting">
+SELECT p.vendor
+FROM Employee e JOIN e.contactInfo c JOIN c.phones p
+WHERE e.contactInfo.address.zipcode = '95054'
+</pre>
+ <p>
+The syntax for single-valued path expressions and collection valued
+path expressions is as follows:
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist"
style="list-style-type: disc; "><li class="listitem">
+ <p>
+single_valued_path_expression ::=
+qualified_identification_variable |
+state_field_path_expression |
+single_valued_object_path_expression
+ </p>
+ </li><li class="listitem">
+ <p>
+state_field_path_expression ::=
+general_identification_variable.{single_valued_object_field.}*state_field
+ </p>
+ </li><li class="listitem">
+ <p>
+single_valued_object_path_expression ::=
+general_identification_variable.{single_valued_object_field.}*single_valued_object_field
+ </p>
+ </li><li class="listitem">
+ <p>
+collection_valued_path_expression ::=
+general_identification_variable.{single_valued_object_field.}*collection_valued_field
+ </p>
+ </li></ul></div>
+ <p>
+A <code class="literal">single_valued_object_field</code> is designated by the
name of an
+association-field in a one-to-one or many-to-one relationship
+or a field of embeddable class type. The type of a
+<code class="literal">single_valued_object_field</code> is the abstract schema
type of the
+related entity or embeddable class.
+ </p>
+ <p>
+A <code class="literal">state_field</code> is designated by the name of an
entity or
+embeddable class state field that corresponds to
+a basic type.
+ </p>
+ <p>
+A collection_valued_field is designated by the name
+of an association-field in a one-to-many or a many-to-many relationship
+or by the name of an element collection field. The
+type of a <code class="literal">collection_valued_field</code> is
+a collection of values of the
+abstract schema type of the related entity
+or element type.
+ </p>
+ <p>
+An identification variable used in a
+<code class="literal">single_valued_object_path_expression</code> or in a
+<code class="literal">collection_valued_path_expression</code>
+may be an unqualified identification variable or an identification
+variable to which the KEY or VALUE function has been applied.
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist"
style="list-style-type: disc; "><li class="listitem">
+ <p>
+general_identification_variable ::=
+identification_variable |
+KEY(identification_variable) |
+VALUE(identification_variable)
+ </p>
+ </li></ul></div>
+ <p>
+It is syntactically illegal to compose a path expression from a
+path expression that evaluates to a collection. For example, if <code
class="literal">mag
+</code> designates <code class="literal">Magazine</code>, the path expression
<code class="literal">
+mag.articles.author</code> is illegal since navigation to authors results in
+a collection. This case should produce an error when the query string is
+verified. To handle such a navigation, an identification variable must be
+declared in the <code class="literal">FROM</code> clause to range over the
elements of the
+<code class="literal">articles</code> collection. Another path expression must
be used to
+navigate over each such element in the <code class="literal">WHERE</code>
clause of the
+query, as in the following query which returns all authors that have any
+articles in any magazines:
+ </p>
+<pre class="programlisting">
+SELECT DISTINCT art.author FROM Magazine AS mag, IN(mag.articles) art
+</pre>
+ <p>
+It is illegal to use a <code
class="literal">collection_valued_path_expression</code> other than
+in the <code class="literal">FROM</code> clause of a query
+except in an <code
class="literal">empty_collection_comparison_expression</code>,
+in a <code class="literal">collection_member_expression</code>, or
+as an argument to the <code class="literal">SIZE</code> operator.
+See <a class="xref" href="jpa_langref.html#jpa_langref_empty_comp"
title="2.5.12. JPQL Empty Collection Comparison
Expressions">Section 2.5.12, “
+ JPQL Empty Collection Comparison Expressions
+ ”</a>, <a class="xref"
href="jpa_langref.html#jpa_langref_collection_member" title="2.5.13. JPQL
Collection Member Expressions">Section 2.5.13, “
+ JPQL Collection Member Expressions
+ ”</a>,
+and <a class="xref" href="jpa_langref.html#jpa_langref_arithmetic"
title="2.6.2.2. JPQL Arithmetic Functions">Section 2.6.2.2, “
+ JPQL Arithmetic Functions
+ ”</a>.
+ </p>
+ </div>
+ <div class="section" id="jpa_langref_Joins"><div
class="titlepage"><div><div><h4 class="title">2.3.5.
+ JPQL Joins
+ </h4></div></div></div><div class="toc"><dl
class="toc"><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_inner_joins">2.3.5.1.
+ JPQL Inner Joins (Relationship Joins)
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_outer_joins">2.3.5.2.
+ JPQL Outer Joins
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_fetch_joins">2.3.5.3.
+ JPQL Fetch Joins
+ </a></span></dt></dl></div>
+
+ <p>
+An inner join may be implicitly specified by the use of a cartesian product in
+the <code class="literal">FROM</code> clause and a join condition in the <code
class="literal">WHERE
+</code> clause. In the absence of a join condition, this reduces to the
cartesian product.
+ </p>
+ <p>
+The main use case for this generalized style of join is when a join condition
does not involve
+a foreign key relationship that is mapped to an entity relationship, for
example:
+ </p>
+<pre class="programlisting">SELECT c FROM Customer c, Employee e WHERE
c.hatsize = e.shoesize</pre>
+ <p>
+In general, use of this style of inner join (also referred to as theta-join)
is less typical than explicitly
+defined joins over relationships.
+ </p>
+ <p>
+The syntax for explicit join operations is as follows:
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist"
style="list-style-type: disc; "><li class="listitem">
+ <p>
+join ::= join_spec join_association_path_expression [AS]
identification_variable
+ </p>
+ </li><li class="listitem">
+ <p>
+fetch_join ::= join_spec FETCH join_association_path_expression
+ </p>
+ </li><li class="listitem">
+ <p>
+join_association_path_expression ::= join_collection_valued_path_expression |
+join_single_valued_path_expression
+ </p>
+ </li><li class="listitem">
+ <p>
+join_collection_valued_path_expression::=
+identification_variable.{single_valued_embeddable_object_field.}*collection_valued_field
+ </p>
+ </li><li class="listitem">
+ <p>
+join_single_valued_path_expression::=
+identification_variable.{single_valued_embeddable_object_field.}*single_valued_object_field
+ </p>
+ </li><li class="listitem">
+ <p>
+join_spec ::= [ LEFT [OUTER] | INNER ] JOIN
+ </p>
+ </li></ul></div>
+ <p>
+The inner and outer join operation types described in
+<a class="xref" href="jpa_langref.html#jpa_langref_inner_joins"
title="2.3.5.1. JPQL Inner Joins (Relationship
Joins)">Section 2.3.5.1, “
+ JPQL Inner Joins (Relationship Joins)
+ ”</a> and <a class="xref"
href="jpa_langref.html#jpa_langref_outer_joins" title="2.3.5.2. JPQL
Outer Joins">Section 2.3.5.2, “
+ JPQL Outer Joins
+ ”</a> are supported.
+ </p>
+ <div class="section" id="jpa_langref_inner_joins"><div
class="titlepage"><div><div><h5 class="title">2.3.5.1.
+ JPQL Inner Joins (Relationship Joins)
+ </h5></div></div></div>
+
+ <p>
+The syntax for the inner join operation is </p><div class="itemizedlist"><ul
class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
+[ INNER ] JOIN join_association_path_expression [AS] identification_variable
+</li></ul></div><p> 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.
+ </p>
+<pre class="programlisting">
+SELECT pub FROM Publisher pub JOIN pub.magazines mag WHERE pub.revenue >
1000000
+</pre>
+ <p>
+The keyword <code class="literal">INNER</code> may optionally be used:
+ </p>
+<pre class="programlisting">
+SELECT pub FROM Publisher pub INNER JOIN pub.magazines mag WHERE pub.revenue
> 1000000
+</pre>
+ <p>
+This is equivalent to the following query using the earlier
+<code class="literal">IN</code> construct. It selects those publishers with
revenue of
+over 1 million for which at least one magazine exists:
+ </p>
+<pre class="programlisting">
+SELECT OBJECT(pub) FROM Publisher pub, IN(pub.magazines) mag WHERE pub.revenue
> 1000000
+</pre>
+ <p>
+The query below joins over Employee, ContactInfo and Phone. ContactInfo is an
+embeddable class that consists of an address and set of phones. Phone is an
entity.
+ </p>
+<pre class="programlisting">
+SELECT p.vendor
+FROM Employee e JOIN e.contactInfo c JOIN c.phones p
+WHERE c.address.zipcode = '95054'
+</pre>
+ </div>
+ <div class="section" id="jpa_langref_outer_joins"><div
class="titlepage"><div><div><h5 class="title">2.3.5.2.
+ JPQL Outer Joins
+ </h5></div></div></div>
+
+ <p>
+<code class="literal">LEFT JOIN</code> and <code class="literal">LEFT OUTER
JOIN</code> are
+synonymous. They enable the retrieval of a set of entities where matching
values
+in the join condition may be absent. The syntax for a left outer join is:
+</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type:
disc; "><li class="listitem">LEFT [OUTER] JOIN join_association_path_expression
[AS] identification_variable
+</li></ul></div><p>
+ </p>
+ <p>
+For example: </p><pre class="programlisting">SELECT pub FROM Publisher pub
LEFT JOIN pub.magazines mag WHERE pub.revenue > 1000000
+</pre><p> The keyword <code class="literal">OUTER</code> may optionally be
used:
+</p><pre class="programlisting">SELECT pub FROM Publisher pub LEFT OUTER JOIN
pub.magazines mags WHERE pub.revenue > 1000000
+</pre><p> An important use case for <code class="literal">LEFT JOIN</code> is
in
+enabling the prefetching of related data items as a side effect of a query.
This
+is accomplished by specifying the <code class="literal">LEFT JOIN</code> as a
<code class="literal">
+FETCH JOIN</code>.
+ </p>
+ </div>
+ <div class="section" id="jpa_langref_fetch_joins"><div
class="titlepage"><div><div><h5 class="title">2.3.5.3.
+ JPQL Fetch Joins
+ </h5></div></div></div>
+
+ <p>
+A <code class="literal">FETCH JOIN</code> enables the fetching of an
association as a side
+effect of the execution of a query. A <code class="literal">FETCH JOIN</code>
is specified
+over an entity and its related entities. The syntax for a fetch join is
+</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type:
disc; "><li class="listitem"><p>fetch_join ::= [ LEFT [OUTER] | INNER ] JOIN
+FETCH join_association_path_expression
+ </p>
+ </li></ul></div><p>
+ </p>
+ <p>
+The association referenced by the right side of the <code
class="literal">FETCH JOIN
+</code> clause must be an association that belongs to an entity that is
+returned as a result of the query. It is not permitted to specify an
+identification variable for the entities referenced by the right side of the
+<code class="literal">FETCH JOIN</code> clause, and hence references to the
implicitly
+fetched entities cannot appear elsewhere in the query.
+ </p>
+ <p>
+The following query
+returns a set of magazines. As a side effect, the associated articles for those
+magazines are also retrieved, even though they are not part of the explicit
+query result. The persistent fields or properties of the articles that are
+eagerly fetched are fully initialized. The initialization of the relationship
+properties of the <code class="literal">articles</code> that are retrieved is
determined
+by the metadata for the <code class="literal">Article</code> entity class.
+</p><pre class="programlisting">SELECT mag FROM Magazine mag LEFT JOIN FETCH
mag.articles WHERE mag.id = 1
+</pre><p>
+ </p>
+ <p>
+A fetch join has the same join semantics as the corresponding inner or outer
+join, except that the related objects specified on the right-hand side of the
+join operation are not returned in the query result or otherwise referenced in
+the query. Hence, for example, if magazine id 1 has five articles, the above
+query returns five references to the magazine 1 entity.
+ </p>
+ <p>
+The <code class="literal">FETCH JOIN</code> construct must not be used in the
FROM clause of a subquery.
+ </p>
+ </div>
+ </div>
+ <div class="section" id="jpa_langref_collection_dec"><div
class="titlepage"><div><div><h4 class="title">2.3.6.
+ JPQL Collection Member Declarations
+ </h4></div></div></div>
+
+ <p>
+An identification variable declared by a <code
class="literal">collection_member_declaration</code> ranges
+over values of a collection obtained by navigation using a path expression.
Such
+a path expression represents a navigation involving the association-fields of
an
+entity abstract schema type. Because a path expression can be based on another
+path expression, the navigation can use the association-fields of related
+entities.
+ </p>
+ <p>
+An identification variable of a collection member declaration is
+declared using a special operator, the reserved identifier <code
class="literal">IN</code>
+. The argument to the <code class="literal">IN</code> operator is a
collection-valued path
+expression. The path expression evaluates to a collection type specified as a
+result of navigation to a collection-valued association-field of an entity
+or embeddable class
+abstract schema type.
+ </p>
+ <p>
+The syntax for declaring a collection member
+identification variable is as follows:
+ </p>
+ <p>
+</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type:
disc; "><li class="listitem"><p>collection_member_declaration ::= IN
+(collection_valued_path_expression) [AS] identification_variable
+ </p>
+ </li></ul></div><p>
+ </p>
+ <p>
+For example, the query </p><pre class="programlisting">SELECT DISTINCT mag
FROM Magazine mag
+ JOIN mag.articles art
+ JOIN art.author auth
+ WHERE auth.lastName = 'Grisham'</pre><p> can equivalently be
+expressed as follows, using the <code class="literal">IN</code> operator:
</p><pre class="programlisting">SELECT DISTINCT mag FROM Magazine mag,
+ IN(mag.articles) art
+ WHERE art.author.lastName = 'Grisham'</pre><p> In this example,
+<code class="literal">articles</code> is the name of an association-field
whose value is a
+collection of instances of the abstract schema type <code
class="literal">Article</code>.
+The identification variable <code class="literal">art</code> designates a
member of this
+collection, a single <code class="literal">Article</code> abstract schema type
instance.
+In this example, <code class="literal">mag</code> is an identification
variable of the
+abstract schema type <code class="literal">Magazine</code>.
+ </p>
+ </div>
+ <div class="section" id="jpa_langref_from_clause_and_sql"><div
class="titlepage"><div><div><h4 class="title">2.3.7.
+ JPQL FROM Clause and SQL
+ </h4></div></div></div>
+
+ <p>
+The Java Persistence query language treats the FROM clause similarly to SQL in
that the declared identification
+variables affect the results of the query even if they are not used in the
WHERE clause. Application
+developers should use caution in defining identification variables because the
domain of the
+query can depend on whether there are any values of the declared type.
+ </p>
+ <p>
+For example, the <code class="literal">FROM</code> clause below defines a
query over
+all orders that have line items and existing
+products. If there are no <code class="literal">Product</code> instances in
the database,
+the domain of the query is empty and no
+order is selected.
+ </p>
+<pre class="programlisting">
+SELECT o
+FROM Order AS o JOIN o.lineItems l JOIN l.product p
+</pre>
+ </div>
+ <div class="section" id="jpa_langref_polymorph"><div
class="titlepage"><div><div><h4 class="title">2.3.8.
+ JPQL Polymorphism
+ </h4></div></div></div>
+
+ <p>
+Java Persistence queries are automatically polymorphic. The <code
class="literal">FROM
+</code> clause of a query designates not only instances of the specific
+entity classes to which explicitly refers but of subclasses as well. The
+instances returned by a query include instances of the subclasses that satisfy
+the query criteria.
+ </p>
+ <p>
+Non-polymorphic queries or queries whose polymorphism is restricted can be
specified using entity
+type expressions in the <code class="literal">WHERE</code> clause to restrict
the domain of the query.
+See <a class="xref"
href="jpa_langref.html#jpa_langref_entity_type_expressions" title="2.6.4.
Entity Type Expressions">Section 2.6.4, “
+ Entity Type Expressions
+ ”</a>.
+ </p>
+ </div>
+ </div>
+ <div class="section" id="jpa_langref_where"><div
class="titlepage"><div><div><h3 class="title">2.4.
+ JPQL WHERE Clause
+ </h3></div></div></div>
+
+ <p>
+The <code class="literal">WHERE</code> clause of a query consists of a
conditional
+expression used to select objects or values that satisfy the expression. The
+<code class="literal">WHERE</code> clause restricts the result of a select
statement or
+the scope of an update or delete operation.
+ </p>
+ <p>
+A <code class="literal">WHERE</code> clause is
+defined as follows: </p><div class="itemizedlist"><ul class="itemizedlist"
style="list-style-type: disc; "><li class="listitem"><p>where_clause ::= WHERE
+conditional_expression
+ </p>
+ </li></ul></div><p>
+ </p>
+ <p>
+The <code class="literal">GROUP BY</code> construct enables the aggregation of
values
+according to the properties of an entity class. The <code
class="literal">HAVING</code>
+construct enables conditions to be specified that further restrict the query
+result as restrictions upon the groups.
+ </p>
+ <p>
+The syntax of the <code class="literal">HAVING
+</code> clause is as follows: </p><div class="itemizedlist"><ul
class="itemizedlist" style="list-style-type: disc; "><li
class="listitem"><p>having_clause
+::= HAVING conditional_expression
+ </p>
+ </li></ul></div><p>
+ </p>
+ <p>
+The <code class="literal">GROUP BY</code> and <code
class="literal">HAVING</code> constructs are
+further discussed in <a class="xref" href="jpa_langref.html#jpa_langref_group"
title="2.7. JPQL GROUP BY, HAVING">Section 2.7, “
+ JPQL GROUP BY, HAVING
+ ”</a>.
+ </p>
+ </div>
+ <div class="section" id="jpa_langref_cond"><div
class="titlepage"><div><div><h3 class="title">2.5.
+ JPQL Conditional Expressions
+ </h3></div></div></div><div class="toc"><dl class="toc"><dt><span
class="section"><a href="jpa_langref.html#jpa_langref_lit">2.5.1.
+ JPQL Literals
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_idvar">2.5.2.
+ JPQL Identification Variables
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_path_exp">2.5.3.
+ JPQL Path Expressions
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_input_params">2.5.4.
+ JPQL Input Parameters
+ </a></span></dt><dd><dl><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_pos_params">2.5.4.1.
+ JPQL Positional Parameters
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_named_params">2.5.4.2.
+ JPQL Named Parameters
+ </a></span></dt></dl></dd><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_cond_comp">2.5.5.
+ JPQL Conditional Expression Composition
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_operators">2.5.6.
+ JPQL Operators and Operator Precedence
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_comparison_expressions">2.5.7.
+ JPQL Comparison Expressions
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_between">2.5.8.
+ JPQL Between Expressions
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_in_expressions">2.5.9.
+ JPQL In Expressions
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_like">2.5.10.
+ JPQL Like Expressions
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_null">2.5.11.
+ JPQL Null Comparison Expressions
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_empty_comp">2.5.12.
+ JPQL Empty Collection Comparison Expressions
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_collection_member">2.5.13.
+ JPQL Collection Member Expressions
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_exists">2.5.14.
+ JPQL Exists Expressions
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_all_any">2.5.15.
+ JPQL All or Any Expressions
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_subqueries">2.5.16.
+ JPQL Subqueries
+ </a></span></dt></dl></div>
+
+ <p>
+The following sections describe the language constructs that can be used in a
+conditional expression of the <code class="literal">WHERE</code> clause or
<code class="literal">
+HAVING</code> clause.
+ </p>
+ <p>
+State-fields that are mapped in serialized form or as
+LOBs may not be portably used in conditional expressions. </p><div
class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3
class="title">Note</h3><p> The
+implementation is not expected to perform such query operations involving such
+fields in memory rather than in the database.
+ </p>
+ </div><p>
+ </p>
+ <div class="section" id="jpa_langref_lit"><div
class="titlepage"><div><div><h4 class="title">2.5.1.
+ JPQL Literals
+ </h4></div></div></div>
+
+ <p>
+A string literal is enclosed in single quotes--for example: 'literal'. A string
+literal that includes a single quote is represented by two single quotes--for
+example: 'literal''s'. String literals in queries, like Java String literals,
+use unicode character encoding. The use of Java escape notation is not
supported
+in query string literals.
+ </p>
+ <p>
+Exact numeric literals support the use of Java integer
+literal syntax as well as SQL exact numeric literal syntax.
+ </p>
+ <p>
+Approximate literals
+support the use of Java floating point literal syntax as well as SQL
approximate
+numeric literal syntax.
+ </p>
+ <p>
+Enum literals support the use of Java enum literal
+syntax. The enum class name must be specified.
+ </p>
+ <p>
+Appropriate suffixes can be used
+to indicate the specific type of a numeric literal in accordance with the Java
+Language Specification. The boolean literals are <code
class="literal">TRUE</code> and
+<code class="literal">FALSE</code>. Although predefined reserved literals
appear in upper
+case, they are case insensitive.
+ </p>
+ <p>
+The JDBC escape syntax may be used for the specification of date, time, and
timestamp literals. For
+example:
+ </p>
+ <pre class="programlisting">
+SELECT o
+FROM Customer c JOIN c.orders o
+WHERE c.name = 'Smith'
+AND o.submissionDate < {d '2008-12-31'}
+ </pre>
+ <p>
+Date, time, and timestamp literals are passed as is to the JDBC driver
+in use.
+ </p>
+ <p>
+Entity type literals are specified by entity names—for example: <code
class="literal">Customer</code>.
+ </p>
+ <p>
+Although reserved literals appear in upper case, they are case insensitive.
+ </p>
+ </div>
+ <div class="section" id="jpa_langref_idvar"><div
class="titlepage"><div><div><h4 class="title">2.5.2.
+ JPQL Identification Variables
+ </h4></div></div></div>
+
+ <p>
+All identification variables used in the <code class="literal">WHERE</code> or
<code class="literal">
+HAVING</code> clause of a <code class="literal">SELECT</code> or <code
class="literal">DELETE
+</code> statement must be declared in the <code class="literal">FROM</code>
clause, as
+described in <a class="xref" href="jpa_langref.html#jpa_langref_from_vars"
title="2.3.2. JPQL Identification Variables">Section 2.3.2, “
+ JPQL Identification Variables
+ ”</a>. The identification
+variables used in the <code class="literal">WHERE</code> clause of an <code
class="literal">UPDATE
+</code> statement must be declared in the <code class="literal">UPDATE</code>
clause.
+ </p>
+ <p>
+Identification variables are existentially quantified in the <code
class="literal">WHERE
+</code> and <code class="literal">HAVING</code> clause. This means that an
+identification variable represents a member of a collection or an instance of
an
+entity's abstract schema type. An identification variable never designates a
+collection in its entirety.
+ </p>
+ </div>
+ <div class="section" id="jpa_langref_path_exp"><div
class="titlepage"><div><div><h4 class="title">2.5.3.
+ JPQL Path Expressions
+ </h4></div></div></div>
+
+ <p>
+It is illegal to use a <code
class="literal">collection_valued_path_expression</code> within a <code
class="literal">
+WHERE</code> or <code class="literal">HAVING</code> clause as part of a
conditional
+expression except in an <code
class="literal">empty_collection_comparison_expression</code>, in a
+<code class="literal">collection_member_expression</code>, or as an argument
to the <code class="literal">SIZE</code>
+operator.
+ </p>
+ </div>
+ <div class="section" id="jpa_langref_input_params"><div
class="titlepage"><div><div><h4 class="title">2.5.4.
+ JPQL Input Parameters
+ </h4></div></div></div><div class="toc"><dl
class="toc"><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_pos_params">2.5.4.1.
+ JPQL Positional Parameters
+ </a></span></dt><dt><span class="section"><a
href="jpa_langref.html#jpa_langref_named_params">2.5.4.2.
+ JPQL Named Parameters
+ </a></span></dt></dl></div>
+
+ <p>
+Either positional or named parameters may be used. Positional and named
+parameters may not be mixed in a single query.
+ </p>
+ <p>
+Input parameters can only be used
+in the <code class="literal">WHERE</code> clause or <code
class="literal">HAVING</code> clause of a
+query.
+ </p>
+ <p>
+Note that if an input parameter value is null, comparison operations or
+arithmetic operations involving the input parameter will return an unknown
+value. See <a class="xref" href="jpa_langref.html#jpa_langref_null_values"
title="2.11. JPQL Null Values">Section 2.11, “
+ JPQL Null Values
+ ”</a>.
+ </p>
+ <p>
+All input parameters must be single-valued, except in IN expressions (see
+<a class="xref" href="jpa_langref.html#jpa_langref_in_expressions"
title="2.5.9. JPQL In Expressions">Section 2.5.9, “
+ JPQL In Expressions
+ ”</a> ), which support the use of collection-valued
+input parameters.
+ </p>
+ <div class="section" id="jpa_langref_pos_params"><div
class="titlepage"><div><div><h5 class="title">2.5.4.1.
+ JPQL Positional Parameters
+ </h5></div></div></div>
+
+ <p>
+The following rules apply to positional parameters. </p><div
class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;
"><li class="listitem">
+<p> Input parameters are designated by the question mark (?) prefix followed
+by an integer. For example: ?1.
+ </p>
+ </li><li class="listitem">
+ <p>
+Input parameters are numbered starting from 1.
+ </p>
+ </li><li class="listitem">
+ <p>
+The same parameter can
+be used more than once in the query string.
+ </p>
+ </li><li class="listitem">
+ <p>
+The ordering of the use of
+parameters within the query string need not conform to the order of the
+positional parameters.
+ </p>
+ </li></ul></div><p>
+ </p>
+ </div>
[... 2222 lines stripped ...]
