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 17package com.google.common.collect; 18 19import com.google.common.annotations.GwtCompatible; 20 21import java.util.Collection; 22import java.util.Comparator; 23import java.util.Map; 24import java.util.Set; 25import java.util.SortedSet; 26 27import 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 2.0 (imported from Google Collections Library) 44 */ 45@GwtCompatible 46public interface SortedSetMultimap<K, V> extends SetMultimap<K, V> { 47 // Following Javadoc copied from Multimap. 48 49 /** 50 * Returns a collection view of all values associated with a key. If no 51 * mappings in the multimap have the provided key, an empty collection is 52 * returned. 53 * 54 * <p>Changes to the returned collection will update the underlying multimap, 55 * and vice versa. 56 * 57 * <p>Because a {@code SortedSetMultimap} has unique sorted values for a given 58 * key, this method returns a {@link SortedSet}, instead of the 59 * {@link java.util.Collection} specified in the {@link Multimap} interface. 60 */ 61 @Override 62 SortedSet<V> get(@Nullable K key); 63 64 /** 65 * Removes all values associated with a given key. 66 * 67 * <p>Because a {@code SortedSetMultimap} has unique sorted values for a given 68 * key, this method returns a {@link SortedSet}, instead of the 69 * {@link java.util.Collection} specified in the {@link Multimap} interface. 70 */ 71 @Override 72 SortedSet<V> removeAll(@Nullable Object key); 73 74 /** 75 * Stores a collection of values with the same key, replacing any existing 76 * values for that key. 77 * 78 * <p>Because a {@code SortedSetMultimap} has unique sorted values for a given 79 * key, this method returns a {@link SortedSet}, instead of the 80 * {@link java.util.Collection} specified in the {@link Multimap} interface. 81 * 82 * <p>Any duplicates in {@code values} will be stored in the multimap once. 83 */ 84 @Override 85 SortedSet<V> replaceValues(K key, Iterable<? extends V> values); 86 87 /** 88 * Returns a map view that associates each key with the corresponding values 89 * in the multimap. Changes to the returned map, such as element removal, will 90 * update the underlying multimap. The map does not support {@code setValue()} 91 * on its entries, {@code put}, or {@code putAll}. 92 * 93 * <p>When passed a key that is present in the map, {@code 94 * asMap().get(Object)} has the same behavior as {@link #get}, returning a 95 * live collection. When passed a key that is not present, however, {@code 96 * asMap().get(Object)} returns {@code null} instead of an empty collection. 97 * 98 * <p>Though the method signature doesn't say so explicitly, the returned map 99 * has {@link SortedSet} values. 100 */ 101 @Override 102 Map<K, Collection<V>> asMap(); 103 104 /** 105 * Returns the comparator that orders the multimap values, with {@code null} 106 * indicating that natural ordering is used. 107 */ 108 Comparator<? super V> valueComparator(); 109} 110