HHH-6082 - Incorporate EntityManager documentation into main dev guide

documentation/src/main/docbook/devguide/en-US/chapters/hql/HQL_JPQL.xml

@@ -1321,18 +1321,119 @@
                 <programlisting><xi:include href="extras/member_of_collection_example.txt" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text"/></programlisting>
             </example>
         </section>
+
+        <section>
+            <title>NOT predicate operator</title>
+            <para>
+                The <literal>NOT</literal> operator is used to negate the predicate that follows it.  If that
+                following predicate is true, the NOT resolves to false.  If the predicate is true, NOT resolves to
+                false.  If the predicate is unknown, the NOT resolves to unknown as well.
+            </para>
+        </section>
+
+        <section>
+            <title>AND predicate operator</title>
+            <para>
+                The <literal>AND</literal> operator is used to combine 2 predicate expressions.  The result of the
+                AND expression is true if and only if both predicates resolve to true.  If either predicate resolves
+                to unknown, the AND expression resolves to unknown as well.  Otherwise, the result is false.
+            </para>
+        </section>
+
+        <section>
+            <title>OR predicate operator</title>
+            <para>
+                The <literal>OR</literal> operator is used to combine 2 predicate expressions.  The result of the
+                OR expression is true if either predicate resolves to true.  If both predicates resolve to unknown, the
+                OR expression resolves to unknown.  Otherwise, the result is false.
+            </para>
+        </section>
     </section>
 
     <section id="ql-where-clause">
         <title>The <literal>WHERE</literal> clause</title>
+        <para>
+            The <literal>WHERE</literal> clause of a query is made up of predicates which assert whether values in
+            each potential row match the predicated checks.  Thus, the where clause restricts the results returned
+            from a select query and limits the scope of update and delete queries.
+        </para>
     </section>
 
     <section id="ql-grouping">
         <title>Grouping</title>
+        <para>
+            The <literal>GROUP BY</literal> clause allows building aggregated results for various value groups.  As an
+            example, consider the following queries:
+        </para>
+        <example id="group_by_illustration">
+            <title>Group-by illustration</title>
+            <programlisting><xi:include href="extras/group_by_illustration.txt" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text"/></programlisting>
+        </example>
+        <para>
+            The first query retrieves the complete total of all orders.  The second retrieves the total for each
+            customer; grouped by each customer.
+        </para>
+        <para>
+            In a grouped query, the where clause applies to the non aggregated values (essentially it determines whether
+            rows will make it into the aggregation).  The <literal>HAVING</literal> clause also restricts results,
+            but it operates on the aggregated values.  In the <xref linkend="group_by_illustration"/> example,
+            we retrieved order totals for all customers.  If that ended up being too much data to deal with,
+            we might want to restrict the results to focus only on customers with a summed order total of more than
+            $10,000.00:
+        </para>
+        <example id="having_illustration">
+            <title>Having illustration</title>
+            <programlisting><xi:include href="extras/having_illustration.txt" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text"/></programlisting>
+        </example>
+        <para>
+            The HAVING clause follows the same rules as the WHERE clause and is also made up of predicates.  HAVING is
+            applied after the groupings and aggregations have been done; WHERE is applied before.
+        </para>
     </section>
 
     <section id="ql-ordering">
         <title>Ordering</title>
+        <para>
+            The results of the query can also be ordered.  The <literal>ORDER BY</literal> clause is used to specify
+            the selected values to be used to order the result.  The types of expressions considered valid as part
+             of the order-by clause include:
+        </para>
+        <itemizedlist>
+            <listitem>
+                <para>
+                    state fields
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    component/embeddable attributes
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    scalar expressions such as arithmetic operations, functions, etc.
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    identification variable declared in the select clause for any of the previous expression types
+                </para>
+            </listitem>
+        </itemizedlist>
+        <para>
+            Additionally, JPQL says that all values referenced in the order-by clause must be named in the select
+            clause.  HQL does not mandate that restriction, but applications desiring database portability should be
+            aware that not all databases support referencing values in the order-by clause that are not referenced
+            in the select clause.
+        </para>
+        <para>
+            Individual expressions in the order-by can be qualified with either <literal>ASC</literal> (ascending) or
+            <literal>DESC</literal> (descending) to indicated the desired ordering direction.
+        </para>
+        <example>
+            <title>Order-by examples</title>
+            <programlisting><xi:include href="extras/order_by_example.txt" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text"/></programlisting>
+        </example>
     </section>
 
     <section id="ql-api">

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

@@ -0,0 +1,10 @@
+// retrieve the total for all orders
+select sum( o.total )
+from Order o
+
+// retrieve the total of all orders
+// *grouped by* customer
+select c.id, sum( o.total )
+from Order o
+    inner join o.customer c
+group by c.id

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

@@ -0,0 +1,5 @@
+select c.id, sum( o.total )
+from Order o
+    inner join o.customer c
+group by c.id
+having sum( o.total ) > 10000.00

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

@@ -0,0 +1,10 @@
+// legal because p.name is implicitly part of p
+select p
+from Person p
+order by p.name
+
+select c.id, sum( o.total ) as t
+from Order o
+    inner join o.customer c
+group by c.id
+order by t

hibernate-entitymanager/src/main/docbook/en/master.xml

@@ -120,7 +120,7 @@
   <xi:include href="modules/migrated/batch.xml"
               xmlns:xi="http://www.w3.org/2001/XInclude" />
 
-  <xi:include href="modules/query_ejbql.xml"
+  <xi:include href="modules/migrated/query_ejbql.xml"
               xmlns:xi="http://www.w3.org/2001/XInclude" />
 
   <xi:include href="modules/query_criteria.xml"