From 61f71030fff62118aecc71fbb24908f44b64b2e8 Mon Sep 17 00:00:00 2001 From: Gavin Date: Fri, 30 Dec 2022 13:24:07 +0100 Subject: [PATCH] incorporate a useful rant about caching in javadoc --- .../hibernate/annotations/package-info.java | 40 +++++++++++++++++-- .../cache/spi/access/package-info.java | 38 ++++++++++-------- 2 files changed, 59 insertions(+), 19 deletions(-) diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/package-info.java b/hibernate-core/src/main/java/org/hibernate/annotations/package-info.java index e0ef0b9dcc..7bad703337 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/package-info.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/package-info.java @@ -131,12 +131,46 @@ * These two approaches cannot be used together. A {@code UserType} always takes precedence * over the compositional approach. *

- * Please see the User Guide or the package {@link org.hibernate.type} for further - * discussion. The packages {@link org.hibernate.type.descriptor.java} and + * The packages {@link org.hibernate.type.descriptor.java} and * {@link org.hibernate.type.descriptor.jdbc} contain the built-in implementations of * {@code JavaType} and {@code JdbcType}, respectively. + *

+ * Please see the User Guide or the package {@link org.hibernate.type} for further + * discussion. * - *

Dialect-specific native SQL

+ *

Second level cache

+ * + * When we make a decision to store an entity in the second-level cache, we must decide + * much more than just whether "to cache or not to cache". Among other considerations: + * + *

+ * In a multi-user system, these policies always depend quite sensitively on the nature + * of the given entity type, and cannot reasonably be fixed at a more global level. + *

+ * With all the above considerations in mind, we strongly recommend the use of the + * Hibernate-defined annotation {@link org.hibernate.annotations.Cache} to assign + * entities to the second-level cache. + *

+ * The JPA-defined {@link jakarta.persistence.Cacheable} annotation is almost useless + * to us, since: + *

+ *

+ * As an aside, the {@link jakarta.persistence.SharedCacheMode} enumeration is even worse: + * its only sensible values are {@code NONE} and {@code ENABLE_SELECTIVE}. The options + * {@code ALL} and {@code DISABLE_SELECTIVE} fit extremely poorly with the practices + * advocated above. + * + *

Dialect-specific native SQL

* * Many annotations in this package allow the specification of native SQL expressions or * even complete statements. For example: diff --git a/hibernate-core/src/main/java/org/hibernate/cache/spi/access/package-info.java b/hibernate-core/src/main/java/org/hibernate/cache/spi/access/package-info.java index ffaaf0f9aa..7d4ba28cc4 100644 --- a/hibernate-core/src/main/java/org/hibernate/cache/spi/access/package-info.java +++ b/hibernate-core/src/main/java/org/hibernate/cache/spi/access/package-info.java @@ -8,36 +8,42 @@ /** * Defines contracts for transactional and concurrent access to cached * {@linkplain org.hibernate.cache.spi.access.EntityDataAccess entity} and - * {@linkplain org.hibernate.cache.spi.access.CollectionDataAccess collection} data. Transactions pass in a - * timestamp indicating transaction start time which is then used to protect against concurrent access (exactly how - * that occurs is based on the actual access-strategy impl used). Two different implementation patterns are provided - * for: + * {@linkplain org.hibernate.cache.spi.access.CollectionDataAccess collection} data. + *

+ * Transactions pass in a timestamp indicating transaction start time which is then used to protect against concurrent + * access. Exactly how that happens is based on the actual access-strategy implementation used. + *

+ * Two different implementation patterns are provided for: *

*

- * The asynchronous access strategies are: + * The asynchronous 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 synchronous access strategy is + * The only synchronous access strategy is * {@linkplain org.hibernate.cache.spi.access.AccessType#TRANSACTIONAL transactional}. *

- * Note that, for an asynchronous cache, cache invalidation must be a two-step process (lock to unlock or - * lock to afterUpdate), since this is the only way to guarantee consistency with the database for a non-transactional - * cache implementation. For a synchronous 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 - * models (see the individual contracts for details). + * Note that: + *

+ * Hence, the contracts {@link org.hibernate.cache.spi.access.EntityDataAccess} and + * {@link org.hibernate.cache.spi.access.CollectionDataAccess} define a three-step process to allow for both models + * (see the individual contracts for details). *

* Note that query result caching does not go through an access strategy; those caches are managed directly against * the underlying {@link org.hibernate.cache.spi.QueryResultsRegion}.