add code examples of EM and EMF lifecycle to javadoc

jakartaee · Nov 3, 2023 · 4bacd66 · 4bacd66
1 parent e443814
commit 4bacd66
Show file tree

Hide file tree

Showing 2 changed files with 33 additions and 2 deletions.
diff --git 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
@@ -59,16 +59,36 @@
  *     {@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
  * approach places complete responsibility for cleanup and exception
  * 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: