Index (Frames) | Index (No Frames) | Package | Package Tree | Tree
java.util

Interface Map

java.lang.Object
|
+--java.util.Map


public interface Map

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:Authors:See Also:

Method Summary

voidclear()

Remove all entries from this Map (optional operation).
booleancontainsKey(java.lang.Object key)

Returns true if this contains a mapping for the given key.
booleancontainsValue(java.lang.Object value)

Returns true if this contains at least one mapping with the given value.
java.util.SetentrySet()

Returns a set view of the mappings in this Map.
booleanequals(java.lang.Object o)

Compares the specified object with this map for equality.
java.lang.Objectget(java.lang.Object key)

Returns the value mapped by the given key.
inthashCode()

Returns the hash code for this map.
booleanisEmpty()

Returns true if the map contains no mappings.
java.util.SetkeySet()

Returns a set view of the keys in this Map.
java.lang.Objectput(java.lang.Object key, java.lang.Object value)

Associates the given key to the given value (optional operation).
voidputAll(java.util.Map m)

Copies all entries of the given map to this one (optional operation).
java.lang.Objectremove(java.lang.Object o)

Removes the mapping for this key if present (optional operation).
intsize()

Returns the number of key-value mappings in the map.
java.util.Collectionvalues()

Returns a collection (or bag) view of the values in this Map.

Method Details

clear

public void clear()

Remove all entries from this Map (optional operation).

Throws:


containsKey

public boolean containsKey(java.lang.Object key)

Returns true if this contains a mapping for the given key.

Parameters:

Returns:

Throws:


containsValue

public boolean containsValue(java.lang.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:

Returns:


entrySet

public Set 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:

See Also:


equals

public boolean equals(java.lang.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.

Parameters:

Returns:

See Also:


get

public Object get(java.lang.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:

Returns:

Throws:

See Also:


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.

Returns:

See Also:


isEmpty

public boolean isEmpty()

Returns true if the map contains no mappings.

Returns:


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:


put

public Object put(java.lang.Object key, java.lang.Object 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:

Returns:

Throws:

See Also:


putAll

public void putAll(java.util.Map 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:

Throws:

See Also:


remove

public Object remove(java.lang.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:

Throws:


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:


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: