001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package java.util;
019:
020: /**
021: * Map has a set of keys, each key is mapped to a single value.
022: */
023: public interface Map<K, V> {
024:
025: /**
026: * Map.Entry is a key/value mapping which is contained in a Map.
027: */
028: public static interface Entry<K, V> {
029: /**
030: * Compares the specified object to this Map.Entry and answer if they
031: * are equal. The object must be an instance of Map.Entry and have the
032: * same key and value.
033: *
034: * @param object
035: * the object to compare with this object
036: * @return true if the specified object is equal to this Map.Entry,
037: * false otherwise
038: *
039: * @see #hashCode
040: */
041: public boolean equals(Object object);
042:
043: /**
044: * Gets the key.
045: *
046: * @return the key
047: */
048: public K getKey();
049:
050: /**
051: * Gets the value.
052: *
053: * @return the value
054: */
055: public V getValue();
056:
057: /**
058: * Answers an integer hash code for the receiver. Objects which are
059: * equal answer the same value for this method.
060: *
061: * @return the receiver's hash
062: *
063: * @see #equals
064: */
065: public int hashCode();
066:
067: /**
068: * Sets the value.
069: *
070: * @param object
071: * the new value
072: * @return object
073: */
074: public V setValue(V object);
075: }
076:
077: /**
078: * Removes all elements from this Map, leaving it empty.
079: *
080: * @exception UnsupportedOperationException
081: * when removing from this Map is not supported
082: *
083: * @see #isEmpty
084: * @see #size
085: */
086: public void clear();
087:
088: /**
089: * Searches this Map for the specified key.
090: *
091: * @param key
092: * the object to search for
093: * @return true if <code>key</code> is a key of this Map, false otherwise
094: */
095: public boolean containsKey(Object key);
096:
097: /**
098: * Searches this Map for the specified value.
099: *
100: * @param value
101: * the object to search for
102: * @return true if <code>value</code> is a value of this Map, false
103: * otherwise
104: */
105: public boolean containsValue(Object value);
106:
107: /**
108: * Returns a <code>Set</code> whose elements comprise all of the mappings
109: * that are to be found in this <code>Map</code>. Information on each of
110: * the mappings is encapsulated in a separate {@link Map.Entry} instance. As
111: * the <code>Set</code> is backed by this <code>Map</code>, users
112: * should be aware that changes in one will be immediately visible in the
113: * other.
114: *
115: * @return a <code>Set</code> of the mappings
116: */
117: public Set<Map.Entry<K, V>> entrySet();
118:
119: /**
120: * Compares the argument to the receiver, and answers true if they represent
121: * the <em>same</em> object using a class specific comparison.
122: *
123: * @param object
124: * Object the object to compare with this object.
125: * @return boolean <code>true</code> if the object is the same as this
126: * object <code>false</code> if it is different from this object.
127: * @see #hashCode
128: */
129: public boolean equals(Object object);
130:
131: /**
132: * Answers the value of the mapping with the specified key.
133: *
134: * @param key
135: * the key
136: * @return the value of the mapping with the specified key
137: */
138: public V get(Object key);
139:
140: /**
141: * Answers an integer hash code for the receiver. Objects which are equal
142: * answer the same value for this method.
143: *
144: * @return the receiver's hash
145: *
146: * @see #equals
147: */
148: public int hashCode();
149:
150: /**
151: * Answers if this Map has no elements, a size of zero.
152: *
153: * @return true if this Map has no elements, false otherwise
154: *
155: * @see #size
156: */
157: public boolean isEmpty();
158:
159: /**
160: * Answers a Set of the keys contained in this Map. The set is backed by
161: * this Map so changes to one are reflected by the other. The set does not
162: * support adding.
163: *
164: * @return a Set of the keys
165: */
166: public Set<K> keySet();
167:
168: /**
169: * Maps the specified key to the specified value.
170: *
171: * @param key
172: * the key
173: * @param value
174: * the value
175: * @return the value of any previous mapping with the specified key or null
176: * if there was no mapping
177: *
178: * @exception UnsupportedOperationException
179: * when adding to this Map is not supported
180: * @exception ClassCastException
181: * when the class of the key or value is inappropriate for
182: * this Map
183: * @exception IllegalArgumentException
184: * when the key or value cannot be added to this Map
185: * @exception NullPointerException
186: * when the key or value is null and this Map does not
187: * support null keys or values
188: */
189: public V put(K key, V value);
190:
191: /**
192: * Copies every mapping in the specified Map to this Map.
193: *
194: * @param map
195: * the Map to copy mappings from
196: *
197: * @exception UnsupportedOperationException
198: * when adding to this Map is not supported
199: * @exception ClassCastException
200: * when the class of a key or value is inappropriate for this
201: * Map
202: * @exception IllegalArgumentException
203: * when a key or value cannot be added to this Map
204: * @exception NullPointerException
205: * when a key or value is null and this Map does not support
206: * null keys or values
207: */
208: public void putAll(Map<? extends K, ? extends V> map);
209:
210: /**
211: * Removes a mapping with the specified key from this Map.
212: *
213: * @param key
214: * the key of the mapping to remove
215: * @return the value of the removed mapping or null if key is not a key in
216: * this Map
217: *
218: * @exception UnsupportedOperationException
219: * when removing from this Map is not supported
220: */
221: public V remove(Object key);
222:
223: /**
224: * Answers the number of elements in this Map.
225: *
226: * @return the number of elements in this Map
227: */
228: public int size();
229:
230: /**
231: * Returns all of the current <code>Map</code> values in a
232: * <code>Collection</code>. As the returned <code>Collection</code> is
233: * backed by this <code>Map</code>, users should be aware that changes in
234: * one will be immediately visible in the other.
235: *
236: * @return a Collection of the values
237: */
238: public Collection<V> values();
239: }
|