1 /* 2 * Copyright (C) 2007 The Guava Authors 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package com.google.common.collect; 18 19 import com.google.common.annotations.GwtCompatible; 20 21 import java.util.Collection; 22 import java.util.Comparator; 23 import java.util.Map; 24 import java.util.Set; 25 import java.util.SortedSet; 26 27 import javax.annotation.Nullable; 28 29 /** 30 * A {@code SetMultimap} whose set of values for a given key are kept sorted; 31 * that is, they comprise a {@link SortedSet}. It cannot hold duplicate 32 * key-value pairs; adding a key-value pair that's already in the multimap has 33 * no effect. This interface does not specify the ordering of the multimap's 34 * keys. See the {@link Multimap} documentation for information common to all 35 * multimaps. 36 * 37 * <p>The {@link #get}, {@link #removeAll}, and {@link #replaceValues} methods 38 * each return a {@link SortedSet} of values, while {@link Multimap#entries()} 39 * returns a {@link Set} of map entries. Though the method signature doesn't say 40 * so explicitly, the map returned by {@link #asMap} has {@code SortedSet} 41 * values. 42 * 43 * <p>See the Guava User Guide article on <a href= 44 * "http://code.google.com/p/guava-libraries/wiki/NewCollectionTypesExplained#Multimap"> 45 * {@code Multimap}</a>. 46 * 47 * @author Jared Levy 48 * @since 2.0 (imported from Google Collections Library) 49 */ 50 @GwtCompatible 51 public interface SortedSetMultimap<K, V> extends SetMultimap<K, V> { 52 // Following Javadoc copied from Multimap. 53 54 /** 55 * Returns a collection view of all values associated with a key. If no 56 * mappings in the multimap have the provided key, an empty collection is 57 * returned. 58 * 59 * <p>Changes to the returned collection will update the underlying multimap, 60 * and vice versa. 61 * 62 * <p>Because a {@code SortedSetMultimap} has unique sorted values for a given 63 * key, this method returns a {@link SortedSet}, instead of the 64 * {@link java.util.Collection} specified in the {@link Multimap} interface. 65 */ 66 @Override get(@ullable K key)67 SortedSet<V> get(@Nullable K key); 68 69 /** 70 * Removes all values associated with a given key. 71 * 72 * <p>Because a {@code SortedSetMultimap} has unique sorted values for a given 73 * key, this method returns a {@link SortedSet}, instead of the 74 * {@link java.util.Collection} specified in the {@link Multimap} interface. 75 */ 76 @Override removeAll(@ullable Object key)77 SortedSet<V> removeAll(@Nullable Object key); 78 79 /** 80 * Stores a collection of values with the same key, replacing any existing 81 * values for that key. 82 * 83 * <p>Because a {@code SortedSetMultimap} has unique sorted values for a given 84 * key, this method returns a {@link SortedSet}, instead of the 85 * {@link java.util.Collection} specified in the {@link Multimap} interface. 86 * 87 * <p>Any duplicates in {@code values} will be stored in the multimap once. 88 */ 89 @Override replaceValues(K key, Iterable<? extends V> values)90 SortedSet<V> replaceValues(K key, Iterable<? extends V> values); 91 92 /** 93 * Returns a map view that associates each key with the corresponding values 94 * in the multimap. Changes to the returned map, such as element removal, will 95 * update the underlying multimap. The map does not support {@code setValue()} 96 * on its entries, {@code put}, or {@code putAll}. 97 * 98 * <p>When passed a key that is present in the map, {@code 99 * asMap().get(Object)} has the same behavior as {@link #get}, returning a 100 * live collection. When passed a key that is not present, however, {@code 101 * asMap().get(Object)} returns {@code null} instead of an empty collection. 102 * 103 * <p><b>Note:</b> The returned map's values are guaranteed to be of type 104 * {@link SortedSet}. To obtain this map with the more specific generic type 105 * {@code Map<K, SortedSet<V>>}, call 106 * {@link Multimaps#asMap(SortedSetMultimap)} instead. 107 */ asMap()108 @Override Map<K, Collection<V>> asMap(); 109 110 /** 111 * Returns the comparator that orders the multimap values, with {@code null} 112 * indicating that natural ordering is used. 113 */ valueComparator()114 Comparator<? super V> valueComparator(); 115 } 116