java.util

Interface Map<K,V>

Known Subinterfaces:
SortedMap<K,V>
Known Implementing Classes:
AbstractMap<K,V>, Attributes, EnumMap<K,extends,Enum,K,V>, HashMap<K,V>, Hashtable<K,V>, IdentityHashMap<K,V>, LinkedHashMap<K,V>, PrinterStateReasons, Properties, Provider, RenderingHints, TabularDataSupport, TreeMap<K,V>, UIDefaults, WeakHashMap<K,V>

public interface Map<K,V>

An object that maps keys onto values. Keys cannot be duplicated. This interface replaces the obsolete Dictionary abstract class.

The map has three collection views, which are backed by the map (modifications on one show up on the other): a set of keys, a collection of values, and a set of key-value mappings. Some maps have a guaranteed order, but not all do.

Note: Be careful about using mutable keys. Behavior is unspecified if a key's comparison behavior is changed after the fact. As a corollary to this rule, don't use a Map as one of its own keys or values, as it makes hashCode and equals have undefined behavior.

All maps are recommended to provide a no argument constructor, which builds an empty map, and one that accepts a Map parameter and copies the mappings (usually by putAll), to create an equivalent map. Unfortunately, Java cannot enforce these suggestions.

The map may be unmodifiable, in which case unsupported operations will throw an UnsupportedOperationException. Note that some operations may be safe, such as putAll(m) where m is empty, even if the operation would normally fail with a non-empty argument.

Since:
1.2
See Also:
HashMap, TreeMap, Hashtable, SortedMap, Collection, Set

Nested Class Summary

static interface
Map.Entry
A map entry (key-value pair).

Method Summary

Set
V>> entrySet()
Returns a set view of the mappings in this Map.
void
clear()
Remove all entries from this Map (optional operation).
boolean
containsKey(Object key)
Returns true if this contains a mapping for the given key.
boolean
containsValue(Object value)
Returns true if this contains at least one mapping with the given value.
boolean
equals(Object o)
Compares the specified object with this map for equality.
V
get(Object key)
Returns the value mapped by the given key.
int
hashCode()
Returns the hash code for this map.
boolean
isEmpty()
Returns true if the map contains no mappings.
Set
keySet()
Returns a set view of the keys in this Map.
V
put(K key, V value)
Associates the given key to the given value (optional operation).
void
putAll(extends K, V> m)
Copies all entries of the given map to this one (optional operation).
V
remove(Object o)
Removes the mapping for this key if present (optional operation).
int
size()
Returns the number of key-value mappings in the map.
Collection
values()
Returns a collection (or bag) view of the values in this Map.

Method Details

V>> entrySet

public SetV>> entrySet()
Returns a set view of the mappings in this Map. Each element in the set is a Map.Entry. The set is backed by the map, so that changes in one show up in the other. Modifications made while an iterator is in progress cause undefined behavior. If the set supports removal, these methods remove the underlying mapping from the map: Iterator.remove, Set.remove, removeAll, retainAll, and clear. Element addition, via add or addAll, is not supported via this set.
Returns:
the set view of all mapping entries
See Also:
Map.Entry

clear

public void clear()
Remove all entries from this Map (optional operation).
Throws:
UnsupportedOperationException - if clear is not supported

containsKey

public boolean containsKey(Object key)
Returns true if this contains a mapping for the given key.
Parameters:
key - the key to search for
Returns:
true if the map contains the key
Throws:
ClassCastException - if the key is of an inappropriate type
NullPointerException - if key is null but the map does not permit null keys

containsValue

public boolean containsValue(Object value)
Returns true if this contains at least one mapping with the given value. In other words, returns true if a value v exists where (value == null ? v == null : value.equals(v)). This usually requires linear time.
Parameters:
value - the value to search for
Returns:
true if the map contains the value
Throws:
ClassCastException - if the type of the value is not a valid type for this map.
NullPointerException - if the value is null and the map doesn't support null values.

equals

public boolean equals(Object o)
Compares the specified object with this map for equality. Returns true if the other object is a Map with the same mappings, that is,
o instanceof Map && entrySet().equals(((Map) o).entrySet(); This allows comparison of maps, regardless of implementation.
Overrides:
equals in interface Object
Parameters:
o - the object to be compared
Returns:
true if the object equals this map

get

public V get(Object key)
Returns the value mapped by the given key. Returns null if there is no mapping. However, in Maps that accept null values, you must rely on containsKey to determine if a mapping exists.
Parameters:
key - the key to look up
Returns:
the value associated with the key, or null if key not in map
Throws:
ClassCastException - if the key is an inappropriate type
NullPointerException - if this map does not accept null keys

hashCode

public int hashCode()
Returns the hash code for this map. This is the sum of all hashcodes for each Map.Entry object in entrySet. This allows comparison of maps, regardless of implementation, and satisfies the contract of Object.hashCode.
Overrides:
hashCode in interface Object
Returns:
the hash code

isEmpty

public boolean isEmpty()
Returns true if the map contains no mappings.
Returns:
true if the map is empty

keySet

public Set keySet()
Returns a set view of the keys in this Map. The set is backed by the map, so that changes in one show up in the other. Modifications made while an iterator is in progress cause undefined behavior. If the set supports removal, these methods remove the underlying mapping from the map: Iterator.remove, Set.remove, removeAll, retainAll, and clear. Element addition, via add or addAll, is not supported via this set.
Returns:
the set view of all keys

put

public V put(K key,
             V value)
Associates the given key to the given value (optional operation). If the map already contains the key, its value is replaced. Be aware that in a map that permits null values, a null return does not always imply that the mapping was created.
Parameters:
key - the key to map
value - the value to be mapped
Returns:
the previous value of the key, or null if there was no mapping
Throws:
UnsupportedOperationException - if the operation is not supported
ClassCastException - if the key or value is of the wrong type
IllegalArgumentException - if something about this key or value prevents it from existing in this map
NullPointerException - if either the key or the value is null, and the map forbids null keys or values

putAll

public void putAll(extends K,
                   V> m)
Copies all entries of the given map to this one (optional operation). If the map already contains a key, its value is replaced.
Parameters:
m - the mapping to load into this map
Throws:
UnsupportedOperationException - if the operation is not supported
ClassCastException - if a key or value is of the wrong type
IllegalArgumentException - if something about a key or value prevents it from existing in this map
NullPointerException - if the map forbids null keys or values, or if m is null.
See Also:
put(Object, Object)

remove

public V remove(Object o)
Removes the mapping for this key if present (optional operation). If the key is not present, this returns null. Note that maps which permit null values may also return null if the key was removed.
Parameters:
Returns:
the value the key mapped to, or null if not present.
Throws:
UnsupportedOperationException - if deletion is unsupported
NullPointerException - if the key is null and this map doesn't support null keys.
ClassCastException - if the type of the key is not a valid type for this map.

size

public int size()
Returns the number of key-value mappings in the map. If there are more than Integer.MAX_VALUE mappings, return Integer.MAX_VALUE.
Returns:
the number of mappings

values

public Collection values()
Returns a collection (or bag) view of the values in this Map. The collection is backed by the map, so that changes in one show up in the other. Modifications made while an iterator is in progress cause undefined behavior. If the collection supports removal, these methods remove the underlying mapping from the map: Iterator.remove, Collection.remove, removeAll, retainAll, and clear. Element addition, via add or addAll, is not supported via this collection.
Returns:
the collection view of all values

Map.java: interface Map -- An object that maps keys to values interface Map.Entry -- an Entry in a Map Copyright (C) 1998, 2001, 2004, 2005 Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.