add RefreshOption and overload EM.refresh()

see #399

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

@@ -27,7 +27,7 @@
  *
  * @since 2.0
  */
-public enum CacheStoreMode implements FindOption {
+public enum CacheStoreMode implements FindOption, RefreshOption {
 
     /**
      * Insert entity data into cache when read from database

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

@@ -513,7 +513,7 @@ public void lock(Object entity, LockModeType lockMode,
      * @since 2.0
      */     
     public void refresh(Object entity,
-                            Map<String, Object> properties); 
+                        Map<String, Object> properties);
 
     /**
      * Refresh the state of the instance from the database, 
@@ -597,7 +597,52 @@ public void refresh(Object entity,
      */
     public void refresh(Object entity, LockModeType lockMode,
                         Map<String, Object> properties);
-
+
+    /**
+     * Refresh the state of the given entity instance from the
+     * database, using the specified {@linkplain RefreshOption options},
+     * overwriting changes made to the entity, if any. If the supplied
+     * options include a {@link LockModeType}, lock the given entity with
+     * respect to the specified lock type.
+     * <p>If the lock mode type is pessimistic and the entity instance is
+     * found but cannot be locked:
+     * <ul>
+     * <li> the <code>PessimisticLockException</code> will be thrown if
+     *      the database locking failure causes transaction-level rollback
+     * <li> the <code>LockTimeoutException</code> will be thrown if the
+     *      database locking failure causes only statement-level rollback
+     * </ul>
+     * <p>If a vendor-specific {@link RefreshOption} is not recognized,
+     * it is silently ignored.
+     * <p>Portable applications should not rely on the standard
+     * {@linkplain Timeout timeout option}. Depending on the database in
+     * use and the locking mechanisms used by the provider, the hint may
+     * or may not be observed.
+     * @param entity  entity instance
+     * @param options  standard and vendor-specific options
+     * @throws IllegalArgumentException if the instance is not an entity
+     *         or the entity is not managed
+     * @throws TransactionRequiredException if invoked on a
+     *         container-managed entity manager of type
+     *         <code>PersistenceContextType.TRANSACTION</code> when there
+     *         is no transaction; if invoked on an extended entity manager
+     *         when there is no transaction and a lock mode other than
+     *         <code>NONE</code> has been specified; or if invoked on an
+     *         extended entity manager that has not been joined to the
+     *         current transaction and a lock mode other than
+     *         <code>NONE</code> has been specified
+     * @throws EntityNotFoundException if the entity no longer exists in
+     *         the database
+     * @throws PessimisticLockException if pessimistic locking fails and
+     *         the transaction is rolled back
+     * @throws LockTimeoutException if pessimistic locking fails and only
+     *         the statement is rolled back
+     * @throws PersistenceException if an unsupported lock call is made
+     * @since 3.2
+     */
+    public void refresh(Object entity,
+                        RefreshOption... options);
+
     /**
      * Clear the persistence context, causing all managed
      * entities to become detached. Changes made to entities that

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

@@ -126,7 +126,7 @@
  * @since 1.0
  *
  */
-public enum LockModeType implements FindOption {
+public enum LockModeType implements FindOption, RefreshOption {
     /**
      *  Synonymous with <code>OPTIMISTIC</code>.
      *  <code>OPTIMISTIC</code> is to be preferred for new

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

@@ -27,7 +27,7 @@
  *
  * @since 2.0
  */
-public enum PessimisticLockScope implements FindOption {
+public enum PessimisticLockScope implements FindOption, RefreshOption {
 
     /**
      * This value defines the default behavior for pessimistic locking.

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

@@ -0,0 +1,38 @@
+/*
+ * Copyright (c) 2008, 2020 Oracle and/or its affiliates. All rights reserved.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0,
+ * or the Eclipse Distribution License v. 1.0 which is available at
+ * http://www.eclipse.org/org/documents/edl-v10.php.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
+ */
+
+// Contributors:
+//     Gavin King      - 3.2
+
+
+package jakarta.persistence;
+
+/**
+ * An option influencing the behavior of {@link EntityManager#refresh}.
+ * Built-in options control {@linkplain LockModeType locking},
+ * {@linkplain CacheStoreMode cache interaction}, and
+ * {@linkplain Timeout timeouts}.
+ *
+ * <p>This interface may be implemented by custom provider-specific
+ * options which extend the options defined by the specification.
+ *
+ * @see LockModeType
+ * @see PessimisticLockScope
+ * @see CacheStoreMode
+ * @see Timeout
+ *
+ * @see EntityManager#refresh(Object, RefreshOption...)
+ *
+ * @since 3.2
+ */
+public interface RefreshOption {
+}

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

@@ -22,7 +22,7 @@
  *
  * @since 3.2
  */
-public class Timeout implements FindOption {
+public class Timeout implements FindOption, RefreshOption {
     private final int milliseconds;
 
     private Timeout(int milliseconds) {

spec/src/main/asciidoc/ch03-entity-operations.adoc

@@ -546,7 +546,7 @@ public interface EntityManager extends AutoCloseable {
      * @since 2.0
      */
     public void refresh(Object entity,
-                            Map<String, Object> properties);
+                        Map<String, Object> properties);
 
     /**
      * Refresh the state of the instance from the database,
@@ -631,6 +631,51 @@ public interface EntityManager extends AutoCloseable {
     public void refresh(Object entity, LockModeType lockMode,
                         Map<String, Object> properties);
 
+    /**
+     * Refresh the state of the given entity instance from the
+     * database, using the specified {@linkplain RefreshOption options},
+     * overwriting changes made to the entity, if any. If the supplied
+     * options include a {@link LockModeType}, lock the given entity with
+     * respect to the specified lock type.
+     * <p>If the lock mode type is pessimistic and the entity instance is
+     * found but cannot be locked:
+     * <ul>
+     * <li> the <code>PessimisticLockException</code> will be thrown if
+     *      the database locking failure causes transaction-level rollback
+     * <li> the <code>LockTimeoutException</code> will be thrown if the
+     *      database locking failure causes only statement-level rollback
+     * </ul>
+     * <p>If a vendor-specific {@link RefreshOption} is not recognized,
+     * it is silently ignored.
+     * <p>Portable applications should not rely on the standard
+     * {@linkplain Timeout timeout option}. Depending on the database in
+     * use and the locking mechanisms used by the provider, the hint may
+     * or may not be observed.
+     * @param entity  entity instance
+     * @param options  standard and vendor-specific options
+     * @throws IllegalArgumentException if the instance is not an entity
+     *         or the entity is not managed
+     * @throws TransactionRequiredException if invoked on a
+     *         container-managed entity manager of type
+     *         <code>PersistenceContextType.TRANSACTION</code> when there
+     *         is no transaction; if invoked on an extended entity manager
+     *         when there is no transaction and a lock mode other than
+     *         <code>NONE</code> has been specified; or if invoked on an
+     *         extended entity manager that has not been joined to the
+     *         current transaction and a lock mode other than
+     *         <code>NONE</code> has been specified
+     * @throws EntityNotFoundException if the entity no longer exists in
+     *         the database
+     * @throws PessimisticLockException if pessimistic locking fails and
+     *         the transaction is rolled back
+     * @throws LockTimeoutException if pessimistic locking fails and only
+     *         the statement is rolled back
+     * @throws PersistenceException if an unsupported lock call is made
+     * @since 3.2
+     */
+    public void refresh(Object entity,
+                        RefreshOption... options);
+
     /**
      * Clear the persistence context, causing all managed
      * entities to become detached. Changes made to entities that