1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 package java.util; 19 20 21 /** 22 * A {@code Map} is a data structure consisting of a set of keys and values 23 * in which each key is mapped to a single value. The class of the objects 24 * used as keys is declared when the {@code Map} is declared, as is the 25 * class of the corresponding values. 26 * <p> 27 * A {@code Map} provides helper methods to iterate through all of the 28 * keys contained in it, as well as various methods to access and update 29 * the key/value pairs. 30 */ 31 public interface Map<K,V> { 32 33 /** 34 * {@code Map.Entry} is a key/value mapping contained in a {@code Map}. 35 */ 36 public static interface Entry<K,V> { 37 /** 38 * Compares the specified object to this {@code Map.Entry} and returns if they 39 * are equal. To be equal, the object must be an instance of {@code Map.Entry} and have the 40 * same key and value. 41 * 42 * @param object 43 * the {@code Object} to compare with this {@code Object}. 44 * @return {@code true} if the specified {@code Object} is equal to this 45 * {@code Map.Entry}, {@code false} otherwise. 46 * @see #hashCode() 47 */ 48 public boolean equals(Object object); 49 50 /** 51 * Returns the key. 52 * 53 * @return the key 54 */ 55 public K getKey(); 56 57 /** 58 * Returns the value. 59 * 60 * @return the value 61 */ 62 public V getValue(); 63 64 /** 65 * Returns an integer hash code for the receiver. {@code Object} which are 66 * equal return the same value for this method. 67 * 68 * @return the receiver's hash code. 69 * @see #equals(Object) 70 */ 71 public int hashCode(); 72 73 /** 74 * Sets the value of this entry to the specified value, replacing any 75 * existing value. 76 * 77 * @param object 78 * the new value to set. 79 * @return object the replaced value of this entry. 80 */ 81 public V setValue(V object); 82 }; 83 84 /** 85 * Removes all elements from this {@code Map}, leaving it empty. 86 * 87 * @throws UnsupportedOperationException 88 * if removing elements from this {@code Map} is not supported. 89 * @see #isEmpty() 90 * @see #size() 91 */ 92 public void clear(); 93 94 /** 95 * Returns whether this {@code Map} contains the specified key. 96 * 97 * @param key 98 * the key to search for. 99 * @return {@code true} if this map contains the specified key, 100 * {@code false} otherwise. 101 */ 102 public boolean containsKey(Object key); 103 104 /** 105 * Returns whether this {@code Map} contains the specified value. 106 * 107 * @param value 108 * the value to search for. 109 * @return {@code true} if this map contains the specified value, 110 * {@code false} otherwise. 111 */ 112 public boolean containsValue(Object value); 113 114 /** 115 * Returns a {@code Set} containing all of the mappings in this {@code Map}. Each mapping is 116 * an instance of {@link Map.Entry}. As the {@code Set} is backed by this {@code Map}, 117 * changes in one will be reflected in the other. 118 * 119 * @return a set of the mappings 120 */ 121 public Set<Map.Entry<K,V>> entrySet(); 122 123 /** 124 * Compares the argument to the receiver, and returns {@code true} if the 125 * specified object is a {@code Map} and both {@code Map}s contain the same mappings. 126 * 127 * @param object 128 * the {@code Object} to compare with this {@code Object}. 129 * @return boolean {@code true} if the {@code Object} is the same as this {@code Object} 130 * {@code false} if it is different from this {@code Object}. 131 * @see #hashCode() 132 * @see #entrySet() 133 */ 134 public boolean equals(Object object); 135 136 /** 137 * Returns the value of the mapping with the specified key. 138 * 139 * @param key 140 * the key. 141 * @return the value of the mapping with the specified key, or {@code null} 142 * if no mapping for the specified key is found. 143 */ 144 public V get(Object key); 145 146 /** 147 * Returns an integer hash code for the receiver. {@code Object}s which are equal 148 * return the same value for this method. 149 * 150 * @return the receiver's hash. 151 * @see #equals(Object) 152 */ 153 public int hashCode(); 154 155 /** 156 * Returns whether this map is empty. 157 * 158 * @return {@code true} if this map has no elements, {@code false} 159 * otherwise. 160 * @see #size() 161 */ 162 public boolean isEmpty(); 163 164 /** 165 * Returns a set of the keys contained in this {@code Map}. The {@code Set} is backed by 166 * this {@code Map} so changes to one are reflected by the other. The {@code Set} does not 167 * support adding. 168 * 169 * @return a set of the keys. 170 */ 171 public Set<K> keySet(); 172 173 /** 174 * Maps the specified key to the specified value. 175 * 176 * @param key 177 * the key. 178 * @param value 179 * the value. 180 * @return the value of any previous mapping with the specified key or 181 * {@code null} if there was no mapping. 182 * @throws UnsupportedOperationException 183 * if adding to this {@code Map} is not supported. 184 * @throws ClassCastException 185 * if the class of the key or value is inappropriate for 186 * this {@code Map}. 187 * @throws IllegalArgumentException 188 * if the key or value cannot be added to this {@code Map}. 189 * @throws NullPointerException 190 * if the key or value is {@code null} and this {@code Map} does 191 * not support {@code null} keys or values. 192 */ 193 public V put(K key, V value); 194 195 /** 196 * Copies every mapping in the specified {@code Map} to this {@code Map}. 197 * 198 * @param map 199 * the {@code Map} to copy mappings from. 200 * @throws UnsupportedOperationException 201 * if adding to this {@code Map} is not supported. 202 * @throws ClassCastException 203 * if the class of a key or a value of the specified {@code Map} is 204 * inappropriate for this {@code Map}. 205 * @throws IllegalArgumentException 206 * if a key or value cannot be added to this {@code Map}. 207 * @throws NullPointerException 208 * if a key or value is {@code null} and this {@code Map} does not 209 * support {@code null} keys or values. 210 */ 211 public void putAll(Map<? extends K,? extends V> map); 212 213 /** 214 * Removes a mapping with the specified key from this {@code Map}. 215 * 216 * @param key 217 * the key of the mapping to remove. 218 * @return the value of the removed mapping or {@code null} if no mapping 219 * for the specified key was found. 220 * @throws UnsupportedOperationException 221 * if removing from this {@code Map} is not supported. 222 */ 223 public V remove(Object key); 224 225 /** 226 * Returns the number of mappings in this {@code Map}. 227 * 228 * @return the number of mappings in this {@code Map}. 229 */ 230 public int size(); 231 232 /** 233 * Returns a {@code Collection} of the values contained in this {@code Map}. The {@code Collection} 234 * is backed by this {@code Map} so changes to one are reflected by the other. The 235 * {@code Collection} supports {@link Collection#remove}, {@link Collection#removeAll}, 236 * {@link Collection#retainAll}, and {@link Collection#clear} operations, 237 * and it does not support {@link Collection#add} or {@link Collection#addAll} operations. 238 * <p> 239 * This method returns a {@code Collection} which is the subclass of 240 * {@link AbstractCollection}. The {@link AbstractCollection#iterator} method of this subclass returns a 241 * "wrapper object" over the iterator of this {@code Map}'s {@link #entrySet()}. The {@link AbstractCollection#size} method 242 * wraps this {@code Map}'s {@link #size} method and the {@link AbstractCollection#contains} method wraps this {@code Map}'s 243 * {@link #containsValue} method. 244 * <p> 245 * The collection is created when this method is called at first time and 246 * returned in response to all subsequent calls. This method may return 247 * different Collection when multiple calls to this method, since it has no 248 * synchronization performed. 249 * 250 * @return a collection of the values contained in this map. 251 */ 252 public Collection<V> values(); 253 } 254
