/*

  * 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;

 import java.lang.ref.ReferenceQueue;

 import java.util.AbstractMap;

 import java.util.Collection;

 import java.util.HashMap;

 import java.util.Hashtable;

 import java.util.Map;

 import java.util.Set;

 import java.util.concurrent.ConcurrentHashMap;

 import java.util.concurrent.ConcurrentMap;

 /**

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

  *

  * <p>Thread-safety of this class will depend on the selected implementation

  * for the internal map. If the convenience constructors are used, resulting

  * instances will be thread-safe, unless a concurrency level of -1 (or less)

  * is specified.</p>

  *

  * @author Rodrigo Ruiz

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

  * @param <V> the type of cached values

  */

 public abstract class BaseCache<K, V> extends AbstractMap<K, V>

   implements Cache<K, V> {

   /**

    * The map containing the cached values.

    */

   private final Map<K, KeyedReference<K, V>> cache;

   /**

    * Queue used to collect unused keys.

    */

   private final ReferenceQueue<V> queue;

   /**

    * <p>Creates an instance with custom capacity and concurrency level.</p>

    *

    * <p>The concurrency level is used as a hint to select the internal Map

    * implementation:</p>

    *

    * <ul>

    *   <li>&lt; 0 : Do not care about concurrency.

    *                A {@link java.util.HashMap} will be used.</li>

    *   <li>= 0    : No concurrent access allowed.

    *                A {@link java.util.Hashtable} will be selected.</li>

    *   <li>&gt; 0 : A {@link java.util.concurrent.ConcurrentHashMap} will be

    *                created with the specified concurrency level.</li>

    * </ul>

    *

    * @param initCapacity     The map initial capacity

    * @param loadFactor       The map load factor

    * @param concurrencyLevel The concurrency level.

    */

   public BaseCache(int initCapacity, float loadFactor, int concurrencyLevel) {

     if (concurrencyLevel < 0) {

       this.cache

         = new Hashtable<K, KeyedReference<K, V>>(initCapacity, loadFactor);

     } else if (concurrencyLevel == 0) {

       this.cache

         = new HashMap<K, KeyedReference<K, V>>(initCapacity, loadFactor);

     } else {

       this.cache = new ConcurrentHashMap<K, KeyedReference<K, V>>(

         initCapacity, loadFactor, concurrencyLevel);

     }

     this.queue = new ReferenceQueue<V>();

   }

   /**

    * <p>Advanced constructor.</p>

    *

    * With this constructor, the programmer can specify the Map to be used

    * to hold the values. Useful for those cases in which the default

    * implementations do not have the correct performance profile.

    *

    * @param map The map to use internally

    */

   public BaseCache(Map<K, KeyedReference<K, V>> map) {

     this.cache = map;

     this.queue = new ReferenceQueue<V>();

   }

   /**

    * {@inheritDoc}

    */

   @Override public final V get(Object key) {

     KeyedReference<K, V> ref = (KeyedReference<K, V>)cache.get(key);

     return (ref == null) ? null : ref.get();

   }

   /**

    * {@inheritDoc}

    */

   @Override public final V put(K key, V value) {

     purge();

     KeyedReference<K, V> ref;

     if (this.cache instanceof ConcurrentMap) {

       ConcurrentMap<K, KeyedReference<K, V>> cmap

         = (ConcurrentMap<K, KeyedReference<K, V>>)this.cache;

       ref = cmap.putIfAbsent(key, createRef(key, value, queue));

     } else {

       ref = cache.get(key);

       if (ref == null) {

         ref = cache.put(key, createRef(key, value, queue));

       }

     }

     return (ref == null) ? null : ref.get();

   }

   /**

    * {@inheritDoc}

    */

   @Override public final V remove(Object key) {

     purge();

     KeyedReference<K, V> ref = cache.remove(key);

     return (ref == null) ? null : ref.get();

   }

   /**

    * {@inheritDoc}

    */

   @Override public final int size() {

     purge();

     return cache.size();

   }

   /**

    * {@inheritDoc}

    */

   @Override public final void clear() {

     purge();

     cache.clear();

   }

   /**

    * {@inheritDoc}

    */

   @Override public final Set<Entry<K, V>> entrySet() {

     throw new UnsupportedOperationException();

   }

   /**

    * {@inheritDoc}

    */

   @Override public final Collection<V> values() {

     throw new UnsupportedOperationException();

   }

   /**

    * {@inheritDoc}

    *

    * <p>The superclass implementation of this method relies on the

    * {@link BaseCache#entrySet} method, which always throws an exception. This

    * re-implementation removes the issue.</p>

    */

   @Override public final int hashCode() {

     return System.identityHashCode(this);

   }

   /**

    * {@inheritDoc}

    *

    * <p>Cache instances are always different by nature, even if they contain

    * exactly the same entries.</p>

    */

   @Override public final boolean equals(Object obj) {

     return obj == this;

   }

   /**

    * Factory method for creating a new reference instance.

    *

    * @param key    The key

    * @param value  The value

    * @param rqueue A reference queue

    * @return A reference instance containing the key and value

    */

   protected abstract KeyedReference<K, V> createRef(K key, V value,

     ReferenceQueue<V> rqueue);

   /**

    * <p>Removes keys for References that have been enqueued.</p>

    *

    * <p>This method is not public because applications should never need to

    * manually purge the cache. However, it is left protected to allow invocation

    * from tests.</p>

    *

    * <p>This method is synchronised because {@link java.lang.ref.ReferenceQueue}

    * is not thread-safe.</p>

    */

   @SuppressWarnings("unchecked")

   protected final synchronized void purge() {

     KeyedReference<K, V> ref = (KeyedReference<K, V>)queue.poll();

     while (ref != null) {

       K key = ref.getKey();

       cache.remove(key);

       ref = (KeyedReference<K, V>)queue.poll();

     }

   }

 }