HHH-6082 - Incorporate EntityManager documentation into main dev guide

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/agg_func_example.txt

@@ -0,0 +1,10 @@
+select count(*), sum( o.total ), avg( o.total ), min( o.total ), max( o.total )
+from Order o
+
+select count( distinct c.name )
+from Customer c
+
+select c.id, c.name, sum( o.total )
+from Customer c
+    left join c.orders o
+group by c.id, c.name

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/arithmetic_example.txt

@@ -0,0 +1,9 @@
+select year( current_date() ) - year( c.dateOfBirth )
+from Customer c
+
+select c
+from Customer c
+where year( current_date() ) - year( c.dateOfBirth ) < 30
+
+select o.customer, o.total + ( o.total * :salesTax )
+from Order o

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/between_exp_example.txt

@@ -0,0 +1,19 @@
+select p
+from Customer c
+    join c.paymentHistory p
+where c.id = 123
+  and index(p) between 0 and 9
+
+select c
+from Customer c
+where c.president.dateOfBirth
+        between {d '1945-01-01'}
+            and {d '1965-01-01'}
+
+select o
+from Order o
+where o.total between 500 and 5000
+
+select p
+from Person p
+where p.name between 'A' and 'E' 

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/collection_expression_example.txt

@@ -0,0 +1,36 @@
+select cal
+from Calendar cal
+where maxelement(cal.holidays) > current_date()
+
+select o
+from Order o
+where maxindex(o.items) > 100
+
+select o
+from Order o
+where minelement(o.items) > 10000
+
+select m
+from Cat as m, Cat as kit
+where kit in elements(m.kittens)
+
+// the above query can be re-written in jpql standard way:
+select m
+from Cat as m, Cat as kit
+where kit member of m.kittens
+
+select p
+from NameList l, Person p
+where p.name = some elements(l.names)
+
+select cat
+from Cat cat
+where exists elements(cat.kittens)
+
+select p
+from Player p
+where 3 > all elements(p.scores)
+
+select show
+from Show show
+where 'fizard' in indices(show.acts)

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/collection_reference_example.txt

@@ -0,0 +1,16 @@
+select c
+from Customer c
+    join c.orders o
+    join o.lineItems l
+    join l.product p
+where o.status = 'pending'
+  and p.status = 'backorder'
+
+// alternate syntax
+select c
+from Customer c,
+    in(c.orders) o,
+    in(o.lineItems) l
+    join l.product p
+where o.status = 'pending'
+  and p.status = 'backorder'

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/comparison_exp_example.txt

@@ -0,0 +1,34 @@
+// numeric comparison
+select c
+from Customer c
+where c.chiefExecutive.age < 30
+
+// string comparison
+select c
+from Customer c
+where c.name = 'Acme'
+
+// datetime comparison
+select c
+from Customer c
+where c.inceptionDate < {d '2000-01-01'}
+
+// enum comparison
+select c
+from Customer c
+where c.chiefExecutive.gender = com.acme.Gender.MALE
+
+// boolean comparison
+select c
+from Customer c
+where c.sendEmail = true
+
+// entity type comparison
+select p
+from Payment p
+where type(p) = WireTransferPayment
+
+// entity value comparison
+select c
+from Customer c
+where c.chiefExecutive = c.chiefTechnologist

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/comparison_using_all_example.txt

@@ -0,0 +1,9 @@
+// select all players that scored at least 3 points
+// in every game.
+select p
+from Player p
+where 3 > all (
+    select spg.points
+    from StatsPerGame spg
+    where spg.player = p
+)

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/concat_op_example.txt

@@ -0,0 +1,3 @@
+select 'Mr. ' || c.name.first || ' ' || c.name.last
+from Customer c
+where c.gender = Gender.MALE

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/ctor_dynamic_instantiation_example.txt

@@ -0,0 +1,4 @@
+select new Family( mother, mate, offspr )
+from DomesticCat as mother
+    join mother.mate as mate
+    left join mother.kittens as offspr

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/empty_collection_example.txt

@@ -0,0 +1,7 @@
+select o
+from Order o
+where o.lineItems is empty
+
+select c
+from Customer c
+where c.pastDueBills is not empty

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/entity_type_exp_example.txt

