/*
 * Hibernate, Relational Persistence for Idiomatic Java
 *
 * License: GNU Lesser General Public License (LGPL), version 2.1 or later.
 * See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
 */
package org.hibernate;

import java.io.Serializable;

Provides an API for querying/managing the second level cache regions.

CAUTION: None of these methods respect any isolation or transactional
semantics associated with the underlying caches.  Specifically, evictions
perform an immediate "hard" removal outside any transactions and/or locking
scheme(s).
Author:
Steve Ebersole/**
 * Provides an API for querying/managing the second level cache regions.
 * <p/>
 * CAUTION: None of these methods respect any isolation or transactional
 * semantics associated with the underlying caches.  Specifically, evictions
 * perform an immediate "hard" removal outside any transactions and/or locking
 * scheme(s).
 *
 * @author Steve Ebersole
 */
@SuppressWarnings( {"UnusedDeclaration"})
public interface Cache extends javax.persistence.Cache {
	
Access to the SessionFactory this Cache is bound to.
Returns:
The SessionFactory/**
	 * Access to the SessionFactory this Cache is bound to.
	 *
	 * @return The SessionFactory
	 */
	SessionFactory getSessionFactory();



	// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	// Entity data

	
Determine whether the cache contains data for the given entity "instance".

The semantic here is whether the cache contains data visible for the
current call context.
Params:
entityClass – The entity class.
identifier – The entity identifier
Returns:
True if the underlying cache contains corresponding data; false
otherwise./**
	 * Determine whether the cache contains data for the given entity "instance".
	 * <p/>
	 * The semantic here is whether the cache contains data visible for the
	 * current call context.
	 *
	 * @param entityClass The entity class.
	 * @param identifier The entity identifier
	 *
	 * @return True if the underlying cache contains corresponding data; false
	 * otherwise.
	 */
	boolean containsEntity(Class entityClass, Serializable identifier);

	
Determine whether the cache contains data for the given entity "instance".

The semantic here is whether the cache contains data visible for the
current call context.
Params:
entityName – The entity name.
identifier – The entity identifier
Returns:
True if the underlying cache contains corresponding data; false otherwise./**
	 * Determine whether the cache contains data for the given entity "instance".
	 * <p/>
	 * The semantic here is whether the cache contains data visible for the
	 * current call context.
	 *
	 * @param entityName The entity name.
	 * @param identifier The entity identifier
	 *
	 * @return True if the underlying cache contains corresponding data; false otherwise.
	 */
	boolean containsEntity(String entityName, Serializable identifier);

	
Evicts the entity data for a particular entity "instance".
Params:
entityClass – The entity class.
identifier – The entity identifier
Since:
5.3/**
	 * Evicts the entity data for a particular entity "instance".
	 *
	 * @param entityClass The entity class.
	 * @param identifier The entity identifier
	 *
	 * @since 5.3
	 */
	void evictEntityData(Class entityClass, Serializable identifier);

	
Evicts the entity data for a particular entity "instance".
Params:
entityName – The entity name.
identifier – The entity identifier
Since:
5.3/**
	 * Evicts the entity data for a particular entity "instance".
	 *
	 * @param entityName The entity name.
	 * @param identifier The entity identifier
	 *
	 * @since 5.3
	 */
	void evictEntityData(String entityName, Serializable identifier);

	
Evicts all entity data from the given region (i.e. for all entities of
type).
Params:
entityClass – The entity class.
Since:
5.3/**
	 * Evicts all entity data from the given region (i.e. for all entities of
	 * type).
	 *
	 * @param entityClass The entity class.
	 *
	 * @since 5.3
	 */
	void evictEntityData(Class entityClass);

	
Evicts all entity data from the given region (i.e. for all entities of
type).
Params:
entityName – The entity name.
Since:
5.3/**
	 * Evicts all entity data from the given region (i.e. for all entities of
	 * type).
	 *
	 * @param entityName The entity name.
	 *
	 * @since 5.3
	 */
	void evictEntityData(String entityName);

	
Evict data from all entity regions.
Since:
5.3/**
	 * Evict data from all entity regions.
	 *
	 * @since 5.3
	 */
	void evictEntityData();


	// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	// Natural-id data


	
Evict cached data for the given entity's natural-id
Params:
entityClass – The entity class.
Since:
5.3/**
	 * Evict cached data for the given entity's natural-id
	 *
	 * @param entityClass The entity class.
	 *
	 * @since 5.3
	 */
	void evictNaturalIdData(Class entityClass);

	
Evict cached data for the given entity's natural-id
Params:
entityName – The entity name.
Since:
5.3/**
	 * Evict cached data for the given entity's natural-id
	 *
	 * @param entityName The entity name.
	 *
	 * @since 5.3
	 */
	void evictNaturalIdData(String entityName);

	
Evict cached data for all natural-ids (for all entities)
Since:
5.3/**
	 * Evict cached data for all natural-ids (for all entities)
	 *
	 * @since 5.3
	 */
	void evictNaturalIdData();




	// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	// Collection data

	
Determine whether the cache contains data for the given collection.

The semantic here is whether the cache contains data visible for the
current call context.
Params:
role – The name of the collection role (in form
[owner-entity-name].[collection-property-name]) whose regions should be
evicted.
ownerIdentifier – The identifier of the owning entity
Returns:
True if the underlying cache contains corresponding data; false otherwise./**
	 * Determine whether the cache contains data for the given collection.
	 * <p/>
	 * The semantic here is whether the cache contains data visible for the
	 * current call context.
	 *
	 * @param role The name of the collection role (in form
	 * [owner-entity-name].[collection-property-name]) whose regions should be
	 * evicted.
	 * @param ownerIdentifier The identifier of the owning entity
	 *
	 * @return True if the underlying cache contains corresponding data; false otherwise.
	 */
	@SuppressWarnings( {"UnusedDeclaration"})
	boolean containsCollection(String role, Serializable ownerIdentifier);


	
Evicts the cache data for the given identified collection "instance"
Params:
role – The "collection role" (in form [owner-entity-name].[collection-property-name]).
ownerIdentifier – The identifier of the owning entity
Since:
5.3/**
	 * Evicts the cache data for the given identified collection "instance"
	 *
	 * @param role The "collection role" (in form [owner-entity-name].[collection-property-name]).
	 * @param ownerIdentifier The identifier of the owning entity
	 *
	 * @since 5.3
	 */
	void evictCollectionData(String role, Serializable ownerIdentifier);

	
Evicts cached data for the given collection role
Params:
role – The "collection role" (in form [owner-entity-name].[collection-property-name]).
Since:
5.3/**
	 * Evicts cached data for the given collection role
	 *
	 * @param role The "collection role" (in form [owner-entity-name].[collection-property-name]).
	 *
	 * @since 5.3
	 */
	void evictCollectionData(String role);

	
Evict cache data for all collections
Since:
5.3/**
	 * Evict cache data for all collections
	 *
	 * @since 5.3
	 */
	void evictCollectionData();




	// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	// Query result data

	
Determine whether the cache contains data for the given query.

The semantic here is whether the cache contains any data for the given
region name since query result caches are not transactionally isolated.
Params:
regionName – The cache name given to the query.
Returns:
True if the underlying cache contains corresponding data; false otherwise./**
	 * Determine whether the cache contains data for the given query.
	 * <p/>
	 * The semantic here is whether the cache contains any data for the given
	 * region name since query result caches are not transactionally isolated.
	 *
	 * @param regionName The cache name given to the query.
	 *
	 * @return True if the underlying cache contains corresponding data; false otherwise.
	 */
	boolean containsQuery(String regionName);

	
Evicts all cached query results from the default region.
/**
	 * Evicts all cached query results from the default region.
	 */
	void evictDefaultQueryRegion();

	
Evicts all cached query results under the given name.
Params:
regionName – The cache name associated to the queries being cached./**
	 * Evicts all cached query results under the given name.
	 *
	 * @param regionName The cache name associated to the queries being cached.
	 */
	void evictQueryRegion(String regionName);

	
Evict data from all query regions.
/**
	 * Evict data from all query regions.
	 */
	void evictQueryRegions();



	// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	// Misc

	
Evict all data from the named cache region
Since:
5.3/**
	 * Evict all data from the named cache region
	 *
	 * @since 5.3
	 */
	void evictRegion(String regionName);

	
{@inheritDoc}
API Note:
Hibernate impl - we only evict entity data here in keeping with the JPA intent (JPA only defines caching for entity data). For evicting all cache regions (collections, natural-ids and query results), use evictAllRegions instead./**
	 * {@inheritDoc}
	 *
	 * @apiNote Hibernate impl - we only evict entity data here in keeping
	 * with the JPA intent (JPA only defines caching for entity data).  For
	 * evicting all cache regions (collections, natural-ids and query results),
	 * use {@link #evictAllRegions} instead.
	 */
	@Override
	default void evictAll() {
		// Evict only the "JPA cache", which is purely defined as the entity regions.
		evictEntityData();
	}

	
Evict data from all cache regions.
/**
	 * Evict data from all cache regions.
	 */
	default void evictAllRegions() {
		evictEntityData();
		evictNaturalIdData();
		evictCollectionData();
		evictDefaultQueryRegion();
		evictQueryRegions();
	}



	// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	// Deprecations (5.3)

	
Evicts the entity data for a particular entity "instance".
Params:
entityClass – The entity class.
identifier – The entity identifier
Deprecated:
Use evictEntityData(Class, Serializable) instead/**
	 * Evicts the entity data for a particular entity "instance".
	 *
	 * @param entityClass The entity class.
	 * @param identifier The entity identifier
	 *
	 * @deprecated Use {@link Cache#evictEntityData(Class, Serializable)} instead
	 */
	@Deprecated
	default void evictEntity(Class entityClass, Serializable identifier) {
		evictEntityData( entityClass, identifier );
	}

	
Evicts the entity data for a particular entity "instance".
Params:
entityName – The entity name.
identifier – The entity identifier
Deprecated:
Use evictEntityData(String, Serializable) instead/**
	 * Evicts the entity data for a particular entity "instance".
	 *
	 * @param entityName The entity name.
	 * @param identifier The entity identifier
	 *
	 * @deprecated Use {@link Cache#evictEntityData(String, Serializable)} instead
	 */
	@Deprecated
	default void evictEntity(String entityName, Serializable identifier) {
		evictEntityData( entityName, identifier );
	}

	
Evicts all entity data from the given region (i.e. for all entities of
type).
Params:
entityClass – The entity class.
Deprecated:
Use evictEntityData(Class) instead/**
	 * Evicts all entity data from the given region (i.e. for all entities of
	 * type).
	 *
	 * @param entityClass The entity class.
	 *
	 * @deprecated Use {@link Cache#evictEntityData(Class)} instead
	 */
	@Deprecated
	default void evictEntityRegion(Class entityClass) {
		evictEntityData( entityClass );
	}

	
Evicts all entity data from the given region (i.e. for all entities of
type).
Params:
entityName – The entity name.
Deprecated:
Use evictEntityData(String) instead/**
	 * Evicts all entity data from the given region (i.e. for all entities of
	 * type).
	 *
	 * @param entityName The entity name.
	 *
	 * @deprecated Use {@link Cache#evictEntityData(String)} instead
	 */
	@Deprecated
	default void evictEntityRegion(String entityName) {
		evictEntityData( entityName );
	}

	
Evict data from all entity regions.
Deprecated:
Use evictEntityData() instead/**
	 * Evict data from all entity regions.
	 *
	 * @deprecated Use {@link Cache#evictEntityData()} instead
	 */
	@Deprecated
	default void evictEntityRegions() {
		evictEntityData();
	}

	
Evicts all naturalId data from the given region (i.e. for all entities of
type).
Params:
entityClass – The entity class.
Deprecated:
Use evictNaturalIdData(Class) instead/**
	 * Evicts all naturalId data from the given region (i.e. for all entities of
	 * type).
	 *
	 * @param entityClass The entity class.
	 *
	 * @deprecated Use {@link Cache#evictNaturalIdData(Class)} instead
	 */
	@Deprecated
	default void evictNaturalIdRegion(Class entityClass) {
		evictNaturalIdData( entityClass );
	}

	
Evicts all naturalId data from the given region (i.e. for all entities of
type).
Params:
entityName – The entity name.
Deprecated:
Use evictNaturalIdData(String) instead/**
	 * Evicts all naturalId data from the given region (i.e. for all entities of
	 * type).
	 *
	 * @param entityName The entity name.
	 *
	 * @deprecated Use {@link Cache#evictNaturalIdData(String)} instead
	 */
	@Deprecated
	default void evictNaturalIdRegion(String entityName) {
		evictNaturalIdData( entityName );
	}

	
Evict data from all naturalId regions.
Deprecated:
Use evictNaturalIdData() instead/**
	 * Evict data from all naturalId regions.
	 *
	 * @deprecated Use {@link Cache#evictNaturalIdData()} instead
	 */
	@Deprecated
	default void evictNaturalIdRegions() {
		evictNaturalIdData();
	}

	
Evicts the cache data for the given identified collection instance.
Params:
role – The "collection role" (in form [owner-entity-name].[collection-property-name]).
ownerIdentifier – The identifier of the owning entity
Deprecated:
Use evictCollectionData(String, Serializable) instead/**
	 * Evicts the cache data for the given identified collection instance.
	 *
	 * @param role The "collection role" (in form [owner-entity-name].[collection-property-name]).
	 * @param ownerIdentifier The identifier of the owning entity
	 *
	 * @deprecated Use {@link Cache#evictCollectionData(String, Serializable)} instead
	 */
	@Deprecated
	default void evictCollection(String role, Serializable ownerIdentifier) {
		evictCollectionData( role, ownerIdentifier );
	}

	
Evicts all entity data from the given region (i.e. evicts cached data
for all of the specified collection role).
Params:
role – The "collection role" (in form [owner-entity-name].[collection-property-name]).
Deprecated:
Use evictCollectionData(String) instead/**
	 * Evicts all entity data from the given region (i.e. evicts cached data
	 * for all of the specified collection role).
	 *
	 * @param role The "collection role" (in form [owner-entity-name].[collection-property-name]).
	 *
	 * @deprecated Use {@link Cache#evictCollectionData(String)} instead
	 */
	@Deprecated
	default void evictCollectionRegion(String role) {
		evictCollectionData( role );
	}

	
Evict data from all collection regions.
Deprecated:
Use evictCollectionData() instead/**
	 * Evict data from all collection regions.
	 *
	 * @deprecated Use {@link Cache#evictCollectionData()} instead
	 */
	@Deprecated
	default void evictCollectionRegions() {
		evictCollectionData();
	}

}