add overload of refresh() accepting an EntityGraph

see issue jakartaee#437

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

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

@@ -885,6 +885,26 @@ void refresh(Object entity, LockModeType lockMode,
     void refresh(Object entity,
                  RefreshOption... options);
 
+    /**
+     * Refresh the state of the given managed entity instance from the
+     * database, along with all associated entities reachable by
+     * following the given {@link EntityGraph}, overwriting changes
+     * made to the entity, if any. This operation does not cascade to
+     * associations marked {@link CascadeType#REFRESH cascade=REFRESH}
+     * unless they are included in the given entity graph.
+     * @param entity  a managed entity instance
+     * @throws IllegalArgumentException if the instance is not an entity
+     *         or if the entity is not managed
+     * @throws TransactionRequiredException if there is no
+     *         transaction when invoked on a container-managed
+     *         entity manager of type
+     *         {@link PersistenceContextType#TRANSACTION}
+     * @throws EntityNotFoundException if the entity no longer exists in
+     *         the database
+     * @since 4.0
+     */
+    <T> void refresh(T entity, EntityGraph<T> entityGraph);
+
     /**
      * Clear the persistence context, causing all managed entities to
      * become detached. Changes made to entities that have not already