001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.collections4.keyvalue;
018
019import java.io.Serializable;
020import java.lang.reflect.Array;
021import java.util.Arrays;
022import java.util.Objects;
023
024/**
025 * A {@code MultiKey} allows multiple map keys to be merged together.
026 * <p>
027 * The purpose of this class is to avoid the need to write code to handle
028 * maps of maps. An example might be the need to look up a file name by
029 * key and locale. The typical solution might be nested maps. This class
030 * can be used instead by creating an instance passing in the key and locale.
031 * </p>
032 * <p>
033 * Example usage:
034 * </p>
035 * <pre>
036 * // populate map with data mapping key+locale to localizedText
037 * Map map = new HashMap();
038 * MultiKey multiKey = new MultiKey(key, locale);
039 * map.put(multiKey, localizedText);
040 *
041 * // later retrieve the localized text
042 * MultiKey multiKey = new MultiKey(key, locale);
043 * String localizedText = (String) map.get(multiKey);
044 * </pre>
045 *
046 * @param <K> the type of keys
047 * @since 3.0
048 */
049public class MultiKey<K> implements Serializable {
050    // This class could implement List, but that would confuse its purpose
051
052    /** Serialisation version */
053    private static final long serialVersionUID = 4465448607415788805L;
054
055    @SuppressWarnings("unchecked")
056    private static <T> Class<? extends T> getClass(final T value) {
057        return (Class<? extends T>) (value == null ? Object.class : value.getClass());
058    }
059
060    @SafeVarargs
061    private static <T> Class<? extends T> getComponentType(final T... values) {
062        @SuppressWarnings("unchecked")
063        final Class<? extends T> rootClass = (Class<? extends T>) Object.class;
064        if (values == null) {
065            return rootClass;
066        }
067        Class<? extends T> prevClass = values.length > 0 ? getClass(values[0]) : rootClass;
068        for (int i = 1; i < values.length; i++) {
069            final Class<? extends T> classI = getClass(values[i]);
070            if (prevClass != classI) {
071                return rootClass;
072            }
073            prevClass = classI;
074        }
075        return prevClass;
076    }
077
078    private static <T> T[] newArray(final T key1, final T key2) {
079        @SuppressWarnings("unchecked")
080        final T[] array = (T[]) Array.newInstance(getComponentType(key1, key2), 2);
081        array[0] = key1;
082        array[1] = key2;
083        return array;
084    }
085
086    private static <T> T[] newArray(final T key1, final T key2, final T key3) {
087        @SuppressWarnings("unchecked")
088        final T[] array = (T[]) Array.newInstance(getComponentType(key1, key2, key3), 3);
089        array[0] = key1;
090        array[1] = key2;
091        array[2] = key3;
092        return array;
093    }
094
095    private static <T> T[] newArray(final T key1, final T key2, final T key3, final T key4) {
096        @SuppressWarnings("unchecked")
097        final T[] array = (T[]) Array.newInstance(getComponentType(key1, key2, key3, key4), 4);
098        array[0] = key1;
099        array[1] = key2;
100        array[2] = key3;
101        array[3] = key4;
102        return array;
103    }
104
105    private static <T> T[] newArray(final T key1, final T key2, final T key3, final T key4, final T key5) {
106        @SuppressWarnings("unchecked")
107        final T[] array = (T[]) Array.newInstance(getComponentType(key1, key2, key3, key4, key5), 5);
108        array[0] = key1;
109        array[1] = key2;
110        array[2] = key3;
111        array[3] = key4;
112        array[4] = key5;
113        return array;
114    }
115
116    /** The individual keys */
117    private final K[] keys;
118
119    /** The cached hashCode */
120    private transient int hashCode;
121
122    /**
123     * Constructor taking two keys.
124     * <p>
125     * The keys should be immutable.
126     * If they are not then they must not be changed after adding to the MultiKey.
127     * </p>
128     *
129     * @param key1  the first key
130     * @param key2  the second key
131     */
132    public MultiKey(final K key1, final K key2) {
133        this(newArray(key1, key2), false);
134    }
135
136    /**
137     * Constructor taking three keys.
138     * <p>
139     * The keys should be immutable
140     * If they are not then they must not be changed after adding to the MultiKey.
141     * </p>
142     *
143     * @param key1  the first key
144     * @param key2  the second key
145     * @param key3  the third key
146     */
147    public MultiKey(final K key1, final K key2, final K key3) {
148        this(newArray(key1, key2, key3), false);
149    }
150
151    /**
152     * Constructor taking four keys.
153     * <p>
154     * The keys should be immutable.
155     * If they are not then they must not be changed after adding to the MultiKey.
156     * </p>
157     *
158     * @param key1  the first key
159     * @param key2  the second key
160     * @param key3  the third key
161     * @param key4  the fourth key
162     */
163    public MultiKey(final K key1, final K key2, final K key3, final K key4) {
164        this(newArray(key1, key2, key3, key4), false);
165    }
166
167    /**
168     * Constructor taking five keys.
169     * <p>
170     * The keys should be immutable.
171     * If they are not then they must not be changed after adding to the MultiKey.
172     * </p>
173     *
174     * @param key1  the first key
175     * @param key2  the second key
176     * @param key3  the third key
177     * @param key4  the fourth key
178     * @param key5  the fifth key
179     */
180    public MultiKey(final K key1, final K key2, final K key3, final K key4, final K key5) {
181        this(newArray(key1, key2, key3, key4, key5), false);
182    }
183
184    /**
185     * Constructor taking an array of keys which is cloned.
186     * <p>
187     * The keys should be immutable.
188     * If they are not then they must not be changed after adding to the MultiKey.
189     * </p>
190     * <p>
191     * This is equivalent to {@code new MultiKey(keys, true)}.
192     * </p>
193     *
194     * @param keys  the array of keys, not null
195     * @throws NullPointerException if the key array is null
196     */
197    public MultiKey(final K[] keys) {
198        this(keys, true);
199    }
200
201    /**
202     * Constructor taking an array of keys, optionally choosing whether to clone.
203     * <p>
204     * <strong>If the array is not cloned, then it must not be modified.</strong>
205     * </p>
206     * <p>
207     * This method is public for performance reasons only, to avoid a clone.
208     * The hash code is calculated once here in this method.
209     * Therefore, changing the array passed in would not change the hash code but
210     * would change the equals method, which is a bug.
211     * </p>
212     * <p>
213     * This is the only fully safe usage of this constructor, as the object array
214     * is never made available in a variable:
215     * <pre>
216     * new MultiKey(new Object[] {...}, false);
217     * </pre>
218     * <p>
219     * The keys should be immutable.
220     * If they are not then they must not be changed after adding to the MultiKey.
221     * </p>
222     *
223     * @param keys  the array of keys, not null
224     * @param makeClone  true to clone the array, false to assign it
225     * @throws NullPointerException if the key array is null
226     * @since 3.1
227     */
228    public MultiKey(final K[] keys, final boolean makeClone) {
229        Objects.requireNonNull(keys, "keys");
230        this.keys = makeClone ? keys.clone() : keys;
231        calculateHashCode(keys);
232    }
233
234    /**
235     * Calculate the hash code of the instance using the provided keys.
236     * @param keys the keys to calculate the hash code for
237     */
238    private void calculateHashCode(final Object[] keys) {
239        int total = 0;
240        for (final Object key : keys) {
241            if (key != null) {
242                total ^= key.hashCode();
243            }
244        }
245        hashCode = total;
246    }
247
248    /**
249     * Compares this object to another.
250     * <p>
251     * To be equal, the other object must be a {@code MultiKey} with the
252     * same number of keys which are also equal.
253     * </p>
254     *
255     * @param other  the other object to compare to
256     * @return true if equal
257     */
258    @Override
259    public boolean equals(final Object other) {
260        if (other == this) {
261            return true;
262        }
263        if (other instanceof MultiKey) {
264            final MultiKey<?> otherMulti = (MultiKey<?>) other;
265            return Arrays.equals(keys, otherMulti.keys);
266        }
267        return false;
268    }
269
270    /**
271     * Gets the key at the specified index.
272     * <p>
273     * The key should be immutable.
274     * If it is not then it must not be changed.
275     * </p>
276     *
277     * @param index  the index to retrieve
278     * @return the key at the index
279     * @throws IndexOutOfBoundsException if the index is invalid
280     * @since 3.1
281     */
282    public K getKey(final int index) {
283        return keys[index];
284    }
285
286    /**
287     * Gets a clone of the array of keys.
288     * <p>
289     * The keys should be immutable
290     * If they are not then they must not be changed.
291     * </p>
292     *
293     * @return the individual keys
294     */
295    public K[] getKeys() {
296        return keys.clone();
297    }
298
299    /**
300     * Gets the combined hash code that is computed from all the keys.
301     * <p>
302     * This value is computed once and then cached, so elements should not
303     * change their hash codes once created (note that this is the same
304     * constraint that would be used if the individual keys elements were
305     * themselves {@link java.util.Map Map} keys).
306     * </p>
307     *
308     * @return the hash code
309     */
310    @Override
311    public int hashCode() {
312        return hashCode;
313    }
314
315    /**
316     * Recalculate the hash code after deserialization. The hash code of some
317     * keys might have change (hash codes based on the system hash code are
318     * only stable for the same process).
319     * @return the instance with recalculated hash code
320     */
321    protected Object readResolve() {
322        calculateHashCode(keys);
323        return this;
324    }
325
326    /**
327     * Gets the size of the list of keys.
328     *
329     * @return the size of the list of keys
330     * @since 3.1
331     */
332    public int size() {
333        return keys.length;
334    }
335
336    /**
337     * Gets a debugging string version of the key.
338     *
339     * @return a debugging string
340     */
341    @Override
342    public String toString() {
343        return "MultiKey" + Arrays.toString(keys);
344    }
345}