001/*
002 * Copyright (c) 2008, 2009, 2011 Oracle, Inc. All rights reserved.
003 *
004 * This program and the accompanying materials are made available under the
005 * terms of the Eclipse Public License v1.0 and Eclipse Distribution License v. 1.0
006 * which accompanies this distribution.  The Eclipse Public License is available
007 * at http://www.eclipse.org/legal/epl-v10.html and the Eclipse Distribution License
008 * is available at http://www.eclipse.org/org/documents/edl-v10.php.
009 */
010package javax.persistence;
011
012/**
013 * Interface used to interact with the second-level cache.
014 * If a cache is not in use, the methods of this interface have
015 * no effect, except for <code>contains</code>, which returns false.
016 *
017 * @since Java Persistence 2.0
018 */
019public interface Cache {
020
021  /**
022   * Whether the cache contains data for the given entity.
023   *
024   * @param cls        entity class
025   * @param primaryKey primary key
026   * @return boolean indicating whether the entity is in the cache
027   */
028  public boolean contains(Class cls, Object primaryKey);
029
030  /**
031   * Remove the data for the given entity from the cache.
032   *
033   * @param cls        entity class
034   * @param primaryKey primary key
035   */
036  public void evict(Class cls, Object primaryKey);
037
038  /**
039   * Remove the data for entities of the specified class (and its
040   * subclasses) from the cache.
041   *
042   * @param cls entity class
043   */
044  public void evict(Class cls);
045
046  /**
047   * Clear the cache.
048   */
049  public void evictAll();
050
051  /**
052   * Return an object of the specified type to allow access to the provider-specific API.
053   * <p>
054   * If the provider's Cache implementation does not support the specified class, the
055   * PersistenceException is thrown.
056   *
057   * @param cls the class of the object to be returned. This is normally either the
058   *            underlying Cache implementation class or an interface that it implements.
059   * @return an instance of the specified class
060   * @throws PersistenceException if the provider does not support the call
061   */
062  public <T> T unwrap(Class<T> cls);
063
064}