/* * %W% %E% * * Copyright 2005 Sun Microsystems, Inc. All rights reserved. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms. */ package java.util; import java.util.Map.Entry; /** * This class provides a skeletal implementation of the Map * interface, to minimize the effort required to implement this interface. * *
To implement an unmodifiable map, the programmer needs only to extend this * class and provide an implementation for the entrySet method, which * returns a set-view of the map's mappings. Typically, the returned set * will, in turn, be implemented atop AbstractSet. This set should * not support the add or remove methods, and its iterator * should not support the remove method. * *
To implement a modifiable map, the programmer must additionally override * this class's put method (which otherwise throws an * UnsupportedOperationException), and the iterator returned by * entrySet().iterator() must additionally implement its * remove method. * *
The programmer should generally provide a void (no argument) and map * constructor, as per the recommendation in the Map interface * specification. * *
The documentation for each non-abstract methods in this class describes its * implementation in detail. Each of these methods may be overridden if the * map being implemented admits a more efficient implementation. * *
This class is a member of the
*
* Java Collections Framework.
*
* @param This implementation returns entrySet().size().
*/
public int size() {
return entrySet().size();
}
/**
* {@inheritDoc}
*
* This implementation returns size() == 0.
*/
public boolean isEmpty() {
return size() == 0;
}
/**
* {@inheritDoc}
*
* This implementation iterates over entrySet() searching
* for an entry with the specified value. If such an entry is found,
* true is returned. If the iteration terminates without
* finding such an entry, false is returned. Note that this
* implementation requires linear time in the size of the map.
*
* @throws ClassCastException {@inheritDoc}
* @throws NullPointerException {@inheritDoc}
*/
public boolean containsValue(Object value) {
Iterator This implementation iterates over entrySet() searching
* for an entry with the specified key. If such an entry is found,
* true is returned. If the iteration terminates without
* finding such an entry, false is returned. Note that this
* implementation requires linear time in the size of the map; many
* implementations will override this method.
*
* @throws ClassCastException {@inheritDoc}
* @throws NullPointerException {@inheritDoc}
*/
public boolean containsKey(Object key) {
Iterator This implementation iterates over entrySet() searching
* for an entry with the specified key. If such an entry is found,
* the entry's value is returned. If the iteration terminates without
* finding such an entry, null is returned. Note that this
* implementation requires linear time in the size of the map; many
* implementations will override this method.
*
* @throws ClassCastException {@inheritDoc}
* @throws NullPointerException {@inheritDoc}
*/
public V get(Object key) {
Iterator This implementation always throws an
* UnsupportedOperationException.
*
* @throws UnsupportedOperationException {@inheritDoc}
* @throws ClassCastException {@inheritDoc}
* @throws NullPointerException {@inheritDoc}
* @throws IllegalArgumentException {@inheritDoc}
*/
public V put(K key, V value) {
throw new UnsupportedOperationException();
}
/**
* {@inheritDoc}
*
* This implementation iterates over entrySet() searching for an
* entry with the specified key. If such an entry is found, its value is
* obtained with its getValue operation, the entry is removed
* from the collection (and the backing map) with the iterator's
* remove operation, and the saved value is returned. If the
* iteration terminates without finding such an entry, null is
* returned. Note that this implementation requires linear time in the
* size of the map; many implementations will override this method.
*
* Note that this implementation throws an
* UnsupportedOperationException if the entrySet
* iterator does not support the remove method and this map
* contains a mapping for the specified key.
*
* @throws UnsupportedOperationException {@inheritDoc}
* @throws ClassCastException {@inheritDoc}
* @throws NullPointerException {@inheritDoc}
*/
public V remove(Object key) {
Iterator This implementation iterates over the specified map's
* entrySet() collection, and calls this map's put
* operation once for each entry returned by the iteration.
*
* Note that this implementation throws an
* UnsupportedOperationException if this map does not support
* the put operation and the specified map is nonempty.
*
* @throws UnsupportedOperationException {@inheritDoc}
* @throws ClassCastException {@inheritDoc}
* @throws NullPointerException {@inheritDoc}
* @throws IllegalArgumentException {@inheritDoc}
*/
public void putAll(Map extends K, ? extends V> m) {
Iterator extends Entry extends K, ? extends V>> i = m.entrySet().iterator();
while (i.hasNext()) {
Entry extends K, ? extends V> e = i.next();
put(e.getKey(), e.getValue());
}
}
/**
* {@inheritDoc}
*
* This implementation calls entrySet().clear().
*
* Note that this implementation throws an
* UnsupportedOperationException if the entrySet
* does not support the clear operation.
*
* @throws UnsupportedOperationException {@inheritDoc}
*/
public void clear() {
entrySet().clear();
}
// Views
/**
* Each of these fields are initialized to contain an instance of the
* appropriate view the first time this view is requested. The views are
* stateless, so there's no reason to create more than one of each.
*/
transient volatile Set This implementation returns a set that subclasses {@link AbstractSet}.
* The subclass's iterator method returns a "wrapper object" over this
* map's entrySet() iterator. The size method
* delegates to this map's size method and the
* contains method delegates to this map's
* containsKey method.
*
* The set is created the first time this method is called,
* and returned in response to all subsequent calls. No synchronization
* is performed, so there is a slight chance that multiple calls to this
* method will not all return the same set.
*/
public Set This implementation returns a collection that subclasses {@link
* AbstractCollection}. The subclass's iterator method returns a
* "wrapper object" over this map's entrySet() iterator.
* The size method delegates to this map's size
* method and the contains method delegates to this map's
* containsValue method.
*
* The collection is created the first time this method is called, and
* returned in response to all subsequent calls. No synchronization is
* performed, so there is a slight chance that multiple calls to this
* method will not all return the same collection.
*/
public Collection This implementation first checks if the specified object is this map;
* if so it returns true. Then, it checks if the specified
* object is a map whose size is identical to the size of this map; if
* not, it returns false. If so, it iterates over this map's
* entrySet collection, and checks that the specified map
* contains each mapping that this map contains. If the specified map
* fails to contain such a mapping, false is returned. If the
* iteration completes, true is returned.
*/
public boolean equals(Object o) {
if (o == this)
return true;
if (!(o instanceof Map))
return false;
Map This implementation iterates over entrySet(), calling
* hashCode() on each element (entry) in the set, and
* adding up the results.
*
* @see Map.Entry#hashCode()
* @see Object#hashCode()
* @see Object#equals(Object)
* @see Set#equals(Object)
*/
public int hashCode() {
int h = 0;
Iterator
*
* This implementation creates an empty string buffer, appends a left
* brace, and iterates over the map's entrySet view, appending
* the string representation of each map.entry in turn. After
* appending each entry except the last, the string ", " is
* appended. Finally a right brace is appended. A string is obtained
* from the stringbuffer, and returned.
*
* @return a String representation of this map
*/
public String toString() {
StringBuffer buf = new StringBuffer();
buf.append("{");
Iterator