deprecate two unused types in the cache SPI + add javadoc
also correct some errors in the names of types - this is why it's better to use @link!!
This commit is contained in:
Gavin
Gavin King
parent
cf9578a9e0
commit
110596adb7
|
|
@ -18,12 +18,12 @@ import org.hibernate.engine.spi.SessionFactoryImplementor;
|
|||
*/
|
||||
public interface DomainDataRegionBuildingContext {
|
||||
/**
|
||||
* The CacheKeyFactory explicitly specified as part of the
|
||||
* bootstrap by the user, by some "container", etc.
|
||||
* The {@link CacheKeysFactory} explicitly specified as part of
|
||||
* the bootstrap by the user, by some "container", etc.
|
||||
*
|
||||
* If this method returns a non-null value, it is expected
|
||||
* that RegionFactory implementors will use to be its
|
||||
* CacheKeyFactory and return it when asked later.
|
||||
* If this method returns a non-null value, it is expected that
|
||||
* {@link RegionFactory} implementors will use to be its
|
||||
* {@link CacheKeysFactory} and return it when asked later.
|
||||
*/
|
||||
CacheKeysFactory getEnforcedCacheKeysFactory();
|
||||
|
||||
|
|
|
|||
|
|
@ -12,6 +12,8 @@ import org.hibernate.persister.collection.CollectionPersister;
|
|||
import org.hibernate.persister.entity.EntityPersister;
|
||||
|
||||
/**
|
||||
* A factory for keys into the second-level cache.
|
||||
*
|
||||
* @author Radim Vansa <rvansa@redhat.com>
|
||||
*/
|
||||
public interface CacheKeysFactory {
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ package org.hibernate.cache.spi;
|
|||
/**
|
||||
* Defines a context object that a {@link RegionFactory} is asked to create
|
||||
* ({@link RegionFactory#createTransactionContext}}) when a Hibernate Session
|
||||
* is created. It's lifecycle is that of the Session. It receives
|
||||
* is created. Its lifecycle is that of the Session. It receives
|
||||
* "transactional event callbacks" around joining and completing resource
|
||||
* transactions.
|
||||
*
|
||||
|
|
@ -26,13 +26,13 @@ package org.hibernate.cache.spi;
|
|||
* instead. Native transactional implementation may provide looser semantics
|
||||
* and 2LC implementation has to adapt to these.
|
||||
*
|
||||
* @implNote Even though a JTA transaction may involve more than one Session
|
||||
* the CacheTransactionContext is specific to each Session since the distinction
|
||||
* is generally unimportant. However, a provider is free to attempt to scope
|
||||
* these CacheTransactionContext instances in such a way that they may be
|
||||
* associated with more than one Session at a time. This SPI is designed
|
||||
* to not require this of the caching impl, but it certainly allows the
|
||||
* provider to do it
|
||||
* @implNote Even though a JTA transaction may involve more than one session,
|
||||
* the {@code CacheTransactionSynchronization} is specific to each session since
|
||||
* the distinction is generally unimportant. However, a provider is free to
|
||||
* attempt to scope these {@code CacheTransactionSynchronization} instances in
|
||||
* such a way that they may be associated with more than one session at a time.
|
||||
* This SPI is designed to not require this of the caching impl, but it certainly
|
||||
* allows the provider to do it.
|
||||
*
|
||||
* @author Steve Ebersole
|
||||
* @author Radim Vansa
|
||||
|
|
|
|||
|
|
@ -9,10 +9,11 @@ package org.hibernate.cache.spi;
|
|||
import org.hibernate.engine.spi.SharedSessionContractImplementor;
|
||||
|
||||
/**
|
||||
* Specialized Region whose data is accessed directly (not requiring key/item wrapping).
|
||||
* Specialized {@link Region} whose data is accessed directly,
|
||||
* without the need for key/item wrapping.
|
||||
*
|
||||
* Does not define a "remove" operation because Hibernate's query and timestamps caches
|
||||
* only ever "get" and "put"
|
||||
* Does not define a "remove" operation because Hibernate's
|
||||
* query and timestamps caches only ever "get" and "put".
|
||||
*
|
||||
* @author Steve Ebersole
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -12,51 +12,58 @@ import org.hibernate.cache.spi.access.NaturalIdDataAccess;
|
|||
import org.hibernate.metamodel.model.domain.NavigableRole;
|
||||
|
||||
/**
|
||||
* A Region for cacheable domain data - entity, collection, natural-id.
|
||||
*
|
||||
* Generally speaking, this type of data has:
|
||||
*
|
||||
* * specific key and value wrapping that needs to be applied
|
||||
* * specific access patterns ({@link EntityDataAccess}, etc),
|
||||
* including some form of locking
|
||||
* A {@linkplain Region second-level cache region} that holds cacheable
|
||||
* domain data:
|
||||
* <ul>
|
||||
* <li>the destructured state of entity instances and collections, and
|
||||
* <li>mappings from natural id to primary key.
|
||||
*</ul>
|
||||
* This type of data has:
|
||||
* <ul>
|
||||
* <li>key and value wrapping that should to be applied, and
|
||||
* <li>defined policies for managing concurrent data access, possibly
|
||||
* including some form of locking.
|
||||
* </ul>
|
||||
* These behaviors are defined by an instance of {@link EntityDataAccess},
|
||||
* {@link CollectionDataAccess}, or {@link NaturalIdDataAccess}).
|
||||
*
|
||||
* @author Steve Ebersole
|
||||
*/
|
||||
public interface DomainDataRegion extends Region {
|
||||
/**
|
||||
* Build a EntityRegionAccess instance representing access to entity data
|
||||
* stored in this cache region using the given AccessType.
|
||||
* Build a {@link EntityDataAccess} instance representing access to
|
||||
* destructured entity data stored in this cache region.
|
||||
*
|
||||
* @apiNote Calling this method is illegal if the given entity is
|
||||
* not cached
|
||||
* not cacheable
|
||||
*
|
||||
* @param rootEntityRole The root entity name for the hierarchy whose data
|
||||
* we want to access
|
||||
* @param rootEntityRole The root entity name for the hierarchy whose
|
||||
* data we want to access
|
||||
*
|
||||
* @throws org.hibernate.cache.CacheException If the provider cannot provide the requested access
|
||||
*/
|
||||
EntityDataAccess getEntityDataAccess(NavigableRole rootEntityRole);
|
||||
|
||||
/**
|
||||
* Build a NaturalIdRegionAccess instance representing access to natural-id
|
||||
* data stored in this cache region using the given AccessType.
|
||||
* Build a {@link NaturalIdDataAccess} instance representing access to
|
||||
* natural id mappings stored in this cache region.
|
||||
*
|
||||
* @apiNote Calling this method is illegal if the given entity is
|
||||
* not cached
|
||||
* @apiNote Calling this method is illegal if the given natural id is
|
||||
* not cacheable
|
||||
*
|
||||
* @param rootEntityRole The NavigableRole of the root entity whose
|
||||
* natural-id data we want to access
|
||||
* natural id data we want to access
|
||||
*
|
||||
* @throws org.hibernate.cache.CacheException If the provider cannot provide the requested access
|
||||
*/
|
||||
NaturalIdDataAccess getNaturalIdDataAccess(NavigableRole rootEntityRole);
|
||||
|
||||
/**
|
||||
* Build a CollectionRegionAccess instance representing access to collection
|
||||
* data stored in this cache region using the given AccessType.
|
||||
* Build a {@link CollectionDataAccess} instance representing access to
|
||||
* destructured collection data stored in this cache region.
|
||||
*
|
||||
* @apiNote Calling this method is illegal if the given entity is
|
||||
* not cached
|
||||
* @apiNote Calling this method is illegal if the given collection is
|
||||
* not cacheable
|
||||
*
|
||||
* @param collectionRole The NavigableRole of the collection whose data
|
||||
* we want to access
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@
|
|||
package org.hibernate.cache.spi;
|
||||
|
||||
/**
|
||||
* Optional Region contract defining support for extra statistic information
|
||||
* Optional contract for a {@link Region} defining support for extra statistic information.
|
||||
*
|
||||
* @author Steve Ebersole
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -8,20 +8,20 @@ package org.hibernate.cache.spi;
|
|||
|
||||
import java.io.Serializable;
|
||||
import java.util.HashMap;
|
||||
import java.util.HashSet;
|
||||
import java.util.Map;
|
||||
import java.util.Set;
|
||||
|
||||
import org.hibernate.Filter;
|
||||
import org.hibernate.Remove;
|
||||
import org.hibernate.engine.spi.TypedValue;
|
||||
import org.hibernate.internal.FilterImpl;
|
||||
import org.hibernate.type.Type;
|
||||
|
||||
/**
|
||||
* Allows cached queries to be keyed by enabled filters.
|
||||
*
|
||||
* @author Gavin King
|
||||
*
|
||||
* @deprecated this class is no longer used
|
||||
*/
|
||||
@Deprecated(since = "6.2") @Remove
|
||||
public final class FilterKey implements Serializable {
|
||||
private final String filterName;
|
||||
private final Map<String,TypedValue> filterParameters = new HashMap<>();
|
||||
|
|
|
|||
|
|
@ -16,8 +16,8 @@ import org.hibernate.query.spi.Limit;
|
|||
import org.hibernate.query.spi.QueryParameterBindings;
|
||||
|
||||
/**
|
||||
* A key that identifies a particular query with bound parameter values. This is the object Hibernate uses
|
||||
* as its key into its query cache.
|
||||
* A key that identifies a particular query with bound parameter values.
|
||||
* This is the object Hibernate uses as a key into its query cache.
|
||||
*
|
||||
* @author Gavin King
|
||||
* @author Steve Ebersole
|
||||
|
|
|
|||
|
|
@ -15,7 +15,13 @@ import org.hibernate.engine.spi.SharedSessionContractImplementor;
|
|||
|
||||
/**
|
||||
* Defines the responsibility for managing query result data caching
|
||||
* in regards to a specific region.
|
||||
* in a specific {@linkplain QueryResultsRegion query cache region}.
|
||||
* There may be multiple instances of {@code QueryResultsCache},
|
||||
* corresponding to second-level cache regions with distinct policies.
|
||||
* <p>
|
||||
* A {@code QueryResultsCache} must be used in conjunction with a
|
||||
* {@link TimestampsCache} which tracks invalidation of the query
|
||||
* spaces (tables) which affect the cached queries.
|
||||
*
|
||||
* @author Gavin King
|
||||
* @author Steve Ebersole
|
||||
|
|
|
|||
|
|
@ -7,8 +7,7 @@
|
|||
package org.hibernate.cache.spi;
|
||||
|
||||
/**
|
||||
* Defines the contract for a cache region which will specifically be used to
|
||||
* store query results.
|
||||
* Defines the contract for a cache region that stores query results.
|
||||
*
|
||||
* @author Steve Ebersole
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -6,6 +6,8 @@
|
|||
*/
|
||||
package org.hibernate.cache.spi;
|
||||
|
||||
import org.hibernate.Remove;
|
||||
|
||||
import java.io.Serializable;
|
||||
import java.util.Collections;
|
||||
import java.util.HashSet;
|
||||
|
|
@ -13,7 +15,10 @@ import java.util.Set;
|
|||
|
||||
/**
|
||||
* @author Steve Ebersole
|
||||
*
|
||||
* @deprecated This helper class is no longer used
|
||||
*/
|
||||
@Deprecated(since="6.2") @Remove
|
||||
public class QuerySpacesHelper {
|
||||
/**
|
||||
* Singleton access
|
||||
|
|
|
|||
|
|
@ -10,19 +10,23 @@ import org.hibernate.boot.spi.SessionFactoryOptions;
|
|||
import org.hibernate.cache.CacheException;
|
||||
|
||||
/**
|
||||
* Contract for a named "region". The concept of a Region might not
|
||||
* necessarily correlate to a specific concept in the underlying caching
|
||||
* provider - it is just a thing that can be referenced by name later.
|
||||
* Contract for a named cache "region". A logical region might not
|
||||
* necessarily correlate to any specific concept in the underlying
|
||||
* caching provider - it's just a thing that can be referenced by
|
||||
* name later.
|
||||
* <p/>
|
||||
* A region's name is "unqualified"; i.e. it is not prefixed by
|
||||
* {@link SessionFactoryOptions#getCacheRegionPrefix()}.
|
||||
* <p/>
|
||||
* Region is the base contract defining some common characteristics
|
||||
* regardless of the type of data intended to be stored within this
|
||||
* Region. The more specific sub-types are {@link DomainDataRegion}
|
||||
* (storing entity, collection and natural-id data) and
|
||||
* {@link DirectAccessRegion} (storing query result and timestamp
|
||||
* data).
|
||||
* {@code Region} is the base contract defining some common
|
||||
* characteristics regardless of the type of data intended to be
|
||||
* stored within the region. The more specific subtypes are:
|
||||
* <ul>
|
||||
* <li>{@link DomainDataRegion} for storing entity, collection and
|
||||
* natural-id data and
|
||||
* <li>{@link DirectAccessRegion} for storing query result and
|
||||
* timestamp data.
|
||||
* </ul>
|
||||
*
|
||||
* @author Steve Ebersole
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -19,11 +19,20 @@ import org.hibernate.service.Service;
|
|||
import org.hibernate.service.spi.Stoppable;
|
||||
|
||||
/**
|
||||
* Contract for building second level cache regions.
|
||||
* <p/>
|
||||
* Implementors should define a constructor in one of two forms:<ul>
|
||||
* <li>MyRegionFactoryImpl({@link java.util.Properties})</li>
|
||||
* <li>MyRegionFactoryImpl()</li>
|
||||
* Contract for building second-level cache regions, including
|
||||
* regions dedicated to storing:
|
||||
* <ul>
|
||||
* <li>{@linkplain #buildDomainDataRegion entity and collection}
|
||||
* instances,
|
||||
* <li>{@linkplain #buildQueryResultsRegion query result sets},
|
||||
* and
|
||||
* <li>{@linkplain #buildTimestampsRegion timestamps} used to
|
||||
* determine when a cached query result set is stale.
|
||||
* </ul>
|
||||
* Implementors should define a constructor in one of two forms:
|
||||
* <ul>
|
||||
* <li>{@code MyRegionFactoryImpl(java.util.Properties)}</li>
|
||||
* <li>{@code MyRegionFactoryImpl()}</li>
|
||||
* </ul>
|
||||
* Use the first when we need to read config properties prior to
|
||||
* {@link #start} being called.
|
||||
|
|
@ -40,8 +49,8 @@ public interface RegionFactory extends Service, Stoppable {
|
|||
String DEFAULT_UPDATE_TIMESTAMPS_REGION_UNQUALIFIED_NAME = "default-update-timestamps-region";
|
||||
|
||||
/**
|
||||
* Lifecycle callback to perform any necessary initialization of the
|
||||
* underlying cache provider. Called exactly once during the
|
||||
* Lifecycle callback to perform any necessary initialization of
|
||||
* the underlying cache provider. Called exactly once during the
|
||||
* construction of a {@link org.hibernate.internal.SessionFactoryImpl}.
|
||||
*
|
||||
* @param settings The settings in effect.
|
||||
|
|
@ -54,7 +63,7 @@ public interface RegionFactory extends Service, Stoppable {
|
|||
void start(SessionFactoryOptions settings, Map<String,Object> configValues) throws CacheException;
|
||||
|
||||
/**
|
||||
* By default should we perform "minimal puts" when using this second
|
||||
* By default, should we perform "minimal puts" when using this second
|
||||
* level cache implementation?
|
||||
*
|
||||
* @return True if "minimal puts" should be performed by default; false
|
||||
|
|
@ -63,7 +72,7 @@ public interface RegionFactory extends Service, Stoppable {
|
|||
boolean isMinimalPutsEnabledByDefault();
|
||||
|
||||
/**
|
||||
* Get the default access type for any "user model" data
|
||||
* Get the default access type for any "user model" data.
|
||||
*/
|
||||
AccessType getDefaultAccessType();
|
||||
|
||||
|
|
@ -74,16 +83,15 @@ public interface RegionFactory extends Service, Stoppable {
|
|||
}
|
||||
|
||||
/**
|
||||
* Generate a timestamp. This value is generally used for purpose of
|
||||
* locking/unlocking cache content depending upon the access-strategy being
|
||||
* used. The intended consumer of this method is the Session to manage
|
||||
* its {@link SharedSessionContractImplementor#getTransactionStartTimestamp} value.
|
||||
* Generate a timestamp. This value is generally used for purpose of
|
||||
* locking/unlocking cache content depending upon the access strategy
|
||||
* being used. It's also expected that this be the value used by the
|
||||
* {@link #createTransactionContext CacheTransactionSynchronization}
|
||||
* created by this {@code RegionFactory}.
|
||||
*
|
||||
* It is also expected that this be the value used for this's RegionFactory's
|
||||
* CacheTransactionContext
|
||||
*
|
||||
* @apiNote This "timestamp" need not be related to timestamp in the Java Date/millisecond
|
||||
* sense. It just needs to be an incrementing value
|
||||
* @apiNote This "timestamp" need not be related to timestamp in the
|
||||
* {@link java.util.Date#getTime()}/{@link System#currentTimeMillis()}
|
||||
* sense. It just needs to be an incrementing value.
|
||||
*/
|
||||
long nextTimestamp();
|
||||
|
||||
|
|
@ -93,7 +101,7 @@ public interface RegionFactory extends Service, Stoppable {
|
|||
}
|
||||
|
||||
/**
|
||||
* Create a named Region for holding domain model data
|
||||
* Create a named {@link Region} for holding domain model data
|
||||
*
|
||||
* @param regionConfig The user requested caching configuration for this Region
|
||||
* @param buildingContext Access to delegates useful in building the Region
|
||||
|
|
@ -103,7 +111,14 @@ public interface RegionFactory extends Service, Stoppable {
|
|||
DomainDataRegionBuildingContext buildingContext);
|
||||
|
||||
|
||||
/**
|
||||
* Create a named {@link Region} for holding query result sets.
|
||||
*/
|
||||
QueryResultsRegion buildQueryResultsRegion(String regionName, SessionFactoryImplementor sessionFactory);
|
||||
|
||||
/**
|
||||
* Create a named {@link Region} for holding timestamps used to
|
||||
* determine when a cached query result set is stale.
|
||||
*/
|
||||
TimestampsRegion buildTimestampsRegion(String regionName, SessionFactoryImplementor sessionFactory);
|
||||
}
|
||||
|
|
|
|||
|
|
@ -12,19 +12,30 @@ import org.hibernate.cache.CacheException;
|
|||
import org.hibernate.engine.spi.SharedSessionContractImplementor;
|
||||
|
||||
/**
|
||||
* Wrapper for a {@link TimestampsRegion} adding handling of stale results
|
||||
* Tracks invalidation of "query spaces" (tables) for the purpose of
|
||||
* determining if a cached query result set is stale. Implementations
|
||||
* use a {@linkplain TimestampsRegion special region} the second-level
|
||||
* cache to store invalidation timestamps.
|
||||
* <ul>
|
||||
* <li>A query space is {@linkplain #invalidate invalidated} in the
|
||||
* {@code TimestampsCache} when a SQL DML statement executed by
|
||||
* Hibernate affects the corresponding table.
|
||||
* <li>A cached query result set is {@linkplain #isUpToDate checked for
|
||||
* staleness} against the {@code TimestampsCache} when it is read
|
||||
* from the {@link QueryResultsCache}.
|
||||
* </ul>
|
||||
*
|
||||
* @author Steve Ebersole
|
||||
*/
|
||||
public interface TimestampsCache {
|
||||
/**
|
||||
* The region used to store all timestamps data
|
||||
* The region used to store all timestamp data.
|
||||
*/
|
||||
TimestampsRegion getRegion();
|
||||
|
||||
/**
|
||||
* Perform pre-invalidation of the passed spaces (table names)
|
||||
* against the timestamps region data
|
||||
* against the timestamp region data.
|
||||
*/
|
||||
void preInvalidate(
|
||||
String[] spaces,
|
||||
|
|
@ -32,7 +43,7 @@ public interface TimestampsCache {
|
|||
|
||||
/**
|
||||
* Perform invalidation of the passed spaces (table names)
|
||||
* against the timestamps region data
|
||||
* against the timestamp region data.
|
||||
*/
|
||||
void invalidate(
|
||||
String[] spaces,
|
||||
|
|
|
|||
|
|
@ -18,7 +18,7 @@ package org.hibernate.cache.spi;
|
|||
*/
|
||||
public interface TimestampsCacheFactory {
|
||||
/**
|
||||
* Build the TimestampsCache
|
||||
* Build the {@link TimestampsCache}.
|
||||
*/
|
||||
TimestampsCache buildTimestampsCache(CacheImplementor cacheManager, TimestampsRegion timestampsRegion);
|
||||
}
|
||||
|
|
|
|||
|
|
@ -7,6 +7,11 @@
|
|||
package org.hibernate.cache.spi;
|
||||
|
||||
/**
|
||||
* Defines the contract for a cache region that stores timestamps.
|
||||
* The timestamps are used to manage query results with respect to
|
||||
* staleness of the underlying tables (sometimes called "query spaces"
|
||||
* or "table spaces").
|
||||
*
|
||||
* @author Steve Ebersole
|
||||
*/
|
||||
public interface TimestampsRegion extends DirectAccessRegion {
|
||||
|
|
|
|||
|
|
@ -17,13 +17,13 @@ import org.hibernate.engine.spi.SharedSessionContractImplementor;
|
|||
* Navigable of the user's domain model in a transactionally ACID manner.
|
||||
*
|
||||
* @apiNote Note that the following methods are not considered "transactional"
|
||||
* in this sense : {@link #contains}, {@link #lockRegion}, {@link #unlockRegion},
|
||||
* {@link #evict}, {@link #evictAll}. The semantics of these methods come
|
||||
* from JPA's {@link Cache} contract.
|
||||
* in this sense: {@link #contains}, {@link #lockRegion}, {@link #unlockRegion},
|
||||
* {@link #evict}, {@link #evictAll}. The semantics of these methods come from
|
||||
* JPA's {@link Cache} contract.
|
||||
*
|
||||
* @implSpec The "non transactional" methods noted in the `@apiNote` should
|
||||
* be implemented to ignore any locking. In other words, if {@link #evict}
|
||||
* is called that item should be forcibly removed from the cache regardless of
|
||||
* @implSpec The "non-transactional" methods noted in the {@code @apiNote}
|
||||
* should be implemented to ignore any locking. That is, when {@link #evict}
|
||||
* is called, the item should be forcibly removed from the cache regardless of
|
||||
* whether anything has locked it.
|
||||
*
|
||||
* @author Steve Ebersole
|
||||
|
|
|
|||
Loading…
Reference in New Issue