document future plans for some dupe enums

This commit is contained in:
Gavin 2022-12-28 01:40:21 +01:00
parent 16be6a821b
commit 4d3dd2c436
4 changed files with 28 additions and 12 deletions

View File

@ -12,6 +12,13 @@ import java.util.Locale;
* Enumerates the policies for managing concurrent access to the shared
* second-level cache.
*
* @apiNote This enumeration is isomorphic to
* {@link org.hibernate.annotations.CacheConcurrencyStrategy}.
* We don't really need both, but one is part of this SPI,
* and one forms part of the API of the annotations package.
* In the future, it would be nice to replace them both with
* a new {@code org.hibernate.CacheConcurrencyPolicy} enum.
*
* @author Steve Ebersole
*/
public enum AccessType {

View File

@ -25,13 +25,15 @@
* </li>
* </ul>
* <p>
* The <i>asynchronous</i> access strategies are: {@link org.hibernate.cache.spi.access.AccessType#READ_ONLY read-only},
* {@link org.hibernate.cache.spi.access.AccessType#READ_WRITE read-write} and
* {@link org.hibernate.cache.spi.access.AccessType#NONSTRICT_READ_WRITE nonstrict-read-write}. The only
* <i>synchronous</i> access strategy is {@linkplain org.hibernate.cache.spi.access.AccessType#TRANSACTIONAL transactional}.
* The <i>asynchronous</i> access strategies are:
* {@linkplain org.hibernate.cache.spi.access.AccessType#READ_ONLY read-only},
* {@linkplain org.hibernate.cache.spi.access.AccessType#READ_WRITE read-write} and
* {@linkplain org.hibernate.cache.spi.access.AccessType#NONSTRICT_READ_WRITE nonstrict-read-write}.
* The only <i>synchronous</i> access strategy is
* {@linkplain org.hibernate.cache.spi.access.AccessType#TRANSACTIONAL transactional}.
* <p>
* Note that, for an <i>asynchronous</i> cache, cache invalidation must be a two-step process (lock->unlock or
* lock->afterUpdate), since this is the only way to guarantee consistency with the database for a nontransactional
* lock->afterUpdate), since this is the only way to guarantee consistency with the database for a non-transactional
* cache implementation. For a <i>synchronous</i> cache, cache invalidation is a single step process (evict or update).
* Hence, these contracts ({@link org.hibernate.cache.spi.access.EntityDataAccess} and
* {@link org.hibernate.cache.spi.access.CollectionDataAccess}) define a three-step process to cater for both

View File

@ -11,27 +11,29 @@ import org.hibernate.annotations.OptimisticLockType;
/**
* Describes how an entity should be optimistically locked.
* <p>
* This enumeration is mainly for internal use, since it
* is isomorphic to {@link OptimisticLockType}.
*
* @apiNote This enumeration is mainly for internal use, since it
* is isomorphic to {@link OptimisticLockType}. In the
* future, it would be nice to replace them both with a
* new {@code org.hibernate.OptimisticLockCheck} enum.
*
* @author Steve Ebersole
*/
public enum OptimisticLockStyle {
/**
* no optimistic locking
* No optimistic locking.
*/
NONE,
/**
* use a dedicated version column
* Optimistic locking via a dedicated version or timestamp column.
*/
VERSION,
/**
* dirty columns are compared
* Optimistic locking via comparison of dirty columns.
*/
DIRTY,
/**
* all columns are compared
* Optimistic locking via comparison of all columns.
*/
ALL;

View File

@ -12,6 +12,11 @@ import org.hibernate.annotations.ResultCheckStyle;
* For persistence operations (INSERT, UPDATE, DELETE) what style of
* determining results (success/failure) is to be used.
*
* @apiNote This enumeration is mainly for internal use, since it
* is isomorphic to {@link ResultCheckStyle}. In the
* future, it would be nice to replace them both with a
* new {@code org.hibernate.ResultCheck} enum.
*
* @author Steve Ebersole
*/
public enum ExecuteUpdateResultCheckStyle {