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.keyvalue; 18 19 import java.io.Serializable; 20 import java.lang.reflect.Array; 21 import java.util.Arrays; 22 import java.util.Objects; 23 24 /** 25 * A {@code MultiKey} allows multiple map keys to be merged together. 26 * <p> 27 * The purpose of this class is to avoid the need to write code to handle 28 * maps of maps. An example might be the need to look up a file name by 29 * key and locale. The typical solution might be nested maps. This class 30 * can be used instead by creating an instance passing in the key and locale. 31 * </p> 32 * <p> 33 * Example usage: 34 * </p> 35 * <pre> 36 * // populate map with data mapping key+locale to localizedText 37 * Map map = new HashMap(); 38 * MultiKey multiKey = new MultiKey(key, locale); 39 * map.put(multiKey, localizedText); 40 * 41 * // later retrieve the localized text 42 * MultiKey multiKey = new MultiKey(key, locale); 43 * String localizedText = (String) map.get(multiKey); 44 * </pre> 45 * 46 * @param <K> the type of keys 47 * @since 3.0 48 */ 49 public class MultiKey<K> implements Serializable { 50 // This class could implement List, but that would confuse its purpose 51 52 /** Serialisation version */ 53 private static final long serialVersionUID = 4465448607415788805L; 54 55 @SuppressWarnings("unchecked") 56 private static <T> Class<? extends T> getClass(final T value) { 57 return (Class<? extends T>) (value == null ? Object.class : value.getClass()); 58 } 59 60 private static <T> Class<? extends T> getComponentType(final T... values) { 61 @SuppressWarnings("unchecked") 62 final Class<? extends T> rootClass = (Class<? extends T>) Object.class; 63 if (values == null) { 64 return rootClass; 65 } 66 Class<? extends T> prevClass = values.length > 0 ? getClass(values[0]) : rootClass; 67 for (int i = 1; i < values.length; i++) { 68 final Class<? extends T> classI = getClass(values[i]); 69 if (prevClass != classI) { 70 return rootClass; 71 } 72 prevClass = classI; 73 } 74 return prevClass; 75 } 76 77 private static <T> T[] newArray(final T key1, final T key2) { 78 @SuppressWarnings("unchecked") 79 final T[] array = (T[]) Array.newInstance(getComponentType(key1, key2), 2); 80 array[0] = key1; 81 array[1] = key2; 82 return array; 83 } 84 85 private static <T> T[] newArray(final T key1, final T key2, final T key3) { 86 @SuppressWarnings("unchecked") 87 final T[] array = (T[]) Array.newInstance(getComponentType(key1, key2, key3), 3); 88 array[0] = key1; 89 array[1] = key2; 90 array[2] = key3; 91 return array; 92 } 93 94 private static <T> T[] newArray(final T key1, final T key2, final T key3, final T key4) { 95 @SuppressWarnings("unchecked") 96 final T[] array = (T[]) Array.newInstance(getComponentType(key1, key2, key3, key4), 4); 97 array[0] = key1; 98 array[1] = key2; 99 array[2] = key3; 100 array[3] = key4; 101 return array; 102 } 103 104 private static <T> T[] newArray(final T key1, final T key2, final T key3, final T key4, final T key5) { 105 @SuppressWarnings("unchecked") 106 final T[] array = (T[]) Array.newInstance(getComponentType(key1, key2, key3, key4, key5), 5); 107 array[0] = key1; 108 array[1] = key2; 109 array[2] = key3; 110 array[3] = key4; 111 array[4] = key5; 112 return array; 113 } 114 115 /** The individual keys */ 116 private final K[] keys; 117 118 /** The cached hashCode */ 119 private transient int hashCode; 120 121 /** 122 * Constructor taking two keys. 123 * <p> 124 * The keys should be immutable 125 * If they are not then they must not be changed after adding to the MultiKey. 126 * 127 * @param key1 the first key 128 * @param key2 the second key 129 */ 130 public MultiKey(final K key1, final K key2) { 131 this(newArray(key1, key2), false); 132 } 133 134 /** 135 * Constructor taking three keys. 136 * <p> 137 * The keys should be immutable 138 * If they are not then they must not be changed after adding to the MultiKey. 139 * 140 * @param key1 the first key 141 * @param key2 the second key 142 * @param key3 the third key 143 */ 144 public MultiKey(final K key1, final K key2, final K key3) { 145 this(newArray(key1, key2, key3), false); 146 } 147 148 /** 149 * Constructor taking four keys. 150 * <p> 151 * The keys should be immutable 152 * If they are not then they must not be changed after adding to the MultiKey. 153 * 154 * @param key1 the first key 155 * @param key2 the second key 156 * @param key3 the third key 157 * @param key4 the fourth key 158 */ 159 public MultiKey(final K key1, final K key2, final K key3, final K key4) { 160 this(newArray(key1, key2, key3, key4), false); 161 } 162 163 /** 164 * Constructor taking five keys. 165 * <p> 166 * The keys should be immutable 167 * If they are not then they must not be changed after adding to the MultiKey. 168 * 169 * @param key1 the first key 170 * @param key2 the second key 171 * @param key3 the third key 172 * @param key4 the fourth key 173 * @param key5 the fifth key 174 */ 175 public MultiKey(final K key1, final K key2, final K key3, final K key4, final K key5) { 176 this(newArray(key1, key2, key3, key4, key5), false); 177 } 178 179 /** 180 * Constructor taking an array of keys which is cloned. 181 * <p> 182 * The keys should be immutable 183 * If they are not then they must not be changed after adding to the MultiKey. 184 * <p> 185 * This is equivalent to {@code new MultiKey(keys, true)}. 186 * 187 * @param keys the array of keys, not null 188 * @throws NullPointerException if the key array is null 189 */ 190 public MultiKey(final K[] keys) { 191 this(keys, true); 192 } 193 194 /** 195 * Constructor taking an array of keys, optionally choosing whether to clone. 196 * <p> 197 * <b>If the array is not cloned, then it must not be modified.</b> 198 * <p> 199 * This method is public for performance reasons only, to avoid a clone. 200 * The hash code is calculated once here in this method. 201 * Therefore, changing the array passed in would not change the hash code but 202 * would change the equals method, which is a bug. 203 * <p> 204 * This is the only fully safe usage of this constructor, as the object array 205 * is never made available in a variable: 206 * <pre> 207 * new MultiKey(new Object[] {...}, false); 208 * </pre> 209 * <p> 210 * The keys should be immutable 211 * If they are not then they must not be changed after adding to the MultiKey. 212 * 213 * @param keys the array of keys, not null 214 * @param makeClone true to clone the array, false to assign it 215 * @throws NullPointerException if the key array is null 216 * @since 3.1 217 */ 218 public MultiKey(final K[] keys, final boolean makeClone) { 219 Objects.requireNonNull(keys, "keys"); 220 this.keys = makeClone ? keys.clone() : keys; 221 calculateHashCode(keys); 222 } 223 224 /** 225 * Calculate the hash code of the instance using the provided keys. 226 * @param keys the keys to calculate the hash code for 227 */ 228 private void calculateHashCode(final Object[] keys) { 229 int total = 0; 230 for (final Object key : keys) { 231 if (key != null) { 232 total ^= key.hashCode(); 233 } 234 } 235 hashCode = total; 236 } 237 238 /** 239 * Compares this object to another. 240 * <p> 241 * To be equal, the other object must be a {@code MultiKey} with the 242 * same number of keys which are also equal. 243 * 244 * @param other the other object to compare to 245 * @return true if equal 246 */ 247 @Override 248 public boolean equals(final Object other) { 249 if (other == this) { 250 return true; 251 } 252 if (other instanceof MultiKey) { 253 final MultiKey<?> otherMulti = (MultiKey<?>) other; 254 return Arrays.equals(keys, otherMulti.keys); 255 } 256 return false; 257 } 258 259 /** 260 * Gets the key at the specified index. 261 * <p> 262 * The key should be immutable. 263 * If it is not then it must not be changed. 264 * 265 * @param index the index to retrieve 266 * @return the key at the index 267 * @throws IndexOutOfBoundsException if the index is invalid 268 * @since 3.1 269 */ 270 public K getKey(final int index) { 271 return keys[index]; 272 } 273 274 /** 275 * Gets a clone of the array of keys. 276 * <p> 277 * The keys should be immutable 278 * If they are not then they must not be changed. 279 * 280 * @return the individual keys 281 */ 282 public K[] getKeys() { 283 return keys.clone(); 284 } 285 286 /** 287 * Gets the combined hash code that is computed from all the keys. 288 * <p> 289 * This value is computed once and then cached, so elements should not 290 * change their hash codes once created (note that this is the same 291 * constraint that would be used if the individual keys elements were 292 * themselves {@link java.util.Map Map} keys). 293 * 294 * @return the hash code 295 */ 296 @Override 297 public int hashCode() { 298 return hashCode; 299 } 300 301 /** 302 * Recalculate the hash code after deserialization. The hash code of some 303 * keys might have change (hash codes based on the system hash code are 304 * only stable for the same process). 305 * @return the instance with recalculated hash code 306 */ 307 protected Object readResolve() { 308 calculateHashCode(keys); 309 return this; 310 } 311 312 /** 313 * Gets the size of the list of keys. 314 * 315 * @return the size of the list of keys 316 * @since 3.1 317 */ 318 public int size() { 319 return keys.length; 320 } 321 322 /** 323 * Gets a debugging string version of the key. 324 * 325 * @return a debugging string 326 */ 327 @Override 328 public String toString() { 329 return "MultiKey" + Arrays.toString(keys); 330 } 331 }