Skip to content

Commit

Permalink
add RefreshOption and overload EM.refresh()
Browse files Browse the repository at this point in the history
see #399
  • Loading branch information
gavinking committed Aug 11, 2023
1 parent 996aa8a commit 74798b7
Show file tree
Hide file tree
Showing 7 changed files with 135 additions and 7 deletions.
2 changes: 1 addition & 1 deletion api/src/main/java/jakarta/persistence/CacheStoreMode.java
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
49 changes: 47 additions & 2 deletions api/src/main/java/jakarta/persistence/EntityManager.java
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion api/src/main/java/jakarta/persistence/LockModeType.java
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
38 changes: 38 additions & 0 deletions api/src/main/java/jakarta/persistence/RefreshOption.java
Original file line number Diff line number Diff line change
@@ -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 {
}
2 changes: 1 addition & 1 deletion api/src/main/java/jakarta/persistence/Timeout.java
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down
47 changes: 46 additions & 1 deletion spec/src/main/asciidoc/ch03-entity-operations.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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
Expand Down

0 comments on commit 74798b7

Please sign in to comment.