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 javax.annotation.CheckForNull; 025import org.checkerframework.checker.nullness.qual.Nullable; 026 027/** 028 * A {@code Multimap} that can hold duplicate key-value pairs and that maintains the insertion 029 * ordering of values for a given key. See the {@link Multimap} documentation for information common 030 * to all multimaps. 031 * 032 * <p>The {@link #get}, {@link #removeAll}, and {@link #replaceValues} methods each return a {@link 033 * List} of values. Though the method signature doesn't say so explicitly, the map returned by 034 * {@link #asMap} has {@code List} values. 035 * 036 * <p>See the Guava User Guide article on <a href= 037 * "https://github.com/google/guava/wiki/NewCollectionTypesExplained#multimap"> {@code 038 * Multimap}</a>. 039 * 040 * @author Jared Levy 041 * @since 2.0 042 */ 043@GwtCompatible 044@ElementTypesAreNonnullByDefault 045public interface ListMultimap<K extends @Nullable Object, V extends @Nullable Object> 046 extends Multimap<K, V> { 047 /** 048 * {@inheritDoc} 049 * 050 * <p>Because the values for a given key may have duplicates and follow the insertion ordering, 051 * this method returns a {@link List}, instead of the {@link java.util.Collection} specified in 052 * the {@link Multimap} interface. 053 */ 054 @Override 055 List<V> get(@ParametricNullness K key); 056 057 /** 058 * {@inheritDoc} 059 * 060 * <p>Because the values for a given key may have duplicates and follow the insertion ordering, 061 * this method returns a {@link List}, instead of the {@link java.util.Collection} specified in 062 * the {@link Multimap} interface. 063 */ 064 @CanIgnoreReturnValue 065 @Override 066 List<V> removeAll(@CheckForNull Object key); 067 068 /** 069 * {@inheritDoc} 070 * 071 * <p>Because the values for a given key may have duplicates and follow the insertion ordering, 072 * this method returns a {@link List}, instead of the {@link java.util.Collection} specified in 073 * the {@link Multimap} interface. 074 */ 075 @CanIgnoreReturnValue 076 @Override 077 List<V> replaceValues(@ParametricNullness K key, Iterable<? extends V> values); 078 079 /** 080 * {@inheritDoc} 081 * 082 * <p><b>Note:</b> The returned map's values are guaranteed to be of type {@link List}. To obtain 083 * this map with the more specific generic type {@code Map<K, List<V>>}, call {@link 084 * Multimaps#asMap(ListMultimap)} instead. 085 */ 086 @Override 087 Map<K, Collection<V>> asMap(); 088 089 /** 090 * Compares the specified object to this multimap for equality. 091 * 092 * <p>Two {@code ListMultimap} instances are equal if, for each key, they contain the same values 093 * in the same order. If the value orderings disagree, the multimaps will not be considered equal. 094 * 095 * <p>An empty {@code ListMultimap} is equal to any other empty {@code Multimap}, including an 096 * empty {@code SetMultimap}. 097 */ 098 @Override 099 boolean equals(@CheckForNull Object obj); 100}