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.Comparator; 023import java.util.Map; 024import java.util.Set; 025import java.util.SortedSet; 026import javax.annotation.Nullable; 027 028/** 029 * A {@code SetMultimap} whose set of values for a given key are kept sorted; 030 * that is, they comprise a {@link SortedSet}. It cannot hold duplicate 031 * key-value pairs; adding a key-value pair that's already in the multimap has 032 * no effect. This interface does not specify the ordering of the multimap's 033 * keys. See the {@link Multimap} documentation for information common to all 034 * multimaps. 035 * 036 * <p>The {@link #get}, {@link #removeAll}, and {@link #replaceValues} methods 037 * each return a {@link SortedSet} of values, while {@link Multimap#entries()} 038 * returns a {@link Set} of map entries. Though the method signature doesn't say 039 * so explicitly, the map returned by {@link #asMap} has {@code SortedSet} 040 * values. 041 * 042 * <p>See the Guava User Guide article on <a href= 043 * "https://github.com/google/guava/wiki/NewCollectionTypesExplained#multimap"> 044 * {@code Multimap}</a>. 045 * 046 * @author Jared Levy 047 * @since 2.0 048 */ 049@GwtCompatible 050public interface SortedSetMultimap<K, V> extends SetMultimap<K, V> { 051 // Following Javadoc copied from Multimap. 052 053 /** 054 * Returns a collection view of all values associated with a key. If no 055 * mappings in the multimap have the provided key, an empty collection is 056 * returned. 057 * 058 * <p>Changes to the returned collection will update the underlying multimap, 059 * and vice versa. 060 * 061 * <p>Because a {@code SortedSetMultimap} has unique sorted values for a given 062 * key, this method returns a {@link SortedSet}, instead of the 063 * {@link java.util.Collection} specified in the {@link Multimap} interface. 064 */ 065 @Override 066 SortedSet<V> get(@Nullable K key); 067 068 /** 069 * Removes all values associated with a given key. 070 * 071 * <p>Because a {@code SortedSetMultimap} has unique sorted values for a given 072 * key, this method returns a {@link SortedSet}, instead of the 073 * {@link java.util.Collection} specified in the {@link Multimap} interface. 074 */ 075 @CanIgnoreReturnValue 076 @Override 077 SortedSet<V> removeAll(@Nullable Object key); 078 079 /** 080 * Stores a collection of values with the same key, replacing any existing 081 * values for that key. 082 * 083 * <p>Because a {@code SortedSetMultimap} has unique sorted values for a given 084 * key, this method returns a {@link SortedSet}, instead of the 085 * {@link java.util.Collection} specified in the {@link Multimap} interface. 086 * 087 * <p>Any duplicates in {@code values} will be stored in the multimap once. 088 */ 089 @CanIgnoreReturnValue 090 @Override 091 SortedSet<V> replaceValues(K key, Iterable<? extends V> values); 092 093 /** 094 * Returns a map view that associates each key with the corresponding values 095 * in the multimap. Changes to the returned map, such as element removal, will 096 * update the underlying multimap. The map does not support {@code setValue()} 097 * on its entries, {@code put}, or {@code putAll}. 098 * 099 * <p>When passed a key that is present in the map, {@code 100 * asMap().get(Object)} has the same behavior as {@link #get}, returning a 101 * live collection. When passed a key that is not present, however, {@code 102 * asMap().get(Object)} returns {@code null} instead of an empty collection. 103 * 104 * <p><b>Note:</b> The returned map's values are guaranteed to be of type 105 * {@link SortedSet}. To obtain this map with the more specific generic type 106 * {@code Map<K, SortedSet<V>>}, call 107 * {@link Multimaps#asMap(SortedSetMultimap)} instead. 108 */ 109 @Override 110 Map<K, Collection<V>> asMap(); 111 112 /** 113 * Returns the comparator that orders the multimap values, with {@code null} 114 * indicating that natural ordering is used. 115 */ 116 Comparator<? super V> valueComparator(); 117}