| /* |
| * Licensed to the Apache Software Foundation (ASF) under one or more |
| * contributor license agreements. See the NOTICE file distributed with |
| * this work for additional information regarding copyright ownership. |
| * The ASF licenses this file to You under the Apache License, Version 2.0 |
| * (the "License"); you may not use this file except in compliance with |
| * the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| package org.apache.commons.collections4; |
| |
| import java.util.Collection; |
| import java.util.Map; |
| import java.util.Map.Entry; |
| import java.util.Set; |
| |
| /** |
| * Defines a map that holds a collection of values against each key. |
| * <p> |
| * A {@code MultiValuedMap} is a Map with slightly different semantics: |
| * <ul> |
| * <li>Putting a value into the map will add the value to a {@link Collection} at that key.</li> |
| * <li>Getting a value will return a {@link Collection}, holding all the values put to that key.</li> |
| * </ul> |
| * <p> |
| * For example: |
| * <pre> |
| * MultiValuedMap<K, String> map = new MultiValuedHashMap<K, String>(); |
| * map.put(key, "A"); |
| * map.put(key, "B"); |
| * map.put(key, "C"); |
| * Collection<String> coll = map.get(key); |
| * </pre> |
| * <p> |
| * <code>coll</code> will be a collection containing "A", "B", "C". |
| * <p> |
| * |
| * @since 4.1 |
| * @version $Id$ |
| */ |
| public interface MultiValuedMap<K, V> { |
| // Query operations |
| |
| /** |
| * Gets the total size of the map. |
| * <p> |
| * Implementations would return the total size of the map which is the count |
| * of the values from all keys. |
| * |
| * @return the total size of the map |
| */ |
| int size(); |
| |
| /** |
| * Returns {@code true} if this map contains no key-value mappings. |
| * |
| * @return {@code true} if this map contains no key-value mappings |
| */ |
| boolean isEmpty(); |
| |
| /** |
| * Returns {@code true} if this map contains a mapping for the specified |
| * key. More formally, returns {@code true} if and only if this map contains |
| * a mapping for a key {@code k} such that {@code (key==null ? k==null : key.equals(k))}. |
| * (There can be at most one such mapping.) |
| * |
| * @param key key whose presence in this map is to be tested |
| * @return true if this map contains a mapping for the specified key |
| * @throws NullPointerException if the specified key is null and this map |
| * does not permit null keys (optional) |
| */ |
| boolean containsKey(Object key); |
| |
| /** |
| * Checks whether the map contains at least one mapping for the specified value. |
| * |
| * @param value the value to search for |
| * @return true if the map contains the value |
| * @throws NullPointerException if the value is null and null values are not supported |
| * by the used collection types (optional) |
| */ |
| boolean containsValue(Object value); |
| |
| /** |
| * Checks whether the map contains a mapping for the specified key and value. |
| * |
| * @param key the key to search for |
| * @param value the value to search for |
| * @return true if the map contains the value |
| */ |
| boolean containsMapping(Object key, Object value); |
| |
| /** |
| * Returns a view collection of the values associated with the specified key. |
| * <p> |
| * This method will return an <b>empty</b> collection if {@link #containsKey(Object)} |
| * returns {@code false}. Changes to the returned collection will update the underlying |
| * {@code MultiValuedMap} and vice-versa. |
| * |
| * @param key the key to retrieve |
| * @return the {@code Collection} of values, implementations should |
| * return an empty collection for no mapping |
| * @throws NullPointerException if the key is null and null keys are invalid (optional) |
| */ |
| Collection<V> get(K key); |
| |
| // Modification operations |
| |
| /** |
| * Adds a key-value mapping to this multi-valued map. |
| * <p> |
| * Unlike a normal {@code Map} the previous value is not replaced. |
| * Instead the new value is added to the collection stored against the key. |
| * Depending on the collection type used, duplicate key-value mappings may |
| * be allowed. |
| * <p> |
| * The method will return {@code true} if the size of the multi-valued map |
| * has been increased because of this operation. |
| * |
| * @param key the key to store against |
| * @param value the value to add to the collection at the key |
| * @return true if the map changed as a result of this put operation, or false |
| * if the map already contained the key-value mapping and the collection |
| * type does not allow duplicate values, e.g. when using a Set |
| * @throws UnsupportedOperationException if the put operation is not supported by |
| * this multi-valued map, e.g. if it is unmodifiable |
| * @throws NullPointerException if the key or value is null and null is invalid (optional) |
| * @throws IllegalArgumentException if some aspect of the specified key or value prevents |
| * it from being stored in this multi-valued map |
| */ |
| boolean put(K key, V value); |
| |
| /** |
| * Adds a mapping to the specified key for all values contained in the given Iterable. |
| * |
| * @param key the key to store against |
| * @param values the values to add to the collection at the key, may not be null |
| * @return true if the map changed as a result of this operation |
| * @throws NullPointerException if the specified iterable is null, or if this map |
| * does not permit null keys or values, and the specified key or values contain |
| * null (optional) |
| */ |
| boolean putAll(K key, Iterable<? extends V> values); |
| |
| /** |
| * Copies all mappings from the specified map to this multi-valued map |
| * (optional operation). |
| * <p> |
| * The effect of this call is equivalent to that of calling |
| * {@link #put(Object,Object) put(k, v)} on this map once for each mapping |
| * from key {@code k} to value {@code v} in the specified map. |
| * <p> |
| * The behavior of this operation is undefined if the specified map is modified |
| * while the operation is in progress. |
| * |
| * @param map mappings to be stored in this map, may not be null |
| * @return true if the map changed as a result of this operation |
| * @throws UnsupportedOperationException if the {@code putAll} operation is |
| * not supported by this map |
| * @throws NullPointerException if the specified map is null, or if this map |
| * does not permit null keys or values, and the specified map |
| * contains null keys or values (optional) |
| * @throws IllegalArgumentException if some property of a key or value in |
| * the specified map prevents it from being stored in this map |
| */ |
| boolean putAll(Map<? extends K, ? extends V> map); |
| |
| /** |
| * Copies all mappings from the specified map to this multi-valued map |
| * (optional operation). |
| * <p> |
| * The effect of this call is equivalent to that of calling |
| * {@link #put(Object,Object) put(k, v)} on this map once for each |
| * mapping from key {@code k} to value {@code v} in the specified map. |
| * <p> |
| * The behavior of this operation is undefined if the specified map is modified |
| * while the operation is in progress. |
| * |
| * @param map mappings to be stored in this map, may not be null |
| * @return true if the map changed as a result of this operation |
| * @throws UnsupportedOperationException if the {@code putAll} operation is |
| * not supported by this map |
| * @throws NullPointerException if the specified map is null, or if this map |
| * does not permit null keys or values, and the specified map |
| * contains null keys or values (optional) |
| * @throws IllegalArgumentException if some property of a key or value in |
| * the specified map prevents it from being stored in this map |
| */ |
| boolean putAll(MultiValuedMap<? extends K, ? extends V> map); |
| |
| /** |
| * Removes all values associated with the specified key. |
| * <p> |
| * The returned collection <i>may</i> be modifiable, but updates will not be propagated |
| * to this multi-valued map. In case no mapping was stored for the specified |
| * key, an empty, unmodifiable collection will be returned. |
| * |
| * @param key the key to remove values from |
| * @return the values that were removed |
| * @throws UnsupportedOperationException if the map is unmodifiable |
| * @throws NullPointerException if the key is null and null keys are invalid (optional) |
| */ |
| Collection<V> remove(Object key); |
| |
| /** |
| * Removes a key-value mapping from the map. |
| * <p> |
| * The item is removed from the collection mapped to the specified key. |
| * Other values attached to that key are unaffected. |
| * <p> |
| * If the last value for a key is removed, implementations typically return |
| * an empty collection from a subsequent <code>get(Object)</code>. |
| * |
| * @param key the key to remove from |
| * @param item the item to remove |
| * @return true if the mapping was removed, false otherwise |
| * @throws UnsupportedOperationException if the map is unmodifiable |
| * @throws NullPointerException if the key or value is null and null is invalid (optional) |
| */ |
| boolean removeMapping(Object key, Object item); |
| |
| /** |
| * Removes all of the mappings from this map (optional operation). |
| * <p> |
| * The map will be empty after this call returns. |
| * |
| * @throws UnsupportedOperationException if the map is unmodifiable |
| */ |
| void clear(); |
| |
| // Views |
| |
| /** |
| * Returns a {@link Collection} view of the mappings contained in this multi-valued map. |
| * <p> |
| * The collection is backed by the map, so changes to the map are reflected |
| * in the collection, and vice-versa. |
| * |
| * @return a set view of the mappings contained in this map |
| */ |
| Collection<Entry<K, V>> entries(); |
| |
| /** |
| * Returns a {@link MultiSet} view of the keys contained in this multi-valued map. |
| * <p> |
| * The {@link MultiSet#getCount(Object)} method of the returned multiset will give |
| * the same result a calling {@code get(Object).size()} for the same key. |
| * <p> |
| * This multiset is backed by the map, so any changes in the map are reflected in |
| * the multiset. |
| * |
| * @return a multiset view of the keys contained in this map |
| */ |
| MultiSet<K> keys(); |
| |
| /** |
| * Returns a {@link Set} view of the keys contained in this multi-valued map. |
| * <p> |
| * The set is backed by the map, so changes to the map are reflected |
| * in the set, and vice-versa. |
| * <p> |
| * If the map is modified while an iteration over the set is in |
| * progress (except through the iterator's own {@code remove} operation), |
| * the result of the iteration is undefined. The set supports element |
| * removal, which removes the corresponding mapping from the map, via the |
| * {@code Iterator.remove}, {@code Set.remove}, {@code removeAll}, |
| * {@code retainAll}, and {@code clear} operations. It does not support |
| * the {@code add} or {@code addAll} operations. |
| * |
| * @return a set view of the keys contained in this map |
| */ |
| Set<K> keySet(); |
| |
| /** |
| * Gets a {@link Collection} view of all values contained in this multi-valued map. |
| * <p> |
| * Implementations typically return a collection containing the combination |
| * of values from all keys. |
| * |
| * @return a collection view of the values contained in this multi-valued map |
| */ |
| Collection<V> values(); |
| |
| /** |
| * Returns a view of this multi-valued map as a {@code Map} from each distinct |
| * key to the non-empty collection of that key's associated values. |
| * <p> |
| * Note that {@code this.asMap().get(k)} is equivalent to {@code this.get(k)} |
| * only when {@code k} is a key contained in the multi-valued map; otherwise it |
| * returns {@code null} as opposed to an empty collection. |
| * <p> |
| * Changes to the returned map or the collections that serve as its values |
| * will update the underlying multi-valued map, and vice versa. The map does |
| * not support {@code put} or {@code putAll}, nor do its entries support |
| * {@link Map.Entry#setValue setValue} and iterators support |
| * {@link java.util.Iterator#remove remove}. |
| * |
| * @return a map view of the mappings in this multi-valued map |
| */ |
| Map<K, Collection<V>> asMap(); |
| |
| // Iterators |
| |
| /** |
| * Obtains a <code>MapIterator</code> over this multi-valued map. |
| * <p> |
| * A map iterator is an efficient way of iterating over maps. There is no |
| * need to access the entries collection or use {@code Map.Entry} objects. |
| * |
| * @return a map iterator |
| */ |
| MapIterator<K, V> mapIterator(); |
| |
| } |