@@ -0,0 +1,8 @@
+select p
+from Payment p
+where type(p) = CreditCardPayment
+
+select p
+from Payment p
+where type(p) = :aType
+

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/explicit_inner_join_example.txt

@@ -0,0 +1,10 @@
+select c
+from Customer c
+    join c.chiefExecutive ceo
+where ceo.age < 25
+
+// same query but specifying join type as 'inner' explicitly
+select c
+from Customer c
+    inner join c.chiefExecutive ceo
+where ceo.age < 25

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/explicit_outer_join_example.txt

@@ -0,0 +1,15 @@
+// get customers who have orders worth more than $5000
+// or who are in "preferred" status
+select distinct c
+from Customer c
+    left join c.orders o
+where o.value > 5000.00
+  or c.status = 'preferred'
+
+// functionally the same query but using the
+// 'left outer' phrase
+select distinct c
+from Customer c
+    left outer join c.orders o
+where o.value > 5000.00
+  or c.status = 'preferred'

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/fetch_join_example.txt

@@ -0,0 +1,3 @@
+select c
+from Customer c
+    left join fetch c.orders o

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/implicit_join_example.txt

@@ -0,0 +1,9 @@
+select c
+from Customer c
+where c.chiefExecutive.age < 25
+
+// same as
+select c
+from Customer c
+    inner join c.chiefExecutive ceo
+where ceo.age < 25

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/index_operator_example.txt

@@ -0,0 +1,22 @@
+select o
+from Order o
+where o.items[0].id = 1234
+
+select p
+from Person p, Calendar c
+where c.holidays['national day'] = p.birthDay
+  and p.nationality.calendar = c
+
+select i
+from Item i, Order o
+where o.items[ o.deliveredItemIndices[0] ] = i
+  and o.id = 11
+
+select i
+from Item i, Order o
+where o.items[ maxindex(o.items) ] = i
+  and o.id = 11
+
+select i
+from Item i, Order o
+where o.items[ size(o.items) - 1 ] = i

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/insert_statement_bnf.txt

@@ -0,0 +1,5 @@
+insert_statement ::= insert_clause select_statement
+
+insert_clause ::= INSERT INTO entity_name (attribute_list)
+
+attribute_list ::= state_field[, state_field ]*

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/insert_statement_named_id.java

@@ -0,0 +1,2 @@
+String hqlInsert = "insert into DelinquentAccount (id, name) select c.id, c.name from Customer c where ...";
+int createdEntities = s.createQuery( hqlInsert ).executeUpdate();

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/jpql_positional_parameter_example.txt

@@ -0,0 +1,16 @@
+String queryString =
+        "select c " +
+        "from Customer c " +
+        "where c.name = ?1 " +
+        "   or c.nickName = ?1";
+
+// HQL - as you can see, handled just like named parameters
+//      in terms of API
+List customers = session.createQuery( queryString )
+        .setParameter( "1", theNameOfInterest )
+        .list();
+
+// JPQL
+List<Customer> customers = entityManager.createQuery( queryString, Customer.class )
+        .setParameter( 1, theNameOfInterest )
+        .getResultList();

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/like_exp_bnf.txt

@@ -0,0 +1,4 @@
+like_expression ::=
+        string_expression
+        [NOT] LIKE pattern_value
+        [ESCAPE escape_character]

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/like_exp_example.txt

@@ -0,0 +1,13 @@
+select p
+from Person p
+where p.name like '%Schmidt'
+
+select p
+from Person p
+where p.name not like 'Jingleheimmer%'
+
+// find any with name starting with "sp_"
+select sp
+from StoredProcedureMetadata sp
+where sp.name like 'sp|_%' escape '|'
+

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/list_dynamic_instantiation_example.txt

@@ -0,0 +1,4 @@
+select new list(mother, offspr, mate.name)
+from DomesticCat as mother
+    inner join mother.mate as mate
+    left outer join mother.kittens as offspr

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/locate_bnf.txt

@@ -0,0 +1 @@
+locate( string_expression, string_expression[, numeric_expression] )

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/map_dynamic_instantiation_example.txt

