HHH-6082 - Incorporate EntityManager documentation into main dev guide
This commit is contained in:
Steve Ebersole
parent
3cf41ee3dc
commit
0e3cfbde55
|
|
@ -1,7 +0,0 @@
|
|||
<?xml version='1.0' encoding='utf-8' ?>
|
||||
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
|
||||
<!ENTITY % BOOK_ENTITIES SYSTEM "Hibernate_Development_Guide.ent">
|
||||
%BOOK_ENTITIES;
|
||||
]>
|
||||
<chapter id="chap-hql">
|
||||
<title>HQL and JPAQL</title> <para> </para> </chapter>
|
||||
|
|
@ -16,7 +16,7 @@
|
|||
<xi:include href="Data_Categorizations.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
<xi:include href="Mapping_Entities.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
<xi:include href="Mapping_Association.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
<xi:include href="HQL_JPAQL.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
<xi:include href="chapters/hql/HQL_JPQL.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
<xi:include href="Criteria.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
<xi:include href="Native_SQL.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
<xi:include href="JMX.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
|
|
|
|||
|
|
@ -0,0 +1,117 @@
|
|||
<?xml version='1.0' encoding='utf-8' ?>
|
||||
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
|
||||
<!ENTITY % BOOK_ENTITIES SYSTEM "../../Hibernate_Development_Guide.ent">
|
||||
%BOOK_ENTITIES;
|
||||
]>
|
||||
<chapter id="query-ql">
|
||||
<title>HQL and JPQL</title>
|
||||
|
||||
<para>
|
||||
The Hibernate Query Language (HQL) and Java Persistence Query Language (JPQL) are both object model
|
||||
focused query languages similar in nature to SQL. JPQL is a heavily-inspired-by subset of HQL. A JPQL
|
||||
query is always a valid HQL query, the reverse is not true however.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Both HQL and JPQL are non-type-safe ways to perform query operations. Criteria queries offer a
|
||||
type-safe approach to querying. See <xref linkend="query-criteria" /> for more information.
|
||||
</para>
|
||||
|
||||
<section>
|
||||
<title>Case Sensitivity</title>
|
||||
|
||||
<para>
|
||||
With the exception of names of Java classes and properties, queries are case-insensitive.
|
||||
So <literal>SeLeCT</literal> is the same as <literal>sELEct</literal> is the same as
|
||||
<literal>SELECT</literal>, but
|
||||
<literal>org.hibernate.eg.FOO</literal> and <literal>org.hibernate.eg.Foo</literal> are different, as are
|
||||
<literal>foo.barSet</literal> and <literal>foo.BARSET</literal>.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
This documentation uses lowercase keywords as its convention.
|
||||
</para>
|
||||
</note>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<title>Statement types</title>
|
||||
<para>
|
||||
Both HQL and JPQL allow <literal>SELECT</literal>, <literal>UPDATE</literal> and <literal>DELETE</literal>
|
||||
statements to be performed. HQL additionally allows <literal>INSERT</literal> statements, in a form
|
||||
similar to SQL's <literal>INSERT-SELECT</literal>.
|
||||
</para>
|
||||
|
||||
<important>
|
||||
<para>
|
||||
Care should be taken as to when a <literal>UPDATE</literal> or <literal>DELETE</literal> statement is
|
||||
executed.
|
||||
</para>
|
||||
<blockquote>
|
||||
<attribution><citetitle pubwork="section">Section 4.10 of the JPA 2.0 Specification</citetitle></attribution>
|
||||
<para>
|
||||
Caution should be used when executing bulk update or delete operations because they may result in
|
||||
inconsistencies between the database and the entities in the active persistence context. In general, bulk
|
||||
update and delete operations should only be performed within a transaction in a new persistence con-
|
||||
text or before fetching or accessing entities whose state might be affected by such operations.
|
||||
</para>
|
||||
</blockquote>
|
||||
</important>
|
||||
|
||||
<section>
|
||||
<title>Select statements</title>
|
||||
<para>
|
||||
The BNF for <literal>SELECT</literal> statements in HQL is:
|
||||
</para>
|
||||
<programlisting>select_statement :: = [select_clause] from_clause [where_clause] [groupby_clause] [having_clause] [orderby_clause]</programlisting>
|
||||
<para>
|
||||
The simplest possible HQL <literal>SELECT</literal> statement is of the form:
|
||||
</para>
|
||||
<programlisting>from com.acme.Cat</programlisting>
|
||||
<para>
|
||||
Even though HQL does not require the presence of a <literal>select_clause</literal>, it is generally
|
||||
good practice to include one. For simple queries like above, the intent is clear and so the
|
||||
<literal>select_clause</literal> is really not needed. But on more complex queries it is usually better
|
||||
to explicitly specify intent.
|
||||
</para>
|
||||
<para>
|
||||
The BNF for <literal>SELECT</literal> statements in JPQL is
|
||||
</para>
|
||||
<programlisting>select_statement :: = select_clause from_clause [where_clause] [groupby_clause] [having_clause] [orderby_clause]</programlisting>
|
||||
<para>
|
||||
The important distinction is that JPQL requires a <literal>select_clause</literal>, whereas HQL does not.
|
||||
Hibernate does not actually enforce that a <literal>select_clause</literal> be present even when
|
||||
parsing JPQL queries, however applications interested in JPA portability should take heed of this.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<title>Update statements</title>
|
||||
<para>
|
||||
The BNF for <literal>UPDATE</literal> statements is the same in HQL and JPQL:
|
||||
</para>
|
||||
<programlisting role="JAVA"><xi:include href="extras/update_statement_bnf.txt" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text"/></programlisting>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<title>Delete statements</title>
|
||||
<para>
|
||||
The BNF for <literal>DELETE</literal> statements is the same in HQL and JPQL:
|
||||
</para>
|
||||
<programlisting role="JAVA"><xi:include href="extras/delete_statement_bnf.txt" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text"/></programlisting>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<title>Insert statements</title>
|
||||
</section>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<title>The <literal>FROM</literal> clause</title>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<title>The <literal>SELECT</literal> clause</title>
|
||||
</section>
|
||||
</chapter>
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
delete_statement ::= delete_clause [where_clause]
|
||||
|
||||
delete_clause ::= DELETE FROM entity_name [[AS] identification_variable]
|
||||
|
|
@ -0,0 +1,9 @@
|
|||
update_statement ::= update_clause [where_clause]
|
||||
|
||||
update_clause ::= UPDATE entity_name [[AS] identification_variable] SET update_item {, update_item}*
|
||||
|
||||
update_item ::= [identification_variable.]{state_field | single_valued_object_field} = new_value
|
||||
|
||||
new_value ::= scalar_expression |
|
||||
simple_entity_expression |
|
||||
NULL
|
||||
Loading…
Reference in New Issue