001/* 002 * Copyright (C) 2007 The Guava Authors 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * http://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 017package com.google.common.collect; 018 019import com.google.common.annotations.GwtCompatible; 020import com.google.errorprone.annotations.CanIgnoreReturnValue; 021import java.util.Collection; 022import java.util.List; 023import java.util.Map; 024import org.checkerframework.checker.nullness.qual.Nullable; 025 026/** 027 * A {@code Multimap} that can hold duplicate key-value pairs and that maintains the insertion 028 * ordering of values for a given key. See the {@link Multimap} documentation for information common 029 * to all multimaps. 030 * 031 * <p>The {@link #get}, {@link #removeAll}, and {@link #replaceValues} methods each return a {@link 032 * List} of values. Though the method signature doesn't say so explicitly, the map returned by 033 * {@link #asMap} has {@code List} values. 034 * 035 * <p>See the Guava User Guide article on <a href= 036 * "https://github.com/google/guava/wiki/NewCollectionTypesExplained#multimap"> {@code 037 * Multimap}</a>. 038 * 039 * @author Jared Levy 040 * @since 2.0 041 */ 042@GwtCompatible 043public interface ListMultimap<K, V> extends Multimap<K, V> { 044 /** 045 * {@inheritDoc} 046 * 047 * <p>Because the values for a given key may have duplicates and follow the insertion ordering, 048 * this method returns a {@link List}, instead of the {@link java.util.Collection} specified in 049 * the {@link Multimap} interface. 050 */ 051 @Override 052 List<V> get(@Nullable K key); 053 054 /** 055 * {@inheritDoc} 056 * 057 * <p>Because the values for a given key may have duplicates and follow the insertion ordering, 058 * this method returns a {@link List}, instead of the {@link java.util.Collection} specified in 059 * the {@link Multimap} interface. 060 */ 061 @CanIgnoreReturnValue 062 @Override 063 List<V> removeAll(@Nullable Object key); 064 065 /** 066 * {@inheritDoc} 067 * 068 * <p>Because the values for a given key may have duplicates and follow the insertion ordering, 069 * this method returns a {@link List}, instead of the {@link java.util.Collection} specified in 070 * the {@link Multimap} interface. 071 */ 072 @CanIgnoreReturnValue 073 @Override 074 List<V> replaceValues(K key, Iterable<? extends V> values); 075 076 /** 077 * {@inheritDoc} 078 * 079 * <p><b>Note:</b> The returned map's values are guaranteed to be of type {@link List}. To obtain 080 * this map with the more specific generic type {@code Map<K, List<V>>}, call {@link 081 * Multimaps#asMap(ListMultimap)} instead. 082 */ 083 @Override 084 Map<K, Collection<V>> asMap(); 085 086 /** 087 * Compares the specified object to this multimap for equality. 088 * 089 * <p>Two {@code ListMultimap} instances are equal if, for each key, they contain the same values 090 * in the same order. If the value orderings disagree, the multimaps will not be considered equal. 091 * 092 * <p>An empty {@code ListMultimap} is equal to any other empty {@code Multimap}, including an 093 * empty {@code SetMultimap}. 094 */ 095 @Override 096 boolean equals(@Nullable Object obj); 097}