1// GenericsNote: Converted.
2/*
3 *  Copyright 2002-2004 The Apache Software Foundation
4 *
5 *  Licensed under the Apache License, Version 2.0 (the "License");
6 *  you may not use this file except in compliance with the License.
7 *  You may obtain a copy of the License at
8 *
9 *      http://www.apache.org/licenses/LICENSE-2.0
10 *
11 *  Unless required by applicable law or agreed to in writing, software
12 *  distributed under the License is distributed on an "AS IS" BASIS,
13 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 *  See the License for the specific language governing permissions and
15 *  limitations under the License.
16 */
17package org.jivesoftware.smack.util.collections;
18
19import java.io.IOException;
20import java.io.ObjectInputStream;
21import java.io.ObjectOutputStream;
22import java.io.Serializable;
23
24/**
25 * A <code>Map</code> implementation that allows mappings to be
26 * removed by the garbage collector.
27 * <p/>
28 * When you construct a <code>ReferenceMap</code>, you can specify what kind
29 * of references are used to store the map's keys and values.
30 * If non-hard references are used, then the garbage collector can remove
31 * mappings if a key or value becomes unreachable, or if the JVM's memory is
32 * running low. For information on how the different reference types behave,
33 * see {@link java.lang.ref.Reference}.
34 * <p/>
35 * Different types of references can be specified for keys and values.
36 * The keys can be configured to be weak but the values hard,
37 * in which case this class will behave like a
38 * <a href="http://java.sun.com/j2se/1.4/docs/api/java/util/WeakHashMap.html">
39 * <code>WeakHashMap</code></a>. However, you can also specify hard keys and
40 * weak values, or any other combination. The default constructor uses
41 * hard keys and soft values, providing a memory-sensitive cache.
42 * <p/>
43 * This map is similar to ReferenceIdentityMap.
44 * It differs in that keys and values in this class are compared using <code>equals()</code>.
45 * <p/>
46 * This {@link java.util.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 * @author Paul Jack
62 * @author Matt Hall, John Watkinson, Stephen Colebourne
63 * @version $Revision: 1.1 $ $Date: 2005/10/11 17:05:32 $
64 * @see java.lang.ref.Reference
65 * @since Commons Collections 3.0 (previously in main package v2.1)
66 */
67public class ReferenceMap <K,V> extends AbstractReferenceMap<K, V> implements Serializable {
68
69    /**
70     * Serialization version
71     */
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, float loadFactor, boolean purgeValues) {
141        super(keyType, valueType, capacity, loadFactor, purgeValues);
142    }
143
144    //-----------------------------------------------------------------------
145    /**
146     * Write the map out using a custom routine.
147     */
148    private void writeObject(ObjectOutputStream out) throws IOException {
149        out.defaultWriteObject();
150        doWriteObject(out);
151    }
152
153    /**
154     * Read the map in using a custom routine.
155     */
156    private void readObject(ObjectInputStream in) throws IOException, ClassNotFoundException {
157        in.defaultReadObject();
158        doReadObject(in);
159    }
160
161}
162