//$Id: CacheConcurrencyStrategy.java 9247 2006-02-09 20:48:43Z steveebersole $
package org.hibernate.cache;

import java.util.Comparator;

/**
 * Implementors manage transactional access to cached data. Transactions
 * pass in a timestamp indicating transaction start time. Two different
 * implementation patterns are provided for.<ul>
 * <li>A transaction-aware cache implementation might be wrapped by a
 * "synchronous" concurrency strategy, where updates to the cache are written
 * to the cache inside the transaction.</li>
 * <li>A non transaction-aware cache would be wrapped by an "asynchronous"
 * concurrency strategy, where items are merely "soft locked" during the 
 * transaction and then updated during the "after transaction completion"
 * phase; the soft lock is not an actual lock on the database row -
 * only upon the cached representation of the item.</li>
 * </ul>
 * <p/>
 * In terms of entity caches, the expected call sequences are: <ul>
 * <li><b>DELETES</b> : {@link #lock} -> {@link #evict} -> {@link #release}</li>
 * <li><b>UPDATES</b> : {@link #lock} -> {@link #update} -> {@link #afterUpdate}</li>
 * <li><b>INSERTS</b> : {@link #insert} -> {@link #afterInsert}</li>
 * </ul>
 * <p/>
 * In terms of collection caches, all modification actions actually just
 * invalidate the entry(s).  The call sequence here is:
 * {@link #lock} -> {@link #evict} -> {@link #release}
 * <p/>
 * Note that, for an asynchronous cache, cache invalidation must be a two 
 * step process (lock->release, or lock-afterUpdate), since this is the only 
 * way to guarantee consistency with the database for a nontransactional cache
 * implementation. For a synchronous cache, cache invalidation is a single 
 * step process (evict, or update). Hence, this interface defines a three
 * step process, to cater for both models.
 * <p/>
 * Note that query result caching does not go through a concurrency strategy; they
 * are managed directly against the underlying {@link Cache cache regions}.
 */
public interface CacheConcurrencyStrategy {

	/**
	 * Attempt to retrieve an object from the cache. Mainly used in attempting
	 * to resolve entities/collections from the second level cache.
	 *
	 * @param key
	 * @param txTimestamp a timestamp prior to the transaction start time
	 * @return the cached object or <tt>null</tt>
	 * @throws CacheException
	 */
	public Object get(Object key, long txTimestamp) throws CacheException;

	/**
	 * Attempt to cache an object, after loading from the database.
	 *
	 * @param key
	 * @param value
	 * @param txTimestamp a timestamp prior to the transaction start time
	 * @param version the item version number
	 * @param versionComparator a comparator used to compare version numbers
	 * @param minimalPut indicates that the cache should avoid a put is the item is already cached
	 * @return <tt>true</tt> if the object was successfully cached
	 * @throws CacheException
	 */
	public boolean put(
			Object key, 
			Object value, 
			long txTimestamp, 
			Object version, 
			Comparator versionComparator,
			boolean minimalPut) 
	throws CacheException;

	/**
	 * We are going to attempt to update/delete the keyed object. This
	 * method is used by "asynchronous" concurrency strategies.
	 * <p/>
	 * The returned object must be passed back to release(), to release the
	 * lock. Concurrency strategies which do not support client-visible
	 * locks may silently return null.
	 * 
	 * @param key
	 * @param version 
	 * @throws CacheException
	 */
	public SoftLock lock(Object key, Object version) throws CacheException;

	/**
	 * Called after an item has become stale (before the transaction completes).
	 * This method is used by "synchronous" concurrency strategies.
	 */
	public void evict(Object key) throws CacheException;

	/**
	 * Called after an item has been updated (before the transaction completes),
	 * instead of calling evict().
	 * This method is used by "synchronous" concurrency strategies.
	 */
	public boolean update(Object key, Object value, Object currentVersion, Object previousVersion) throws CacheException;

	/**
	 * Called after an item has been inserted (before the transaction completes),
	 * instead of calling evict().
	 * This method is used by "synchronous" concurrency strategies.
	 */
	public boolean insert(Object key, Object value, Object currentVersion) throws CacheException;
	
	
	/**
	 * Called when we have finished the attempted update/delete (which may or 
	 * may not have been successful), after transaction completion.
	 * This method is used by "asynchronous" concurrency strategies.
	 * @param key
	 * @throws CacheException
	 */
	public void release(Object key, SoftLock lock) throws CacheException;
	/**
	 * Called after an item has been updated (after the transaction completes),
	 * instead of calling release().
	 * This method is used by "asynchronous" concurrency strategies.
	 */
	public boolean afterUpdate(Object key, Object value, Object version, SoftLock lock) 
	throws CacheException;
	/**
	 * Called after an item has been inserted (after the transaction completes),
	 * instead of calling release().
	 * This method is used by "asynchronous" concurrency strategies.
	 */
	public boolean afterInsert(Object key, Object value, Object version) 
	throws CacheException;
	
	
	/**
	 * Evict an item from the cache immediately (without regard for transaction
	 * isolation).
	 * @param key
	 * @throws CacheException
	 */
	public void remove(Object key) throws CacheException;
	/**
	 * Evict all items from the cache immediately.
	 * @throws CacheException
	 */
	public void clear() throws CacheException;
	/**
	 * Clean up all resources.
	 */
	public void destroy();
	/**
	 * Set the underlying cache implementation.
	 * @param cache
	 */
	public void setCache(Cache cache);
	
	/**
	 * Marker interface, denoting a client-visible "soft lock"
	 * on a cached item.
	 * @author Gavin King
	 */
	public static interface SoftLock {}
		
	/**
	 * Get the cache region name
	 */
	public String getRegionName();
	
	/**
	 * Get the wrapped cache implementation
	 */
	public Cache getCache();
}