HHH-11186 - Add examples for all Hibernate annotations

Document @PersistenceUnit

documentation/src/main/asciidoc/userguide/appendices/Annotations.adoc

@@ -462,7 +462,7 @@ See the <<chapters/bootstrap/Bootstrap.adoc#bootstrap-jpa-compliant-PersistenceC
 
 The http://docs.oracle.com/javaee/7/api/javax/persistence/PersistenceUnit.html[`@PersistenceUnit`] annotation is used to specify the `EntityManagerFactory` that needs to be injected as a dependency.
 
-//TODO: Add example
+See the <<chapters/bootstrap/Bootstrap.adoc#bootstrap-jpa-compliant-PersistenceUnit-example, `@PersistenceUnit` mapping>> section for more info.
 
 [[annotations-jpa-persistenceunits]]
 ==== `@PersistenceUnits`

documentation/src/main/asciidoc/userguide/chapters/bootstrap/Bootstrap.adoc

@@ -35,16 +35,11 @@ It uses the terms _EE_ and _SE_ for these two approaches, but those terms are ve
 What the JPA spec calls EE bootstrapping implies the existence of a container (EE, OSGi, etc), who'll manage and inject the persistence context on behalf of the application.
 What it calls SE bootstrapping is everything else. We will use the terms container-bootstrapping and application-bootstrapping in this guide.
 
-[NOTE]
-====
-If you would like additional details on accessing and using `EntityManager` instances, sections 7.6 and 7.7 of the JPA 2.1 specification cover container-managed and application-managed `EntityManagers`, respectively.
-====
-
 For compliant container-bootstrapping, the container will build an `EntityManagerFactory` for each persistent-unit defined in the `META-INF/persistence.xml` configuration file
 and make that available to the application for injection via the `javax.persistence.PersistenceUnit` annotation or via JNDI lookup.
 
 [[bootstrap-jpa-compliant-PersistenceUnit-example]]
-.Injecting a `EntityManagerFactory`
+.Injecting the default `EntityManagerFactory`
 ====
 [source, JAVA, indent=0]
 ----
@@ -52,6 +47,18 @@ include::{sourcedir}/BootstrapTest.java[tags=bootstrap-jpa-compliant-Persistence
 ----
 ====
 
+Or, in case you have multiple Persistence Units (e.g. multiple `persistence.xml` configuration files),
+you can inject a specific `EntityManagerFactory` by Unit name:
+
+[[bootstrap-jpa-compliant-PersistenceUnit-configurable-example]]
+.Injecting a specific `EntityManagerFactory`
+====
+[source, JAVA, indent=0]
+----
+include::{sourcedir}/BootstrapTest.java[tags=bootstrap-jpa-compliant-PersistenceUnit-configurable-example]
+----
+====
+
 The `META-INF/persistence.xml` file looks as follows:
 
 [[bootstrap-jpa-compliant-persistence-xml-example]]
@@ -108,6 +115,11 @@ include::{sourcedir}/BootstrapTest.java[tags=bootstrap-jpa-compliant-Persistence
 ----
 ====
 
+[NOTE]
+====
+If you would like additional details on accessing and using `EntityManager` instances, sections 7.6 and 7.7 of the JPA 2.1 specification cover container-managed and application-managed `EntityManagers`, respectively.
+====
+
 [[bootstrap-jpa-xml-files]]
 ==== Externalizing XML mapping files
 

documentation/src/main/java/org/hibernate/userguide/model/Person.java

@@ -162,7 +162,7 @@ import javax.persistence.Version;
     ,
     // tag::jpa-read-only-entities-native-example[]
     @NamedQuery(
-        name = "get_person_by_name",
+        name = "get_read_only_person_by_name",
         query = "select p from Person p where name = :name",
         hints = {
             @QueryHint(

documentation/src/test/java/org/hibernate/userguide/bootstrap/BootstrapTest.java

@@ -412,6 +412,13 @@ public class BootstrapTest {
 	private EntityManagerFactory emf;
 	//end::bootstrap-jpa-compliant-PersistenceUnit-example[]
 
+	//tag::bootstrap-jpa-compliant-PersistenceUnit-configurable-example[]
+	@PersistenceUnit(
+		unitName = "CRM"
+	)
+	private EntityManagerFactory entityManagerFactory;
+	//end::bootstrap-jpa-compliant-PersistenceUnit-configurable-example[]
+
 	//tag::bootstrap-jpa-compliant-PersistenceContext-example[]
 	@PersistenceContext
 	private EntityManager em;