From 4bacd6603809d3e57e352ebe4b1c4958466edabd Mon Sep 17 00:00:00 2001
From: Gavin King <gavin@hibernate.org>
Date: Fri, 3 Nov 2023 17:07:17 +0100
Subject: [PATCH] add code examples of EM and EMF lifecycle to javadoc

---
 .../jakarta/persistence/EntityManager.java    | 15 ++++++++++++--
 .../persistence/EntityManagerFactory.java     | 20 +++++++++++++++++++
 2 files changed, 33 insertions(+), 2 deletions(-)

diff --git a/api/src/main/java/jakarta/persistence/EntityManager.java b/api/src/main/java/jakarta/persistence/EntityManager.java
index 882e234f..eddd9ec2 100644
--- a/api/src/main/java/jakarta/persistence/EntityManager.java
+++ b/api/src/main/java/jakarta/persistence/EntityManager.java
@@ -45,10 +45,21 @@
  * and is thus considered quite error-prone. It is much safer to use
  * the methods {@link EntityManagerFactory#runInTransaction} and
  * {@link EntityManagerFactory#callInTransaction}.
+ * {@snippet :
+ * emf.runInTransaction(em -> {
+ *     // do work in a persistence context
+ *     ...
+ * });
+ * }
  *
  * <p>In the Jakarta EE environment, a container-managed
- * {@link EntityManagerFactory} may be obtained by dependency
- * injection, using {@link PersistenceContext}.
+ * {@link EntityManager} may be obtained by dependency injection,
+ * using {@link PersistenceContext}.
+ * {@snippet :
+ * // inject the container-managed entity manager
+ * @PersistenceContext(unitName="orderMgt")
+ * EntityManager em;
+ * }
  *
  * <p>If the persistence unit has
  * {@linkplain PersistenceUnitTransactionType#RESOURCE_LOCAL
diff --git a/api/src/main/java/jakarta/persistence/EntityManagerFactory.java b/api/src/main/java/jakarta/persistence/EntityManagerFactory.java
index 9861c45d..9772d71e 100644
--- a/api/src/main/java/jakarta/persistence/EntityManagerFactory.java
+++ b/api/src/main/java/jakarta/persistence/EntityManagerFactory.java
@@ -59,9 +59,25 @@
  *     {@link Persistence#createEntityManagerFactory(PersistenceConfiguration)}.
  * </ul>
  *
+ * <p>Usually, there is exactly one {@code EntityManagerFactory} for
+ * each persistence unit:
+ * {@snippet :
+ * // create a factory at startup time
+ * static final EntityManagerFactory emf =
+ *         Persistence.createEntityManagerFactory("orderMgt");
+ * ...
+ * // destroy the factory before shutting down
+ * emf.close();
+ * }
+ *
  * <p>Alternatively, in the Jakarta EE environment, a
  * container-managed {@code EntityManagerFactory} may be obtained
  * by dependency injection, using {@link PersistenceUnit}.
+ * {@snippet :
+ * // inject the container-managed factory
+ * @PersistenceUnit(unitName="orderMgt")
+ * EntityManagerFactory emf;
+ * }
  *
  * <p>An application-managed {@code EntityManager} may be created
  * via a call to {@link #createEntityManager()}. However, this
@@ -69,6 +85,10 @@
  * management on the client, and is thus considered error-prone. It
  * is much safer to use the methods {@link #runInTransaction} and
  * {@link #callInTransaction} to obtain {@code EntityManager}s.
+ * Alternatively, in the Jakarta EE environment, a container-managed
+ * {@link EntityManager} may be obtained by dependency injection,
+ * using {@link PersistenceContext}, and the application need not
+ * interact with the {@code EntityManagerFactory} directly.
  *
  * <p>The {@code EntityManagerFactory} provides access to certain
  * other useful APIs: