HHH-19364 - Introduce simplified dynamic query builders

Author: sebersole

documentation/src/main/asciidoc/userguide/Hibernate_User_Guide.adoc

@@ -31,6 +31,7 @@ include::chapters/caching/Caching.adoc[]
 include::chapters/events/Events.adoc[]
 include::chapters/query/hql/Query.adoc[]
 include::chapters/query/hql/QueryLanguage.adoc[]
+include::chapters/query/dynamic/DynamicQueries.adoc[]
 include::chapters/query/criteria/Criteria.adoc[]
 include::chapters/query/criteria/CriteriaExtensions.adoc[]
 include::chapters/query/native/Native.adoc[]

documentation/src/main/asciidoc/userguide/chapters/query/dynamic/DynamicQueries.adoc

@@ -0,0 +1,98 @@
+[[dynamic-queries]]
+== Dynamic Queries
+:root-project-dir: ../../../../../../../..
+
+Hibernate offers an API for creating dynamic representations of a query, augmenting that representation and then creating an executable form of that query.  The idea is similar in concept to <<chapters/query/criteria/Criteria.adoc#criteria,criteria queries>>, but focused on ease-of-use and less verbosity.
+
+[NOTE]
+====
+These APIs are new in 7.0 and considered incubating.
+====
+
+There is support for both <<dynamic-selection,selection>> and <<dynamic-mutation,mutation>> queries via the `DynamicSelection` and `DynamicMutation` contracts, respectively.  These can be obtained from both `Session` and `StatelessSession`.
+
+[[dynamic-selection]]
+=== DynamicSelection
+
+A `DynamicSelection` allows to iteratively build a query from a "base", adjust the query by adding sorting and restrictions and finally creating an executable <<hql-SelectionQuery,`SelectionQuery`>>.
+
+[NOTE]
+====
+For 7.0, only HQL is offered as a base.
+====
+
+====
+[source, java, indent=0]
+----
+Session session = ...;
+// create using the HQL "from Book" as the base
+DynamicSelection<Book> ds = session.createDynamicSelection(
+    "from Book",
+    Book.class
+);
+// from here we can augment the base query "from Book",
+// with either restrictions
+ds.restriction(
+    Restriction.restrict(
+        Book_.suggestedCost,
+        Range.closed(10.00, 19.99)
+    )
+);
+
+// or here with some sorting
+ds.order(
+    Order.asc(Book_.suggestedCost)
+)
+----
+====
+
+[NOTE]
+====
+Notice that generally the JPA static metamodel is a convenient and type-safe way to help build these sorting and restriction references.
+====
+
+After adjusting the query, we can obtain the executable `SelectionQuery`:
+
+====
+[source, java, indent=0]
+----
+SelectionQuery<Book> qry = ds.createQuery();
+List<Book> books = qry.getResultList();
+----
+====
+
+These calls can be chained, e.g.
+
+====
+[source, java, indent=0]
+----
+SelectionQuery<Book> qry = session.createDynamicSelection(
+    "from Book",
+    Book.class
+).restriction(
+    Restriction.restrict(
+        Book_.suggestedCost,
+        Range.closed(10.00, 19.99)
+    )
+).order(
+    Order.asc(Book_.suggestedCost)
+)
+.createQuery();
+----
+====
+
+[NOTE]
+====
+We expect, in future releases, to add the ability to handle pagination.
+
+We also expect to add the ability to use <<criteria,Criteria>> references as the base.  Possibly even `TypedQueryReference` references.
+
+// todo : consider these forms as well:
+//   - session.createDynamicSelection(Book.class)
+//   - session.createDynamicSelectionForDynamicModel(String rootEntityName)
+====
+
+[[dynamic-mutation]]
+=== DynamicMutation
+// todo : ...
+TODO