/*

  * RCache - A collection of simple reference-based cache implementations.

  * Copyright (C) 2007  Rodrigo Ruiz

  *

  * This library is free software; you can redistribute it and/or

  * modify it under the terms of the GNU Lesser General Public

  * License as published by the Free Software Foundation; either

  * version 2.1 of the License, or (at your option) any later version.

  *

  * This library 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 library; if not, write to the Free Software

  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA

  *

  * Alternatively, the contents of this file may be used under the terms

  * of the Apache 2.0 license (the "Apache License"), in which case its

  * provisions are applicable instead of those above. If you wish to allow use

  * of your version of this file only* under the terms of the Apache License

  * and not to allow others to use your version of this file under the LGPL,

  * indicate your decision by* deleting the provisions above and replace them

  * with the notice and other provisions required by the Apache License. If

  * you do not delete the provisions above, a recipient may use your version of

  * this file under either the LGPL or the Apache License.

  */

 package net.sourceforge.rcache;

 /**

  * <p>Memory-Sensitive Cache.</p>

  *

  * <p>Cache implementations will probably be implemented as Maps and so, this

  * interface is maintained "compatible" with {@link java.util.Map}. However,

  * in most situations, the Map interface is more complex than needed.</p>

  *

  * <p>This interface offers a simpler option, more oriented to the actual goals

  * of a Cache.</p>

  *

  * @author Rodrigo Ruiz

  * @param <K> the type of keys maintained by this cache

  * @param <V> the type of cached values

  */

 public interface Cache<K, V> {

   /**

    * <p>The operations defined in the Cache interface.</p>

    *

    * <p>This enumeration can be used for any method needing to

    * target a specific operation by name.</p>

    */

   enum Operation {

     /** get() operation. */

     GET,

     /** put() operation. */

     PUT,

     /** remove() operation. */

     REMOVE,

     /** clear() operation. */

     CLEAR

   };

   /**

    * Default cache initial capacity.

    */

   int DEFAULT_INITIAL_CAPACITY = 100;

   /**

    * Default cache load factor.

    */

   float DEFAULT_LOAD_FACTOR = 0.75f;

   /**

    * Default concurrency level. Appropriate for multiple readers and

    * a single writer.

    */

   int DEFAULT_CONCURRENCY_LEVEL = 1;

   /**

    * <p>Returns the value to which this cache maps the specified key.  Returns

    * <tt>null</tt> if the cache contains no entry for this key.  A return

    * value of <tt>null</tt> does not <i>necessarily</i> indicate that the

    * cache contains no entry for the key; it's also possible that the cache

    * explicitly maps the key to <tt>null</tt></p>.

    *

    * <p>Although this method should use <tt>K</tt> for the key type, it

    * is left as <tt>Object</tt> to keep this interface compatible with

    * {@link java.util.Map}.</p>

    *

    * @param key key whose associated value is to be returned.

    * @return the value to which this cache associates the specified key.

    */

   V get(Object key);

   /**

    * <p>Associates the specified value with the specified key in this cache,

    * but only if no value is associated yet. If the cache previously contained

    * an entry for this key, the old value is returned, but not replaced.</p>

    *

    * <p>This method is equivalent to the <tt>putIfAbsent</tt> from the

    * {@link java.util.concurrent.ConcurrentMap} class, as it is more

    * appropriate for a cache than the original one from {@link java.util.Map}.

    *

    * @param key key with which the specified value is to be associated.

    * @param value value to be associated with the specified key.

    *

    * @return the value associated with specified key. If the key was already

    *         associated with a value, the old value is returned. Otherwise,

    *         <tt>value</tt> is returned

    *

    * @throws ClassCastException if the class of the specified key or value

    *         prevents it from being stored in this cache.

    *

    * @throws IllegalArgumentException if some aspect of this key or value

    *         prevents it from being stored in this map.

    */

   V put(K key, V value);

   /**

    * <p>Removes the entry for this key from this cache if present.</p>

    *

    * <p>Although this method should use <tt>K</tt> for the key type, it

    * is left as <tt>Object</tt> to keep this interface compatible with

    * {@link java.util.Map}.</p>

    *

    * @param key key whose entry is to be removed from the cache.

    * @return previous value associated with specified key, or <tt>null</tt>

    *         if there was no entry for key.  (A <tt>null</tt> return can

    *         also indicate that the cache previously associated <tt>null</tt>

    *         with the specified key)

    */

   V remove(Object key);

   /**

    * <p>Removes all entries from this cache.</p>

    *

    * <p>This method must be handled very carefully, as it will break

    * the assumption of unique instances for cached factories.</p>

    */

   void clear();

 }