    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 *      https://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.multimap;
    018
    019import java.io.IOException;
    020import java.io.ObjectInputStream;
    021import java.io.ObjectOutputStream;
    022import java.io.Serializable;
    023import java.util.ArrayList;
    024import java.util.Collection;
    025import java.util.HashMap;
    026import java.util.Map;
    027
    028import org.apache.commons.collections4.MultiMapUtils;
    029import org.apache.commons.collections4.MultiValuedMap;
    030
    031/**
    032 * Implements a {@code ListValuedMap}, using a {@link HashMap} to provide data
    033 * storage and {@link ArrayList}s as value collections. This is the standard
    034 * implementation of a ListValuedMap.
    035 * <p>
    036 * <strong>Note that ArrayListValuedHashMap is not synchronized and is not
    037 * thread-safe.</strong> If you wish to use this map from multiple threads
    038 * concurrently, you must use appropriate synchronization. This class may throw
    039 * exceptions when accessed by concurrent threads without synchronization.
    040 * </p>
    041 *
    042 * @param <K> The type of the keys in this map
    043 * @param <V> The type of the values in this map
    044 * @since 4.1
    045 */
    046public class ArrayListValuedHashMap<K, V> extends AbstractListValuedMap<K, V>
    047    implements Serializable {
    048
    049    /** Serialization Version */
    050    private static final long serialVersionUID = 20151118L;
    051
    052    /**
    053     * The initial map capacity used when none specified in constructor.
    054     */
    055    private static final int DEFAULT_INITIAL_MAP_CAPACITY = 16;
    056
    057    /**
    058     * The initial list capacity when using none specified in constructor.
    059     */
    060    private static final int DEFAULT_INITIAL_LIST_CAPACITY = 3;
    061
    062    /**
    063     * The initial list capacity when creating a new value collection.
    064     */
    065    private final int initialListCapacity;
    066
    067    /**
    068     * Creates an empty ArrayListValuedHashMap with the default initial
    069     * map capacity (16) and the default initial list capacity (3).
    070     */
    071    public ArrayListValuedHashMap() {
    072        this(DEFAULT_INITIAL_MAP_CAPACITY, DEFAULT_INITIAL_LIST_CAPACITY);
    073    }
    074
    075    /**
    076     * Creates an empty ArrayListValuedHashMap with the default initial
    077     * map capacity (16) and the specified initial list capacity.
    078     *
    079     * @param initialListCapacity  The initial capacity used for value collections
    080     */
    081    public ArrayListValuedHashMap(final int initialListCapacity) {
    082        this(DEFAULT_INITIAL_MAP_CAPACITY, initialListCapacity);
    083    }
    084
    085    /**
    086     * Creates an empty ArrayListValuedHashMap with the specified initial
    087     * map and list capacities.
    088     *
    089     * @param initialMapCapacity  The initial hashmap capacity
    090     * @param initialListCapacity  The initial capacity used for value collections
    091     */
    092    public ArrayListValuedHashMap(final int initialMapCapacity, final int initialListCapacity) {
    093        super(new HashMap<>(initialMapCapacity));
    094        this.initialListCapacity = initialListCapacity;
    095    }
    096
    097    /**
    098     * Creates an ArrayListValuedHashMap copying all the mappings of the given map.
    099     *
    100     * @param map A {@code Map} to copy into this map
    101     */
    102    public ArrayListValuedHashMap(final Map<? extends K, ? extends V> map) {
    103        this(map.size(), DEFAULT_INITIAL_LIST_CAPACITY);
    104        super.putAll(map);
    105    }
    106
    107    /**
    108     * Creates an ArrayListValuedHashMap copying all the mappings of the given map.
    109     *
    110     * @param map A {@code MultiValuedMap} to copy into this map
    111     */
    112    public ArrayListValuedHashMap(final MultiValuedMap<? extends K, ? extends V> map) {
    113        this(map.size(), DEFAULT_INITIAL_LIST_CAPACITY);
    114        super.putAll(map);
    115    }
    116
    117    @Override
    118    protected ArrayList<V> createCollection() {
    119        return new ArrayList<>(initialListCapacity);
    120    }
    121
    122    @Override
    123    public ArrayListValuedHashMap<V, K> inverted() {
    124        return MultiMapUtils.invert(this, new ArrayListValuedHashMap<V, K>());
    125    }
    126
    127    /**
    128     * Deserializes an instance from an ObjectInputStream.
    129     *
    130     * @param in The source ObjectInputStream.
    131     * @throws IOException            Any of the usual Input/Output related exceptions.
    132     * @throws ClassNotFoundException A class of a serialized object cannot be found.
    133     */
    134    private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {
    135        in.defaultReadObject();
    136        setMap(new HashMap<>());
    137        doReadObject(in);
    138    }
    139
    140    /**
    141     * Trims the capacity of all value collections to their current size.
    142     */
    143    public void trimToSize() {
    144        for (final Collection<V> coll : getMap().values()) {
    145            final ArrayList<V> list = (ArrayList<V>) coll;
    146            list.trimToSize();
    147        }
    148    }
    149
    150    /**
    151     * Serializes this object to an ObjectOutputStream.
    152     *
    153     * @param out The target ObjectOutputStream.
    154     * @throws IOException thrown when an I/O errors occur writing to the target stream.
    155     */
    156    private void writeObject(final ObjectOutputStream out) throws IOException {
    157        out.defaultWriteObject();
    158        doWriteObject(out);
    159    }
    160
    161}