jsimple.util

Class Map<K,V>

java.lang.Object

jsimple.util.Map<K,V>

Direct Known Subclasses:

HashMap

public abstract class Map<K,V>
extends java.lang.Object

A Map is a data structure consisting of a set of keys and values in which each key is mapped to a single value. The class of the objects used as keys is declared when the Map is declared, as is the class of the corresponding values.

A Map provides helper methods to iterate through all of the keys contained in it, as well as various methods to access and update the key/value pairs.

Changes from the java.util version:

Does not implement Serializable nor clone()

This class is an abstract implementation of the Map interface. This default implementation does not support adding. A subclass must implement the abstract method entrySet().

Since:

1.2

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Map() Constructs a new instance of this AbstractMap.

Method Summary

Modifier and Type	Method and Description
abstract void	clear() Removes all elements from this Map, leaving it empty.
abstract boolean	containsKey(K key) Returns whether this Map contains the specified key.
abstract boolean	containsValue(V value) Returns whether this Map contains the specified value.
abstract Set<MapEntry<K,V>>	entrySet() Returns a Set containing all of the mappings in this Map.
boolean	equals(java.lang.Object object) By default, equals isn't supported for maps or other collections, though subclasses can choose to override this behavior if they want.
abstract V	get(K key) Returns the value of the mapping with the specified key
int	hashCode() Returns the hash code for this object.
abstract boolean	isEmpty() Returns whether this map is empty.
abstract Set<K>	keySet() Returns a set of the keys contained in this Map.
abstract V	put(K key, V value) Maps the specified key to the specified value.
abstract void	putAll(Map<? extends K,? extends V> map) Copies every mapping in the specified Map to this Map.
abstract V	remove(K key) Removes a mapping with the specified key from this Map.
abstract int	size() Returns the number of mappings in this Map.
java.lang.String	toString() Returns the string representation of this map.
abstract Collection<V>	values() Returns a Collection of the values contained in this Map.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Map

protected Map()

Constructs a new instance of this AbstractMap.

Method Detail

entrySet

public abstract Set<MapEntry<K,V>> entrySet()

Returns a Set containing all of the mappings in this Map. Each mapping is an instance of MapEntry. As the Set is backed by this Map, changes in one will be reflected in the other.

Returns:

a set of the mappings

equals

public boolean equals(java.lang.Object object)

By default, equals isn't supported for maps or other collections, though subclasses can choose to override this behavior if they want. Instead developers should call some other, more specific, method, checking for the exact kind of equality they want.

As background: This behavior differs from the standard java.util.AbstractMaps.equals method, where two maps are considered equal if the have the same number of entries and those entries have keys and values that are equal, according to equals. That's so-called deep equality. Whereas C#, on the other hand, just does reference equality by default for maps, saying two maps are equal if they reference the same object.

There are two main reasons we differ from standard Java and don't support equals here or for other collection methods:

(a) The desired semantics are ambiguous (deep, shallow, or reference equality? should order matter? map type matter?). There's no single obvious right answer & different semantics are appropriate in different cases. (b) It's hard to implement the Java semantics and support generics, with covariance, properly and have it work with Java to C#/Swift translation. Limited C# and Swift support for covariance, especially when casting from an Object, makes it all the harder. So best to just avoid all those issues & make the developer do explicitly what they want, calling some other method.

Overrides:

equals in class java.lang.Object

Parameters:

object - the object to compare to this object.

Returns:

true if the specified object is equal to this list, false otherwise; though by default this method throws an exception and developers generally shouldn't use it

hashCode

public int hashCode()

Returns the hash code for this object. Objects which are equal must return the same value for this method.

Overrides:

hashCode in class java.lang.Object

Returns:

the hash code of this object.

See Also:

equals(Object)

toString

public java.lang.String toString()

Returns the string representation of this map. Note that this method doesn't support maps with a loop in the object graph that end up containing themselves (e.g. map that directly or indirectly points back to itself as a key or value in the map). Such maps will result in infinite recursion and ultimately a stack overflow exception.

Overrides:

toString in class java.lang.Object

Returns:

the string representation of this map.

clear

public abstract void clear()

Removes all elements from this Map, leaving it empty.

Throws:

java.lang.UnsupportedOperationException - if removing elements from this Map is not supported.

See Also:

isEmpty(), size()

containsKey

public abstract boolean containsKey(K key)

Returns whether this Map contains the specified key.

Parameters:

key - the key to search for.

Returns:

true if this map contains the specified key, false otherwise.

containsValue

public abstract boolean containsValue(V value)

Returns whether this Map contains the specified value.

Parameters:

value - the value to search for.

Returns:

true if this map contains the specified value, false otherwise.

get

public abstract V get(K key)

Returns the value of the mapping with the specified key

Parameters:

key - the key.

Returns:

the value of the mapping with the specified key, or null / default value for non-nullable value type if no mapping for the specified key is found.

isEmpty

public abstract boolean isEmpty()

Returns whether this map is empty.

Returns:

true if this map has no elements, false otherwise.

See Also:

size()

keySet

public abstract Set<K> keySet()

Returns a set of the keys contained in this Map. The Set is backed by this Map so changes to one are reflected by the other. The Set does not support adding.

Returns:

a set of the keys.

put

public abstract V put(K key,
                      V value)

Maps the specified key to the specified value.

Parameters:

key - the key.

value - the value.

Returns:

the value of any previous mapping with the specified key or null / default value for non-nullable value type if there was no mapping.

Throws:

java.lang.UnsupportedOperationException - if adding to this Map is not supported.

java.lang.ClassCastException - if the class of the key or value is inappropriate for this Map.

java.lang.IllegalArgumentException - if the key or value cannot be added to this Map.

java.lang.NullPointerException - if the key or value is null and this Map does not support null keys or values.

putAll

public abstract void putAll(Map<? extends K,? extends V> map)

Copies every mapping in the specified Map to this Map.

Parameters:

map - the Map to copy mappings from.

Throws:

java.lang.UnsupportedOperationException - if adding to this Map is not supported.

java.lang.ClassCastException - if the class of a key or a value of the specified Map is inappropriate for this Map.

java.lang.IllegalArgumentException - if a key or value cannot be added to this Map.

java.lang.NullPointerException - if a key or value is null and this Map does not support null keys or values.

remove

public abstract V remove(K key)

Removes a mapping with the specified key from this Map.

Parameters:

key - the key of the mapping to remove.

Returns:

the value of the removed mapping or null / default value for non-nullable value type if no mapping for the specified key was found

Throws:

java.lang.UnsupportedOperationException - if removing from this Map is not supported.

size

public abstract int size()

Returns the number of mappings in this Map.

Returns:

the number of mappings in this Map.

values

public abstract Collection<V> values()

Returns a Collection of the values contained in this Map. The Collection is backed by this Map so changes to one are reflected by the other. The Collection supports Collection.remove(E), Collection.removeAll(jsimple.util.Collection<E>), Collection.retainAll(jsimple.util.Collection<E>), and Collection.clear() operations, and it does not support Collection.add(E) or Collection.addAll(jsimple.util.Collection<? extends E>) operations.

This method returns a Collection which is the subclass of Collection. The Collection.iterator() method of this subclass returns a "wrapper object" over the iterator of this Map's entrySet(). The Collection.size() method wraps this Map's size() method and the Collection.contains(E) method wraps this Map's containsValue(V) method.

The collection is created when this method is called at first time and returned in response to all subsequent calls. This method may return different Collection when multiple calls to this method, since it has no synchronization performed.

Returns:

a collection of the values contained in this map.