1. /*

  2.  *  Copyright 2002-2004 The Apache Software Foundation

  3.  *

  4.  *  Licensed under the Apache License, Version 2.0 (the "License");

  5.  *  you may not use this file except in compliance with the License.

  6.  *  You may obtain a copy of the License at

  7.  *

  8.  *      http://www.apache.org/licenses/LICENSE-2.0

  9.  *

  10.  *  Unless required by applicable law or agreed to in writing, software

  11.  *  distributed under the License is distributed on an "AS IS" BASIS,

  12.  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

  13.  *  See the License for the specific language governing permissions and

  14.  *  limitations under the License.

  15.  */

  16. package org.apache.commons.collections.map;

  17. 

  18. import java.io.IOException;

  19. import java.io.ObjectInputStream;

  20. import java.io.ObjectOutputStream;

  21. import java.io.Serializable;

  22. 

  23. /**

  24.  * A <code>Map</code> implementation that allows mappings to be

  25.  * removed by the garbage collector.

  26.  * <p>

  27.  * When you construct a <code>ReferenceMap</code>, you can specify what kind

  28.  * of references are used to store the map's keys and values.

  29.  * If non-hard references are used, then the garbage collector can remove

  30.  * mappings if a key or value becomes unreachable, or if the JVM's memory is

  31.  * running low. For information on how the different reference types behave,

  32.  * see {@link Reference}.

  33.  * <p>

  34.  * Different types of references can be specified for keys and values.

  35.  * The keys can be configured to be weak but the values hard,

  36.  * in which case this class will behave like a

  37.  * <a href="http://java.sun.com/j2se/1.4/docs/api/java/util/WeakHashMap.html">

  38.  * <code>WeakHashMap</code></a>. However, you can also specify hard keys and

  39.  * weak values, or any other combination. The default constructor uses

  40.  * hard keys and soft values, providing a memory-sensitive cache.

  41.  * <p>

  42.  * This map is similar to

  43.  * {@link org.apache.commons.collections.map.ReferenceIdentityMap ReferenceIdentityMap}.

  44.  * It differs in that keys and values in this class are compared using <code>equals()</code>.

  45.  * <p>

  46.  * This {@link Map} implementation does <i>not</i> allow null elements.

  47.  * Attempting to add a null key or value to the map will raise a <code>NullPointerException</code>.

  48.  * <p>

  49.  * This implementation is not synchronized.

  50.  * You can use {@link java.util.Collections#synchronizedMap} to 

  51.  * provide synchronized access to a <code>ReferenceMap</code>.

  52.  * Remember that synchronization will not stop the garbage collecter removing entries.

  53.  * <p>

  54.  * All the available iterators can be reset back to the start by casting to

  55.  * <code>ResettableIterator</code> and calling <code>reset()</code>.

  56.  * <p>

  57.  * NOTE: As from Commons Collections 3.1 this map extends <code>AbstractReferenceMap</code>

  58.  * (previously it extended AbstractMap). As a result, the implementation is now

  59.  * extensible and provides a <code>MapIterator</code>.

  60.  *

  61.  * @see java.lang.ref.Reference

  62.  * 

  63.  * @since Commons Collections 3.0 (previously in main package v2.1)

  64.  * @version $Revision: 1.13 $ $Date: 2004/04/27 21:35:23 $

  65.  * 

  66.  * @author Paul Jack

  67.  * @author Stephen Colebourne

  68.  */

  69. public class ReferenceMap extends AbstractReferenceMap implements Serializable {

  70. 

  71.     /** Serialization version */

  72.     private static final long serialVersionUID = 1555089888138299607L;

  73. 

  74.     /**

  75.      * Constructs a new <code>ReferenceMap</code> that will

  76.      * use hard references to keys and soft references to values.

  77.      */

  78.     public ReferenceMap() {

  79.         super(HARD, SOFT, DEFAULT_CAPACITY, DEFAULT_LOAD_FACTOR, false);

  80.     }

  81. 

  82.     /**

  83.      * Constructs a new <code>ReferenceMap</code> that will

  84.      * use the specified types of references.

  85.      *

  86.      * @param keyType  the type of reference to use for keys;

  87.      *   must be {@link #HARD}, {@link #SOFT}, {@link #WEAK}

  88.      * @param valueType  the type of reference to use for values;

  89.      *   must be {@link #HARD}, {@link #SOFT}, {@link #WEAK}

  90.      */

  91.     public ReferenceMap(int keyType, int valueType) {

  92.         super(keyType, valueType, DEFAULT_CAPACITY, DEFAULT_LOAD_FACTOR, false);

  93.     }

  94. 

  95.     /**

  96.      * Constructs a new <code>ReferenceMap</code> that will

  97.      * use the specified types of references.

  98.      *

  99.      * @param keyType  the type of reference to use for keys;

  100.      *   must be {@link #HARD}, {@link #SOFT}, {@link #WEAK}

  101.      * @param valueType  the type of reference to use for values;

  102.      *   must be {@link #HARD}, {@link #SOFT}, {@link #WEAK}

  103.      * @param purgeValues should the value be automatically purged when the 

  104.      *   key is garbage collected 

  105.      */

  106.     public ReferenceMap(int keyType, int valueType, boolean purgeValues) {

  107.         super(keyType, valueType, DEFAULT_CAPACITY, DEFAULT_LOAD_FACTOR, purgeValues);

  108.     }

  109. 

  110.     /**

  111.      * Constructs a new <code>ReferenceMap</code> with the

  112.      * specified reference types, load factor and initial

  113.      * capacity.

  114.      *

  115.      * @param keyType  the type of reference to use for keys;

  116.      *   must be {@link #HARD}, {@link #SOFT}, {@link #WEAK}

  117.      * @param valueType  the type of reference to use for values;

  118.      *   must be {@link #HARD}, {@link #SOFT}, {@link #WEAK}

  119.      * @param capacity  the initial capacity for the map

  120.      * @param loadFactor  the load factor for the map

  121.      */

  122.     public ReferenceMap(int keyType, int valueType, int capacity, float loadFactor) {

  123.         super(keyType, valueType, capacity, loadFactor, false);

  124.     }

  125. 

  126.     /**

  127.      * Constructs a new <code>ReferenceMap</code> with the

  128.      * specified reference types, load factor and initial

  129.      * capacity.

  130.      *

  131.      * @param keyType  the type of reference to use for keys;

  132.      *   must be {@link #HARD}, {@link #SOFT}, {@link #WEAK}

  133.      * @param valueType  the type of reference to use for values;

  134.      *   must be {@link #HARD}, {@link #SOFT}, {@link #WEAK}

  135.      * @param capacity  the initial capacity for the map

  136.      * @param loadFactor  the load factor for the map

  137.      * @param purgeValues  should the value be automatically purged when the 

  138.      *   key is garbage collected 

  139.      */

  140.     public ReferenceMap(int keyType, int valueType, int capacity,

  141.                         float loadFactor, boolean purgeValues) {

  142.         super(keyType, valueType, capacity, loadFactor, purgeValues);

  143.     }

  144. 

  145.     //-----------------------------------------------------------------------

  146.     /**

  147.      * Write the map out using a custom routine.

  148.      */

  149.     private void writeObject(ObjectOutputStream out) throws IOException {

  150.         out.defaultWriteObject();

  151.         doWriteObject(out);

  152.     }

  153. 

  154.     /**

  155.      * Read the map in using a custom routine.

  156.      */

  157.     private void readObject(ObjectInputStream in) throws IOException, ClassNotFoundException {

  158.         in.defaultReadObject();

  159.         doReadObject(in);

  160.     }

  161. 

  162. }