From 0e3cfbde5512cb152aac7514dca9eabe5442118c Mon Sep 17 00:00:00 2001 From: Steve Ebersole Date: Wed, 1 Feb 2012 11:09:57 -0600 Subject: [PATCH] HHH-6082 - Incorporate EntityManager documentation into main dev guide --- .../main/docbook/devguide/en-US/HQL_JPAQL.xml | 7 -- .../en-US/Hibernate_Development_Guide.xml | 2 +- .../devguide/en-US/chapters/hql/HQL_JPQL.xml | 117 ++++++++++++++++++ .../hql/extras/delete_statement_bnf.txt | 3 + .../hql/extras/update_statement_bnf.txt | 9 ++ 5 files changed, 130 insertions(+), 8 deletions(-) delete mode 100644 documentation/src/main/docbook/devguide/en-US/HQL_JPAQL.xml create mode 100644 documentation/src/main/docbook/devguide/en-US/chapters/hql/HQL_JPQL.xml create mode 100644 documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/delete_statement_bnf.txt create mode 100644 documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/update_statement_bnf.txt diff --git a/documentation/src/main/docbook/devguide/en-US/HQL_JPAQL.xml b/documentation/src/main/docbook/devguide/en-US/HQL_JPAQL.xml deleted file mode 100644 index cee4c577bd..0000000000 --- a/documentation/src/main/docbook/devguide/en-US/HQL_JPAQL.xml +++ /dev/null @@ -1,7 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - HQL and JPAQL diff --git a/documentation/src/main/docbook/devguide/en-US/Hibernate_Development_Guide.xml b/documentation/src/main/docbook/devguide/en-US/Hibernate_Development_Guide.xml index 3c4c38d363..1f87a6fb39 100644 --- a/documentation/src/main/docbook/devguide/en-US/Hibernate_Development_Guide.xml +++ b/documentation/src/main/docbook/devguide/en-US/Hibernate_Development_Guide.xml @@ -16,7 +16,7 @@ - + diff --git a/documentation/src/main/docbook/devguide/en-US/chapters/hql/HQL_JPQL.xml b/documentation/src/main/docbook/devguide/en-US/chapters/hql/HQL_JPQL.xml new file mode 100644 index 0000000000..d4acdb03b8 --- /dev/null +++ b/documentation/src/main/docbook/devguide/en-US/chapters/hql/HQL_JPQL.xml @@ -0,0 +1,117 @@ + + +%BOOK_ENTITIES; +]> + + HQL and JPQL + + + 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. + + + + Both HQL and JPQL are non-type-safe ways to perform query operations. Criteria queries offer a + type-safe approach to querying. See for more information. + + +
+ Case Sensitivity + + + With the exception of names of Java classes and properties, queries are case-insensitive. + So SeLeCT is the same as sELEct is the same as + SELECT, but + org.hibernate.eg.FOO and org.hibernate.eg.Foo are different, as are + foo.barSet and foo.BARSET. + + + + + This documentation uses lowercase keywords as its convention. + + +
+ +
+ Statement types + + Both HQL and JPQL allow SELECT, UPDATE and DELETE + statements to be performed. HQL additionally allows INSERT statements, in a form + similar to SQL's INSERT-SELECT. + + + + + Care should be taken as to when a UPDATE or DELETE statement is + executed. + +
+ Section 4.10 of the JPA 2.0 Specification + + 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. + +
+ + +
+ Select statements + + The BNF for SELECT statements in HQL is: + + select_statement :: = [select_clause] from_clause [where_clause] [groupby_clause] [having_clause] [orderby_clause] + + The simplest possible HQL SELECT statement is of the form: + + from com.acme.Cat + + Even though HQL does not require the presence of a select_clause, it is generally + good practice to include one. For simple queries like above, the intent is clear and so the + select_clause is really not needed. But on more complex queries it is usually better + to explicitly specify intent. + + + The BNF for SELECT statements in JPQL is + + select_statement :: = select_clause from_clause [where_clause] [groupby_clause] [having_clause] [orderby_clause] + + The important distinction is that JPQL requires a select_clause, whereas HQL does not. + Hibernate does not actually enforce that a select_clause be present even when + parsing JPQL queries, however applications interested in JPA portability should take heed of this. + +
+ +
+ Update statements + + The BNF for UPDATE statements is the same in HQL and JPQL: + + +
+ +
+ Delete statements + + The BNF for DELETE statements is the same in HQL and JPQL: + + +
+ +
+ Insert statements +
+
+ +
+ The <literal>FROM</literal> clause +
+ +
+ The <literal>SELECT</literal> clause +
+ diff --git a/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/delete_statement_bnf.txt b/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/delete_statement_bnf.txt new file mode 100644 index 0000000000..087d1ed4da --- /dev/null +++ b/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/delete_statement_bnf.txt @@ -0,0 +1,3 @@ +delete_statement ::= delete_clause [where_clause] + +delete_clause ::= DELETE FROM entity_name [[AS] identification_variable] diff --git a/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/update_statement_bnf.txt b/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/update_statement_bnf.txt new file mode 100644 index 0000000000..69fd26bd64 --- /dev/null +++ b/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/update_statement_bnf.txt @@ -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