@@ -0,0 +1,7 @@
+select new map( mother as mother, offspr as offspr, mate as mate )
+from DomesticCat as mother
+    inner join mother.mate as mate
+    left outer join mother.kittens as offspr
+
+select new map( max(c.bodyWeight) as max, min(c.bodyWeight) as min, count(*) as n )
+from Cat c

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/member_of_collection_example.txt

@@ -0,0 +1,8 @@
+select p
+from Person p
+where 'John' member of p.nickNames
+
+select p
+from Person p
+where p.name.first = 'Joseph'
+  and 'Joey' not member of p.nickNames

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/multiple_root_entity_ref_example.txt

@@ -0,0 +1,5 @@
+// build a product between customers and active mailing campaigns so we can spam!
+select distinct cust, camp
+from Customer cust, Campaign camp
+where camp.type = 'mail'
+  and current_timestamp() between camp.activeRange.start and camp.activeRange.end

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/multiple_root_entity_ref_example2.txt

@@ -0,0 +1,5 @@
+// retrieve all customers with headquarters in the same state as Acme's headquarters
+select distinct c1
+from Customer c1, Customer c2
+where c1.address.state = c2.address.state
+  and c2.name = 'Acme'

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/named_parameter_example.txt

@@ -0,0 +1,15 @@
+String queryString =
+        "select c " +
+        "from Customer c " +
+        "where c.name = :name " +
+        "   or c.nickName = :name";
+
+// HQL
+List customers = session.createQuery( queryString )
+        .setParameter( "name", theNameOfInterest )
+        .list();
+
+// JPQL
+List<Customer> customers = entityManager.createQuery( queryString, Customer.class )
+        .setParameter( "name", theNameOfInterest )
+        .getResultList();

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/null_check_example.txt

@@ -0,0 +1,9 @@
+// select everyone with an associated address
+select p
+from Person p
+where p.address is not null
+
+// select everyone without an associated address
+select p
+from Person p
+where p.address is null

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/nullif_example.txt

@@ -0,0 +1,8 @@
+// return customers who have changed their last name
+select nullif( c.previousName.last, c.name.last )
+from Customer c
+
+// equivalent CASE expression
+select case when c.previousName.last = c.name.last then null
+            else c.previousName.last end
+from Customer c

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/numeric_literals_example.txt

@@ -0,0 +1,29 @@
+// simple integer literal
+select o
+from Order o
+where o.referenceNumber = 123
+
+// simple integer literal, typed as a long
+select o
+from Order o
+where o.referenceNumber = 123L
+
+// decimal notation
+select o
+from Order o
+where o.total > 5000.00
+
+// decimal notation, typed as a float
+select o
+from Order o
+where o.total > 5000.00F
+
+// scientific notation
+select o
+from Order o
+where o.total > 5e+3
+
+// scientific notation, typed as a float
+select o
+from Order o
+where o.total > 5e+3F

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/qualified_path_expressions_example.txt

@@ -0,0 +1,33 @@
+// Product.images is a Map<String,String> : key = a name, value = file path
+
+// select all the image file paths (the map value) for Product#123
+select i
+from Product p
+    join p.images i
+where p.id = 123
+
+// same as above
+select value(i)
+from Product p
+    join p.images i
+where p.id = 123
+
+// select all the image names (the map key) for Product#123
+select key(i)
+from Product p
+    join p.images i
+where p.id = 123
+
+// select all the image names and file paths (the 'Map.Entry') for Product#123
+select entry(i)
+from Product p
+    join p.images i
+where p.id = 123
+
+// total the value of the initial line items for all orders for a customer
+select sum( li.amount )
+from Customer c
+        join c.orders o
+        join o.lineItems li
+where c.id = 123
+  and index(li) = 1

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/reused_implicit_join_example.txt

@@ -0,0 +1,19 @@
+select c
+from Customer c
+where c.chiefExecutive.age < 25
+   and c.chiefExecutive.address.state = 'TX'
+
+// same as
+select c
+from Customer c
+    inner join c.chiefExecutive ceo
+where ceo.age < 25
+  and ceo.address.state = 'TX'
+
+// same as
+select c
+from Customer c
+    inner join c.chiefExecutive ceo
+    inner join ceo.address a
+where ceo.age < 25
+  and a.state = 'TX'

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/root_entity_ref_bnf.txt

