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; 18 19 import java.util.List; 20 21 /** 22 * Defines a map that holds a list of values against each key. 23 * <p> 24 * A {@code ListValuedMap} is a Map with slightly different semantics: 25 * </p> 26 * <ul> 27 * <li>Putting a value into the map will add the value to a {@link List} at that key.</li> 28 * <li>Getting a value will return a {@link List}, holding all the values put to that key.</li> 29 * </ul> 30 * 31 * @param <K> the type of the keys in this map 32 * @param <V> the type of the values in this map 33 * @since 4.1 34 */ 35 public interface ListValuedMap<K, V> extends MultiValuedMap<K, V> { 36 37 /** 38 * Gets the list of values associated with the specified key. 39 * <p> 40 * This method will return an <b>empty</b> list if 41 * {@link #containsKey(Object)} returns {@code false}. Changes to the 42 * returned list will update the underlying {@code ListValuedMap} and 43 * vice-versa. 44 * 45 * @param key the key to retrieve 46 * @return the {@code List} of values, implementations should return an 47 * empty {@code List} for no mapping 48 * @throws NullPointerException if the key is null and null keys are invalid 49 */ 50 @Override 51 List<V> get(K key); 52 53 /** 54 * Removes all values associated with the specified key. 55 * <p> 56 * The returned list <i>may</i> be modifiable, but updates will not be 57 * propagated to this list-valued map. In case no mapping was stored for the 58 * specified key, an empty, unmodifiable list will be returned. 59 * 60 * @param key the key to remove values from 61 * @return the {@code List} of values removed, implementations 62 * typically return an empty, unmodifiable {@code List} for no mapping found 63 * @throws UnsupportedOperationException if the map is unmodifiable 64 * @throws NullPointerException if the key is null and null keys are invalid 65 */ 66 @Override 67 List<V> remove(Object key); 68 69 }