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 import java.lang.ref.Reference; 24 25 /** 26 * A {@code Map} implementation that allows mappings to be 27 * removed by the garbage collector and matches keys and values based 28 * on {@code ==} not {@code equals()}. 29 * <p> 30 * When you construct a {@code ReferenceIdentityMap}, you can specify what kind 31 * of references are used to store the map's keys and values. 32 * If non-hard references are used, then the garbage collector can remove 33 * mappings if a key or value becomes unreachable, or if the JVM's memory is 34 * running low. For information on how the different reference types behave, 35 * see {@link Reference}. 36 * </p> 37 * <p> 38 * Different types of references can be specified for keys and values. 39 * The default constructor uses hard keys and soft values, providing a 40 * memory-sensitive cache. 41 * </p> 42 * <p> 43 * This map is similar to 44 * {@link org.apache.commons.collections4.map.ReferenceMap ReferenceMap}. 45 * It differs in that keys and values in this class are compared using {@code ==}. 46 * </p> 47 * <p> 48 * This map will violate the detail of various Map and map view contracts. 49 * As a general rule, don't compare this map to other maps. 50 * </p> 51 * <p> 52 * This {@link java.util.Map Map} implementation does <i>not</i> allow null elements. 53 * Attempting to add a null key or value to the map will raise a {@code NullPointerException}. 54 * </p> 55 * <p> 56 * This implementation is not synchronized. 57 * You can use {@link java.util.Collections#synchronizedMap} to 58 * provide synchronized access to a {@code ReferenceIdentityMap}. 59 * Remember that synchronization will not stop the garbage collector removing entries. 60 * </p> 61 * <p> 62 * All the available iterators can be reset back to the start by casting to 63 * {@code ResettableIterator} and calling {@code reset()}. 64 * </p> 65 * <p> 66 * <strong>Note that ReferenceIdentityMap is not synchronized and is not thread-safe.</strong> 67 * If you wish to use this map from multiple threads concurrently, you must use 68 * appropriate synchronization. The simplest approach is to wrap this map 69 * using {@link java.util.Collections#synchronizedMap}. This class may throw 70 * exceptions when accessed by concurrent threads without synchronization. 71 * </p> 72 * 73 * @param <K> the type of the keys in this map 74 * @param <V> the type of the values in this map 75 * 76 * @see java.lang.ref.Reference 77 * @since 3.0 (previously in main package v2.1) 78 */ 79 public class ReferenceIdentityMap<K, V> extends AbstractReferenceMap<K, V> implements Serializable { 80 81 /** Serialization version */ 82 private static final long serialVersionUID = -1266190134568365852L; 83 84 /** 85 * Constructs a new {@code ReferenceIdentityMap} that will 86 * use hard references to keys and soft references to values. 87 */ 88 public ReferenceIdentityMap() { 89 super(ReferenceStrength.HARD, ReferenceStrength.SOFT, DEFAULT_CAPACITY, 90 DEFAULT_LOAD_FACTOR, false); 91 } 92 93 /** 94 * Constructs a new {@code ReferenceIdentityMap} that will 95 * use the specified types of references. 96 * 97 * @param keyType the type of reference to use for keys; 98 * must be {@link AbstractReferenceMap.ReferenceStrength#HARD HARD}, 99 * {@link AbstractReferenceMap.ReferenceStrength#SOFT SOFT}, 100 * {@link AbstractReferenceMap.ReferenceStrength#WEAK WEAK} 101 * @param valueType the type of reference to use for values; 102 * must be {@link AbstractReferenceMap.ReferenceStrength#HARD HARD}, 103 * {@link AbstractReferenceMap.ReferenceStrength#SOFT SOFT}, 104 * {@link AbstractReferenceMap.ReferenceStrength#WEAK WEAK} 105 */ 106 public ReferenceIdentityMap(final ReferenceStrength keyType, final ReferenceStrength valueType) { 107 super(keyType, valueType, DEFAULT_CAPACITY, DEFAULT_LOAD_FACTOR, false); 108 } 109 110 /** 111 * Constructs a new {@code ReferenceIdentityMap} that will 112 * use the specified types of references. 113 * 114 * @param keyType the type of reference to use for keys; 115 * must be {@link AbstractReferenceMap.ReferenceStrength#HARD HARD}, 116 * {@link AbstractReferenceMap.ReferenceStrength#SOFT SOFT}, 117 * {@link AbstractReferenceMap.ReferenceStrength#WEAK WEAK} 118 * @param valueType the type of reference to use for values; 119 * must be {@link AbstractReferenceMap.ReferenceStrength#HARD HARD}, 120 * {@link AbstractReferenceMap.ReferenceStrength#SOFT SOFT}, 121 * {@link AbstractReferenceMap.ReferenceStrength#WEAK WEAK} 122 * @param purgeValues should the value be automatically purged when the 123 * key is garbage collected 124 */ 125 public ReferenceIdentityMap(final ReferenceStrength keyType, final ReferenceStrength valueType, 126 final boolean purgeValues) { 127 super(keyType, valueType, DEFAULT_CAPACITY, DEFAULT_LOAD_FACTOR, purgeValues); 128 } 129 130 /** 131 * Constructs a new {@code ReferenceIdentityMap} with the 132 * specified reference types, load factor and initial capacity. 133 * 134 * @param keyType the type of reference to use for keys; 135 * must be {@link AbstractReferenceMap.ReferenceStrength#HARD HARD}, 136 * {@link AbstractReferenceMap.ReferenceStrength#SOFT SOFT}, 137 * {@link AbstractReferenceMap.ReferenceStrength#WEAK WEAK} 138 * @param valueType the type of reference to use for values; 139 * must be {@link AbstractReferenceMap.ReferenceStrength#HARD HARD}, 140 * {@link AbstractReferenceMap.ReferenceStrength#SOFT SOFT}, 141 * {@link AbstractReferenceMap.ReferenceStrength#WEAK WEAK} 142 * @param capacity the initial capacity for the map 143 * @param loadFactor the load factor for the map 144 */ 145 public ReferenceIdentityMap(final ReferenceStrength keyType, final ReferenceStrength valueType, 146 final int capacity, final float loadFactor) { 147 super(keyType, valueType, capacity, loadFactor, false); 148 } 149 150 /** 151 * Constructs a new {@code ReferenceIdentityMap} with the 152 * specified reference types, load factor and initial capacity. 153 * 154 * @param keyType the type of reference to use for keys; 155 * must be {@link AbstractReferenceMap.ReferenceStrength#HARD HARD}, 156 * {@link AbstractReferenceMap.ReferenceStrength#SOFT SOFT}, 157 * {@link AbstractReferenceMap.ReferenceStrength#WEAK WEAK} 158 * @param valueType the type of reference to use for values; 159 * must be {@link AbstractReferenceMap.ReferenceStrength#HARD HARD}, 160 * {@link AbstractReferenceMap.ReferenceStrength#SOFT SOFT}, 161 * {@link AbstractReferenceMap.ReferenceStrength#WEAK WEAK} 162 * @param capacity the initial capacity for the map 163 * @param loadFactor the load factor for the map 164 * @param purgeValues should the value be automatically purged when the 165 * key is garbage collected 166 */ 167 public ReferenceIdentityMap(final ReferenceStrength keyType, final ReferenceStrength valueType, 168 final int capacity, final float loadFactor, final boolean purgeValues) { 169 super(keyType, valueType, capacity, loadFactor, purgeValues); 170 } 171 172 /** 173 * Gets the hash code for the key specified. 174 * <p> 175 * This implementation uses the identity hash code. 176 * 177 * @param key the key to get a hash code for 178 * @return the hash code 179 */ 180 @Override 181 protected int hash(final Object key) { 182 return System.identityHashCode(key); 183 } 184 185 /** 186 * Gets the hash code for a MapEntry. 187 * <p> 188 * This implementation uses the identity hash code. 189 * 190 * @param key the key to get a hash code for, may be null 191 * @param value the value to get a hash code for, may be null 192 * @return the hash code, as per the MapEntry specification 193 */ 194 @Override 195 protected int hashEntry(final Object key, final Object value) { 196 return System.identityHashCode(key) ^ 197 System.identityHashCode(value); 198 } 199 200 /** 201 * Compares two keys for equals. 202 * <p> 203 * This implementation converts the key from the entry to a real reference 204 * before comparison and uses {@code ==}. 205 * 206 * @param key1 the first key to compare passed in from outside 207 * @param key2 the second key extracted from the entry via {@code entry.key} 208 * @return true if equal by identity 209 */ 210 @Override 211 protected boolean isEqualKey(final Object key1, Object key2) { 212 key2 = isKeyType(ReferenceStrength.HARD) ? key2 : ((Reference<?>) key2).get(); 213 return key1 == key2; 214 } 215 216 /** 217 * Compares two values for equals. 218 * <p> 219 * This implementation uses {@code ==}. 220 * 221 * @param value1 the first value to compare passed in from outside 222 * @param value2 the second value extracted from the entry via {@code getValue()} 223 * @return true if equal by identity 224 */ 225 @Override 226 protected boolean isEqualValue(final Object value1, final Object value2) { 227 return value1 == value2; 228 } 229 230 /** 231 * Read the map in using a custom routine. 232 * 233 * @param in the input stream 234 * @throws IOException if an error occurs while reading from the stream 235 * @throws ClassNotFoundException if an object read from the stream can not be loaded 236 */ 237 private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException { 238 in.defaultReadObject(); 239 doReadObject(in); 240 } 241 242 /** 243 * Write the map out using a custom routine. 244 * 245 * @param out the output stream 246 * @throws IOException if an error occurs while writing to the stream 247 */ 248 private void writeObject(final ObjectOutputStream out) throws IOException { 249 out.defaultWriteObject(); 250 doWriteObject(out); 251 } 252 253 }