1 /* 2 * Copyright (C) 2007 Google Inc. 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. 35 * 36 * <p>The {@link #get}, {@link #removeAll}, and {@link #replaceValues} methods 37 * each return a {@link SortedSet} of values, while {@link Multimap#entries()} 38 * returns a {@link Set} of map entries. Though the method signature doesn't say 39 * so explicitly, the map returned by {@link #asMap} has {@code SortedSet} 40 * values. 41 * 42 * @author Jared Levy 43 * @since 2010.01.04 <b>stable</b> (imported from Google Collections Library) 44 */ 45 @GwtCompatible 46 public interface SortedSetMultimap<K, V> extends SetMultimap<K, V> { 47 /** 48 * Returns a collection view of all values associated with a key. If no 49 * mappings in the multimap have the provided key, an empty collection is 50 * returned. 51 * 52 * <p>Changes to the returned collection will update the underlying multimap, 53 * and vice versa. 54 * 55 * <p>Because a {@code SortedSetMultimap} has unique sorted values for a given 56 * key, this method returns a {@link SortedSet}, instead of the 57 * {@link java.util.Collection} specified in the {@link Multimap} interface. 58 */ 59 SortedSet<V> get(@Nullable K key); 60 61 /** 62 * Removes all values associated with a given key. 63 * 64 * <p>Because a {@code SortedSetMultimap} has unique sorted values for a given 65 * key, this method returns a {@link SortedSet}, instead of the 66 * {@link java.util.Collection} specified in the {@link Multimap} interface. 67 */ 68 SortedSet<V> removeAll(@Nullable Object key); 69 70 /** 71 * Stores a collection of values with the same key, replacing any existing 72 * values for that key. 73 * 74 * <p>Because a {@code SortedSetMultimap} has unique sorted values for a given 75 * key, this method returns a {@link SortedSet}, instead of the 76 * {@link java.util.Collection} specified in the {@link Multimap} interface. 77 * 78 * <p>Any duplicates in {@code values} will be stored in the multimap once. 79 */ 80 SortedSet<V> replaceValues(K key, Iterable<? extends V> values); 81 82 /** 83 * Returns a map view that associates each key with the corresponding values 84 * in the multimap. Changes to the returned map, such as element removal, 85 * will update the underlying multimap. The map never supports 86 * {@code setValue()} on the map entries, {@code put}, or {@code putAll}. 87 * 88 * <p>The collections returned by {@code asMap().get(Object)} have the same 89 * behavior as those returned by {@link #get}. 90 * 91 * <p>Though the method signature doesn't say so explicitly, the returned map 92 * has {@link SortedSet} values. 93 */ 94 Map<K, Collection<V>> asMap(); 95 96 /** 97 * Returns the comparator that orders the multimap values, with a {@code null} 98 * indicating that natural ordering is used. 99 */ 100 Comparator<? super V> valueComparator(); 101 } 102
