add code examples of EM and EMF lifecycle to javadoc

api/src/main/java/jakarta/persistence/EntityManager.java

@@ -45,17 +45,49 @@
  * and is thus considered quite error-prone. It is much safer to use
  * the methods {@link EntityManagerFactory#runInTransaction} and
  * {@link EntityManagerFactory#callInTransaction}.
+ * {@snippet :
+ * entityManagerFactory.runInTransaction(entityManager -> {
+ *     // 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 entityManager;
+ * }
  *
  * <p>If the persistence unit has
  * {@linkplain PersistenceUnitTransactionType#RESOURCE_LOCAL
  * resource local} transaction management, transactions must
  * be managed using the {@link EntityTransaction} obtained by
  * calling {@link #getTransaction()}.
  *
+ * <p>A complete idiom for custom application management of
+ * the {@link EntityManager} and its associated resource-local
+ * {@link EntityTransaction} is as follows:
+ * {@snippet :
+ * EntityManager entityManager = entityManagerFactory.createEntityManager();
+ * EntityTransaction transaction = entityManager.getTransaction();
+ * try {
+ *     transaction.begin();
+ *     // do work
+ *     ...
+ *     transaction.commit();
+ * }
+ * catch (Exception e) {
+ *     if (transaction.isActive()) transaction.rollback();
+ *     throw e;
+ * }
+ * finally {
+ *     entityManager.close();
+ * }
+ * }
+ *
  * <p>Each {@code EntityManager} instance is associated with a
  * distinct <em>persistence context</em>. A persistence context
  * is a set of entity instances in which for any given persistent

api/src/main/java/jakarta/persistence/EntityManagerFactory.java

@@ -59,16 +59,33 @@
  *     {@link Persistence#createEntityManagerFactory(PersistenceConfiguration)}.
  * </ul>
  *
+ * <p>Usually, there is exactly one {@code EntityManagerFactory} for
+ * each persistence unit:
+ * {@snippet :
+ * // create a factory at initialization time
+ * static final EntityManagerFactory entityManagerFactory =
+ *         Persistence.createEntityManagerFactory("orderMgt");
+ * }
+ *
  * <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 entityManagerFactory;
+ * }
  *
  * <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:
@@ -90,10 +107,15 @@
  * </ul>
  *
  * <p>When the application has finished using the entity manager
- * factory, and/or at application shutdown, the application should
- * {@linkplain #close} the entity manager factory. Once an
- * {@code EntityManagerFactory} has been closed, all its entity
- * managers are considered to be in the closed state.
+ * factory, or when the application terminates, the application
+ * should {@linkplain #close} the entity manager factory. If
+ * necessary, a {@link java.lang.ref.Cleaner} may be used:
+ * {@snippet :
+ * // factory should be destroyed before program terminates
+ * Cleaner.create().register(entityManagerFactory, entityManagerFactory::close);
+ * }
+ * Once an {@code EntityManagerFactory} has been closed, all its
+ * entity managers are considered to be in the closed state.
  *
  * @see EntityManager
  *