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.collections4.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} implementation that allows mappings to be 26 * removed by the garbage collector. 27 * <p> 28 * When you construct a {@code ReferenceMap}, 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 * <p> 36 * Different types of references can be specified for keys and values. 37 * The keys can be configured to be weak but the values hard, 38 * in which case this class will behave like a 39 * <a href="https://docs.oracle.com/javase/8/docs/api/java/util/WeakHashMap.html"> 40 * {@code WeakHashMap}</a>. However, you can also specify hard keys and 41 * weak values, or any other combination. The default constructor uses 42 * hard keys and soft values, providing a memory-sensitive cache. 43 * </p> 44 * <p> 45 * This map is similar to 46 * {@link org.apache.commons.collections4.map.ReferenceIdentityMap ReferenceIdentityMap}. 47 * It differs in that keys and values in this class are compared using {@code equals()}. 48 * </p> 49 * <p> 50 * This {@link java.util.Map Map} implementation does <i>not</i> allow null elements. 51 * Attempting to add a null key or value to the map will raise a {@code NullPointerException}. 52 * </p> 53 * <p> 54 * This implementation is not synchronized. 55 * You can use {@link java.util.Collections#synchronizedMap} to 56 * provide synchronized access to a {@code ReferenceMap}. 57 * Remember that synchronization will not stop the garbage collector removing entries. 58 * </p> 59 * <p> 60 * All the available iterators can be reset back to the start by casting to 61 * {@code ResettableIterator} and calling {@code reset()}. 62 * </p> 63 * <p> 64 * <strong>Note that ReferenceMap is not synchronized and is not thread-safe.</strong> 65 * If you wish to use this map from multiple threads concurrently, you must use 66 * appropriate synchronization. The simplest approach is to wrap this map 67 * using {@link java.util.Collections#synchronizedMap}. This class may throw 68 * exceptions when accessed by concurrent threads without synchronization. 69 * </p> 70 * <p> 71 * NOTE: As from Commons Collections 3.1 this map extends {@code AbstractReferenceMap} 72 * (previously it extended AbstractMap). As a result, the implementation is now 73 * extensible and provides a {@code MapIterator}. 74 * </p> 75 * 76 * @param <K> the type of the keys in the map 77 * @param <V> the type of the values in the map 78 * 79 * @see java.lang.ref.Reference 80 * @since 3.0 (previously in main package v2.1) 81 */ 82 public class ReferenceMap<K, V> extends AbstractReferenceMap<K, V> implements Serializable { 83 84 /** Serialization version */ 85 private static final long serialVersionUID = 1555089888138299607L; 86 87 /** 88 * Constructs a new {@code ReferenceMap} that will 89 * use hard references to keys and soft references to values. 90 */ 91 public ReferenceMap() { 92 super(ReferenceStrength.HARD, ReferenceStrength.SOFT, DEFAULT_CAPACITY, 93 DEFAULT_LOAD_FACTOR, false); 94 } 95 96 /** 97 * Constructs a new {@code ReferenceMap} that will 98 * use the specified types of references. 99 * 100 * @param keyType the type of reference to use for keys; 101 * must be {@link AbstractReferenceMap.ReferenceStrength#HARD HARD}, 102 * {@link AbstractReferenceMap.ReferenceStrength#SOFT SOFT}, 103 * {@link AbstractReferenceMap.ReferenceStrength#WEAK WEAK} 104 * @param valueType the type of reference to use for values; 105 * must be {@link AbstractReferenceMap.ReferenceStrength#HARD HARD}, 106 * {@link AbstractReferenceMap.ReferenceStrength#SOFT SOFT}, 107 * {@link AbstractReferenceMap.ReferenceStrength#WEAK WEAK} 108 */ 109 public ReferenceMap(final ReferenceStrength keyType, final ReferenceStrength valueType) { 110 super(keyType, valueType, DEFAULT_CAPACITY, DEFAULT_LOAD_FACTOR, false); 111 } 112 113 /** 114 * Constructs a new {@code ReferenceMap} that will 115 * use the specified types of references. 116 * 117 * @param keyType the type of reference to use for keys; 118 * must be {@link AbstractReferenceMap.ReferenceStrength#HARD HARD}, 119 * {@link AbstractReferenceMap.ReferenceStrength#SOFT SOFT}, 120 * {@link AbstractReferenceMap.ReferenceStrength#WEAK WEAK} 121 * @param valueType the type of reference to use for values; 122 * must be {@link AbstractReferenceMap.ReferenceStrength#HARD HARD}, 123 * {@link AbstractReferenceMap.ReferenceStrength#SOFT SOFT}, 124 * {@link AbstractReferenceMap.ReferenceStrength#WEAK WEAK} 125 * @param purgeValues should the value be automatically purged when the 126 * key is garbage collected 127 */ 128 public ReferenceMap(final ReferenceStrength keyType, final ReferenceStrength valueType, final boolean purgeValues) { 129 super(keyType, valueType, DEFAULT_CAPACITY, DEFAULT_LOAD_FACTOR, purgeValues); 130 } 131 132 /** 133 * Constructs a new {@code ReferenceMap} with the 134 * specified reference types, load factor and initial 135 * capacity. 136 * 137 * @param keyType the type of reference to use for keys; 138 * must be {@link AbstractReferenceMap.ReferenceStrength#HARD HARD}, 139 * {@link AbstractReferenceMap.ReferenceStrength#SOFT SOFT}, 140 * {@link AbstractReferenceMap.ReferenceStrength#WEAK WEAK} 141 * @param valueType the type of reference to use for values; 142 * must be {@link AbstractReferenceMap.ReferenceStrength#HARD HARD}, 143 * {@link AbstractReferenceMap.ReferenceStrength#SOFT SOFT}, 144 * {@link AbstractReferenceMap.ReferenceStrength#WEAK WEAK} 145 * @param capacity the initial capacity for the map 146 * @param loadFactor the load factor for the map 147 */ 148 public ReferenceMap(final ReferenceStrength keyType, final ReferenceStrength valueType, final int capacity, 149 final float loadFactor) { 150 super(keyType, valueType, capacity, loadFactor, false); 151 } 152 153 /** 154 * Constructs a new {@code ReferenceMap} with the 155 * specified reference types, load factor and initial 156 * capacity. 157 * 158 * @param keyType the type of reference to use for keys; 159 * must be {@link AbstractReferenceMap.ReferenceStrength#HARD HARD}, 160 * {@link AbstractReferenceMap.ReferenceStrength#SOFT SOFT}, 161 * {@link AbstractReferenceMap.ReferenceStrength#WEAK WEAK} 162 * @param valueType the type of reference to use for values; 163 * must be {@link AbstractReferenceMap.ReferenceStrength#HARD HARD}, 164 * {@link AbstractReferenceMap.ReferenceStrength#SOFT SOFT}, 165 * {@link AbstractReferenceMap.ReferenceStrength#WEAK WEAK} 166 * @param capacity the initial capacity for the map 167 * @param loadFactor the load factor for the map 168 * @param purgeValues should the value be automatically purged when the 169 * key is garbage collected 170 */ 171 public ReferenceMap(final ReferenceStrength keyType, final ReferenceStrength valueType, final int capacity, 172 final float loadFactor, final boolean purgeValues) { 173 super(keyType, valueType, capacity, loadFactor, purgeValues); 174 } 175 176 /** 177 * Read the map in using a custom routine. 178 * 179 * @param in the input stream 180 * @throws IOException if an error occurs while reading from the stream 181 * @throws ClassNotFoundException if an object read from the stream can not be loaded 182 */ 183 private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException { 184 in.defaultReadObject(); 185 doReadObject(in); 186 } 187 188 /** 189 * Write the map out using a custom routine. 190 * 191 * @param out the output stream 192 * @throws IOException if an error occurs while writing to the stream 193 */ 194 private void writeObject(final ObjectOutputStream out) throws IOException { 195 out.defaultWriteObject(); 196 doWriteObject(out); 197 } 198 199 }