1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. 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 */
17 package org.apache.commons.collections.map;
18
19 import java.io.IOException;
20 import java.io.ObjectInputStream;
21 import java.io.ObjectOutputStream;
22 import 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 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
44 * {@link org.apache.commons.collections.map.ReferenceIdentityMap ReferenceIdentityMap}.
45 * It differs in that keys and values in this class are compared using <code>equals()</code>.
46 * <p>
47 * This {@link java.util.Map Map} implementation does <i>not</i> allow null elements.
48 * Attempting to add a null key or value to the map will raise a <code>NullPointerException</code>.
49 * <p>
50 * This implementation is not synchronized.
51 * You can use {@link java.util.Collections#synchronizedMap} to
52 * provide synchronized access to a <code>ReferenceMap</code>.
53 * Remember that synchronization will not stop the garbage collecter removing entries.
54 * <p>
55 * All the available iterators can be reset back to the start by casting to
56 * <code>ResettableIterator</code> and calling <code>reset()</code>.
57 * <p>
58 * <strong>Note that ReferenceMap is not synchronized and is not thread-safe.</strong>
59 * If you wish to use this map from multiple threads concurrently, you must use
60 * appropriate synchronization. The simplest approach is to wrap this map
61 * using {@link java.util.Collections#synchronizedMap}. This class may throw
62 * exceptions when accessed by concurrent threads without synchronization.
63 * <p>
64 * NOTE: As from Commons Collections 3.1 this map extends <code>AbstractReferenceMap</code>
65 * (previously it extended AbstractMap). As a result, the implementation is now
66 * extensible and provides a <code>MapIterator</code>.
67 *
68 * @see java.lang.ref.Reference
69 *
70 * @since 3.0 (previously in main package v2.1)
71 * @version $Id: ReferenceMap.java 1429905 2013-01-07 17:15:14Z ggregory $
72 */
73 public class ReferenceMap<K, V> extends AbstractReferenceMap<K, V> implements Serializable {
74
75 /** Serialization version */
76 private static final long serialVersionUID = 1555089888138299607L;
77
78 /**
79 * Constructs a new <code>ReferenceMap</code> that will
80 * use hard references to keys and soft references to values.
81 */
82 public ReferenceMap() {
83 super(ReferenceStrength.HARD, ReferenceStrength.SOFT, DEFAULT_CAPACITY,
84 DEFAULT_LOAD_FACTOR, false);
85 }
86
87 /**
88 * Constructs a new <code>ReferenceMap</code> that will
89 * use the specified types of references.
90 *
91 * @param keyType the type of reference to use for keys;
92 * must be {@link AbstractReferenceMap.ReferenceStrength#HARD HARD},
93 * {@link AbstractReferenceMap.ReferenceStrength#SOFT SOFT},
94 * {@link AbstractReferenceMap.ReferenceStrength#WEAK WEAK}
95 * @param valueType the type of reference to use for values;
96 * must be {@link AbstractReferenceMap.ReferenceStrength#HARD HARD},
97 * {@link AbstractReferenceMap.ReferenceStrength#SOFT SOFT},
98 * {@link AbstractReferenceMap.ReferenceStrength#WEAK WEAK}
99 */
100 public ReferenceMap(final ReferenceStrength keyType, final ReferenceStrength valueType) {
101 super(keyType, valueType, DEFAULT_CAPACITY, DEFAULT_LOAD_FACTOR, false);
102 }
103
104 /**
105 * Constructs a new <code>ReferenceMap</code> that will
106 * use the specified types of references.
107 *
108 * @param keyType the type of reference to use for keys;
109 * must be {@link AbstractReferenceMap.ReferenceStrength#HARD HARD},
110 * {@link AbstractReferenceMap.ReferenceStrength#SOFT SOFT},
111 * {@link AbstractReferenceMap.ReferenceStrength#WEAK WEAK}
112 * @param valueType the type of reference to use for values;
113 * must be {@link AbstractReferenceMap.ReferenceStrength#HARD HARD},
114 * {@link AbstractReferenceMap.ReferenceStrength#SOFT SOFT},
115 * {@link AbstractReferenceMap.ReferenceStrength#WEAK WEAK}
116 * @param purgeValues should the value be automatically purged when the
117 * key is garbage collected
118 */
119 public ReferenceMap(final ReferenceStrength keyType, final ReferenceStrength valueType, final boolean purgeValues) {
120 super(keyType, valueType, DEFAULT_CAPACITY, DEFAULT_LOAD_FACTOR, purgeValues);
121 }
122
123 /**
124 * Constructs a new <code>ReferenceMap</code> with the
125 * specified reference types, load factor and initial
126 * capacity.
127 *
128 * @param keyType the type of reference to use for keys;
129 * must be {@link AbstractReferenceMap.ReferenceStrength#HARD HARD},
130 * {@link AbstractReferenceMap.ReferenceStrength#SOFT SOFT},
131 * {@link AbstractReferenceMap.ReferenceStrength#WEAK WEAK}
132 * @param valueType the type of reference to use for values;
133 * must be {@link AbstractReferenceMap.ReferenceStrength#HARD HARD},
134 * {@link AbstractReferenceMap.ReferenceStrength#SOFT SOFT},
135 * {@link AbstractReferenceMap.ReferenceStrength#WEAK WEAK}
136 * @param capacity the initial capacity for the map
137 * @param loadFactor the load factor for the map
138 */
139 public ReferenceMap(final ReferenceStrength keyType, final ReferenceStrength valueType, final int capacity,
140 final float loadFactor) {
141 super(keyType, valueType, capacity, loadFactor, false);
142 }
143
144 /**
145 * Constructs a new <code>ReferenceMap</code> with the
146 * specified reference types, load factor and initial
147 * capacity.
148 *
149 * @param keyType the type of reference to use for keys;
150 * must be {@link AbstractReferenceMap.ReferenceStrength#HARD HARD},
151 * {@link AbstractReferenceMap.ReferenceStrength#SOFT SOFT},
152 * {@link AbstractReferenceMap.ReferenceStrength#WEAK WEAK}
153 * @param valueType the type of reference to use for values;
154 * must be {@link AbstractReferenceMap.ReferenceStrength#HARD HARD},
155 * {@link AbstractReferenceMap.ReferenceStrength#SOFT SOFT},
156 * {@link AbstractReferenceMap.ReferenceStrength#WEAK WEAK}
157 * @param capacity the initial capacity for the map
158 * @param loadFactor the load factor for the map
159 * @param purgeValues should the value be automatically purged when the
160 * key is garbage collected
161 */
162 public ReferenceMap(final ReferenceStrength keyType, final ReferenceStrength valueType, final int capacity,
163 final float loadFactor, final boolean purgeValues) {
164 super(keyType, valueType, capacity, loadFactor, purgeValues);
165 }
166
167 //-----------------------------------------------------------------------
168 /**
169 * Write the map out using a custom routine.
170 */
171 private void writeObject(final ObjectOutputStream out) throws IOException {
172 out.defaultWriteObject();
173 doWriteObject(out);
174 }
175
176 /**
177 * Read the map in using a custom routine.
178 */
179 private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {
180 in.defaultReadObject();
181 doReadObject(in);
182 }
183
184 }