/*
 * Hibernate, Relational Persistence for Idiomatic Java
 *
 * Copyright (c) 2008-2011, Red Hat Inc. or third-party contributors as
 * indicated by the @author tags or express copyright attribution
 * statements applied by the authors.  All third-party contributions are
 * distributed under license by Red Hat Inc.
 *
 * This copyrighted material is made available to anyone wishing to use, modify,
 * copy, or redistribute it subject to the terms and conditions of the GNU
 * Lesser General Public License, as published by the Free Software Foundation.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
 * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License
 * for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this distribution; if not, write to:
 * Free Software Foundation, Inc.
 * 51 Franklin Street, Fifth Floor
 * Boston, MA  02110-1301  USA
 */
package org.hibernate.cache.spi;

import java.io.Serializable;
import java.util.List;
import java.util.Set;

import org.hibernate.HibernateException;
import org.hibernate.cache.CacheException;
import org.hibernate.engine.spi.SessionImplementor;
import org.hibernate.type.Type;

Defines the contract for caches capable of storing query results.  These
caches should only concern themselves with storing the matching result ids.
The transactional semantics are necessarily less strict than the semantics
of an item cache.
Author:
Gavin King/**
 * Defines the contract for caches capable of storing query results.  These
 * caches should only concern themselves with storing the matching result ids.
 * The transactional semantics are necessarily less strict than the semantics
 * of an item cache.
 * 
 * @author Gavin King
 */
public interface QueryCache {
	
Clear items from the query cache.
Throws:
CacheException – Indicates a problem delegating to the underlying cache./**
	 * Clear items from the query cache.
	 *
	 * @throws CacheException Indicates a problem delegating to the underlying cache.
	 */
	public void clear() throws CacheException;

	
Put a result into the query cache.
Params:
key – The cache key
returnTypes – The result types
result – The results to cache
isNaturalKeyLookup – Was this a natural id lookup?
session – The originating session
Throws:
HibernateException – Indicates a problem delegating to the underlying cache.
Returns:
Whether the put actually happened./**
	 * Put a result into the query cache.
	 *
	 * @param key The cache key
	 * @param returnTypes The result types
	 * @param result The results to cache
	 * @param isNaturalKeyLookup Was this a natural id lookup?
	 * @param session The originating session
	 *
	 * @return Whether the put actually happened.
	 *
	 * @throws HibernateException Indicates a problem delegating to the underlying cache.
	 */
	public boolean put(QueryKey key, Type[] returnTypes, List result, boolean isNaturalKeyLookup, SessionImplementor session) throws HibernateException;

	
Get results from the cache.
Params:
key – The cache key
returnTypes – The result types
isNaturalKeyLookup – Was this a natural id lookup?
spaces – The query spaces (used in invalidation plus validation checks)
session – The originating session
Throws:
HibernateException – Indicates a problem delegating to the underlying cache.
Returns:
The cached results; may be null./**
	 * Get results from the cache.
	 *
	 * @param key The cache key
	 * @param returnTypes The result types
	 * @param isNaturalKeyLookup Was this a natural id lookup?
	 * @param spaces The query spaces (used in invalidation plus validation checks)
	 * @param session The originating session
	 *
	 * @return The cached results; may be null.
	 *
	 * @throws HibernateException Indicates a problem delegating to the underlying cache.
	 */
	public List get(QueryKey key, Type[] returnTypes, boolean isNaturalKeyLookup, Set<Serializable> spaces, SessionImplementor session) throws HibernateException;

	
Destroy the cache.
/**
	 * Destroy the cache.
	 */
	public void destroy();

	
The underlying cache factory region being used.
Returns:
The cache region./**
	 * The underlying cache factory region being used.
	 *
	 * @return The cache region.
	 */
	public QueryResultsRegion getRegion();

}