update processor chapter for JPA 3.2

Signed-off-by: Gavin King <[email protected]>

Author: gavinking

documentation/src/main/asciidoc/introduction/Hibernate_Introduction.adoc

@@ -20,7 +20,7 @@ include::Configuration.adoc[]
 include::Entities.adoc[]
 include::Mapping.adoc[]
 include::Interacting.adoc[]
-include::Generator.adoc[]
+include::Processor.adoc[]
 include::Tuning.adoc[]
 include::Advanced.adoc[]
 include::Credits.adoc[]

documentation/src/main/asciidoc/introduction/Introduction.adoc

@@ -768,6 +768,7 @@ This "test" is one which many people like to run even in production, when the sy
 
 It's now time to begin our journey toward actually _understanding_ the code we saw earlier.
 
+This introduction will guide you through the basic tasks involved in developing a program that uses Hibernate for persistence:
 This introduction will guide you through the basic tasks involved in developing a program that uses Hibernate for persistence:
 
 1. configuring and bootstrapping Hibernate, and obtaining an instance of `SessionFactory` or `EntityManagerFactory`,

documentation/src/main/asciidoc/introduction/Generator.adoc renamed to documentation/src/main/asciidoc/introduction/Processor.adoc

@@ -116,6 +116,56 @@ This is very useful for writing generic code in frameworks or libraries.
 For example, you could use it to create your own criteria query API.
 ====
 
+The JPA static metamodel for an entity also contains members representing the named queries and named entity graphs declared by `@NamedQuery`, `@NamedNativeQuery`, and `@NamedEntityGraph` annotations of the entity class.
+
+For example, if we had:
+
+[source,java]
+----
+@CheckHQL // validate named queries at compile time
+@NamedQuery(name="findBooksByTitle",
+            query="from Book where title like :title order by title")
+@Entity
+class Book { ... }
+----
+
+Then we may execute the query as follows:
+
+[source,java]
+----
+var books =
+        entityManager.createNamedQuery(Queries_._findBooksByTitle_)
+                .setParameter("title", titlePattern)
+                .setPage(page)
+                .getResultList();
+----
+
+Notice that no typecast was required here, since the generated code embeds the return type of the query as a type argument of the JPA `TypedQueryReference`:
+
+[source,java]
+----
+/**
+ * @see #_findBooksByTitle_
+ **/
+public static final String QUERY_FIND_BOOKS_BY_TITLE = "findBooksByTitle";
+
+
+/**
+ * The query named {@value QUERY_FIND_BOOKS_BY_TITLE}
+ * <pre>
+ * from Book where title like :title order by title
+ * </pre>
+ *
+ * @see org.example.Book
+ **/
+public static volatile TypedQueryReference<Book> _findBooksByTitle_;
+----
+
+[TIP]
+====
+Actually, Hibernate Processor doesn't require that such annotations be applied to the entity class itself, as we <<organizing-persistence,already saw earlier>>.
+====
+
 We've already been using metamodel references like `Book_.authors` and `Book.AUTHORS` in the previous chapters.
 So now let's see what else Hibernate Processor can do for us.