add EntityManager/Query.setCacheRetrieveMode()/setCacheStoreMode()

see #383.

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

@@ -22,6 +22,9 @@
  * specify the behavior when data is retrieved by the
  * <code>find</code> methods and by queries.
  *
+ * @see EntityManager#setCacheRetrieveMode(CacheRetrieveMode)
+ * @see Query#setCacheRetrieveMode(CacheRetrieveMode)
+ *
  * @since 2.0
  */
 public enum CacheRetrieveMode implements FindOption {

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

@@ -22,6 +22,9 @@
  * the behavior when data is read from the database and when data is
  * committed into the database.
  *
+ * @see EntityManager#setCacheStoreMode(CacheStoreMode)
+ * @see Query#setCacheStoreMode(CacheStoreMode)
+ *
  * @since 2.0
  */
 public enum CacheStoreMode implements FindOption {

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

@@ -642,7 +642,35 @@ public void refresh(Object entity, LockModeType lockMode,
      */
     public LockModeType getLockMode(Object entity);
 
-    /** 
+    /**
+     * Set the cache retrieval mode that is in effect during
+     * query execution. This cache retrieval mode overrides the
+     * cache retrieve mode in use by the entity manager.
+     * @param cacheRetrieveMode cache retrieval mode
+     * @since 3.2
+     */
+    public void setCacheRetrieveMode(CacheRetrieveMode cacheRetrieveMode);
+
+    /**
+     * Set the default cache storage mode for this persistence context.
+     * @param cacheStoreMode cache storage mode
+     * @since 3.2
+     */
+    public void setCacheStoreMode(CacheStoreMode cacheStoreMode);
+
+    /**
+     * The cache retrieval mode for this persistence context.
+     * @since 3.2
+     */
+    public CacheRetrieveMode getCacheRetrieveMode();
+
+    /**
+     * The cache storage mode for this persistence context.
+     * @since 3.2
+     */
+    public CacheStoreMode getCacheStoreMode();
+
+    /**
      * Set an entity manager property or hint. 
      * If a vendor-specific property or hint is not recognized, it is
      * silently ignored. 

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

@@ -512,6 +512,40 @@ Query setParameter(int position, Date value,
      */
     LockModeType getLockMode();
 
+    /**
+     * Set the cache retrieval mode that is in effect during
+     * query execution. This cache retrieval mode overrides the
+     * cache retrieve mode in use by the entity manager.
+     * @param cacheRetrieveMode cache retrieval mode
+     * @return the same query instance
+     * @since 3.2
+     */
+    Query setCacheRetrieveMode(CacheRetrieveMode cacheRetrieveMode);
+
+    /**
+     * Set the cache storage mode that is in effect during
+     * query execution. This cache storage mode overrides the
+     * cache storage mode in use by the entity manager.
+     * @param cacheStoreMode cache storage mode
+     * @return the same query instance
+     * @since 3.2
+     */
+    Query setCacheStoreMode(CacheStoreMode cacheStoreMode);
+
+    /**
+     * The cache retrieval mode that will be in effect during
+     * query execution.
+     * @since 3.2
+     */
+    CacheRetrieveMode getCacheRetrieveMode();
+
+    /**
+     * The cache storage mode that will be in effect during
+     * query execution.
+     * @since 3.2
+     */
+    CacheStoreMode getCacheStoreMode();
+
     /**
      * Return an object of the specified type to allow access to 
      * the provider-specific API.  If the provider's query 

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

@@ -261,6 +261,26 @@ StoredProcedureQuery setParameter(int position,
      */
     StoredProcedureQuery setFlushMode(FlushModeType flushMode);
 
+    /**
+     * Set the cache retrieval mode that is in effect during
+     * query execution. This cache retrieval mode overrides the
+     * cache retrieve mode in use by the entity manager.
+     * @param cacheRetrieveMode cache retrieval mode
+     * @return the same query instance
+     * @since 3.2
+     */
+    StoredProcedureQuery setCacheRetrieveMode(CacheRetrieveMode cacheRetrieveMode);
+
+    /**
+     * Set the cache storage mode that is in effect during
+     * query execution. This cache storage mode overrides the
+     * cache storage mode in use by the entity manager.
+     * @param cacheStoreMode cache storage mode
+     * @return the same query instance
+     * @since 3.2
+     */
+    StoredProcedureQuery setCacheStoreMode(CacheStoreMode cacheStoreMode);
+
     /**
      * Register a positional parameter.
      * All parameters must be registered.

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

@@ -316,4 +316,24 @@ TypedQuery<X> setParameter(int position, Date value,
       */
      TypedQuery<X> setLockMode(LockModeType lockMode);
 
+    /**
+     * Set the cache retrieval mode that is in effect during
+     * query execution. This cache retrieval mode overrides the
+     * cache retrieve mode in use by the entity manager.
+     * @param cacheRetrieveMode cache retrieval mode
+     * @return the same query instance
+     * @since 3.2
+     */
+    TypedQuery<X> setCacheRetrieveMode(CacheRetrieveMode cacheRetrieveMode);
+
+    /**
+     * Set the cache storage mode that is in effect during
+     * query execution. This cache storage mode overrides the
+     * cache storage mode in use by the entity manager.
+     * @param cacheStoreMode cache storage mode
+     * @return the same query instance
+     * @since 3.2
+     */
+    TypedQuery<X> setCacheStoreMode(CacheStoreMode cacheStoreMode);
+
 }