@@ -0,0 +1 @@
+root_entity_reference ::= entity_name [AS] identification_variable

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/searched_case_bnf.txt

@@ -0,0 +1 @@
+CASE [ WHEN {test_conditional} THEN {match_result} ]* ELSE {miss_result} END

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/searched_case_exp_example.txt

@@ -0,0 +1,9 @@
+select case when c.name.first is not null then c.name.first
+            when c.nickName is not null then c.nickName
+            else '<no first name>' end
+from Customer c
+
+// Again, the abbreviated form coalesce can handle this a
+// little more succinctly
+select coalesce( c.name.first, c.nickName, '<no first name>' )
+from Customer c

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/select_statement_bnf.txt

@@ -0,0 +1,7 @@
+select_statement :: =
+        [select_clause]
+        from_clause
+        [where_clause]
+        [groupby_clause]
+        [having_clause]
+        [orderby_clause]

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/simple_case_bnf.txt

@@ -0,0 +1 @@
+CASE {operand} WHEN {test_value} THEN {match_result} ELSE {miss_result} END

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/simple_case_exp_example.txt

@@ -0,0 +1,16 @@
+select case c.nickName when null then '<no nick name>' else c.nickName end
+from Customer c
+
+// This NULL checking is such a common case that most dbs
+// define an abbreviated CASE form.  For example:
+select nvl( c.nickName, '<no nick name>' )
+from Customer c
+
+// or:
+select isnull( c.nickName, '<no nick name>' )
+from Customer c
+
+// the standard coalesce abbreviated form can be used
+// to achieve the same result:
+select coalesce( c.nickName, '<no nick name>' )
+from Customer c

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/simplest_query.java

@@ -0,0 +1 @@
+select c from com.acme.Cat c

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/simplest_query2.java

@@ -0,0 +1 @@
+select c from Cat c

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/string_literals_example.txt

@@ -0,0 +1,8 @@
+select c
+from Customer c
+where c.name = 'Acme'
+
+select c
+from Customer c
+where c.name = 'Acme''s Pretzel Logic'
+

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/substring_bnf.txt

@@ -0,0 +1 @@
+substring( string_expression, numeric_expression [, numeric_expression] )

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/update_statement_bnf.txt

@@ -1,8 +1,10 @@
 update_statement ::= update_clause [where_clause]
 
-update_clause ::= UPDATE entity_name [[AS] identification_variable] SET update_item {, update_item}*
+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
+update_item ::= [identification_variable.]{state_field | single_valued_object_field}
+        = new_value
 
 new_value ::= scalar_expression |
                 simple_entity_expression |

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/update_statement_hql.java

@@ -0,0 +1,8 @@
+String hqlUpdate =
+		"update Customer c " +
+		"set c.name = :newName " +
+		"where c.name = :oldName";
+int updatedEntities = session.createQuery( hqlUpdate )
+        .setString( "newName", newName )
+        .setString( "oldName", oldName )
+        .executeUpdate();

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/update_statement_jpql.java

@@ -0,0 +1,8 @@
+String jpqlUpdate =
+		"update Customer c " +
+		"set c.name = :newName " +
+		"where c.name = :oldName";
+int updatedEntities = entityManager.createQuery( jpqlUpdate )
+        .setString( "newName", newName )
+        .setString( "oldName", oldName )
+        .executeUpdate();

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/versioned_update_statement_hql.java

@@ -0,0 +1,8 @@
+String hqlVersionedUpdate =
+		"update versioned Customer c " +
+		"set c.name = :newName " +
+		"where c.name = :oldName";
+int updatedEntities = s.createQuery( hqlUpdate )
+        .setString( "newName", newName )
+        .setString( "oldName", oldName )
+        .executeUpdate();

documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/with_join_example.txt

@@ -0,0 +1,4 @@
+select distinct c
+from Customer c
+    left join c.orders o
+        with o.value > 5000.00