org.apache.commons.collections.map
Class SingletonMap

java.lang.Object
  org.apache.commons.collections.map.SingletonMap

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, java.util.Map, BoundedMap, IterableMap, KeyValue, OrderedMap

public class SingletonMap
extends java.lang.Object
implements OrderedMap, BoundedMap, KeyValue, java.io.Serializable, java.lang.Cloneable

A Map implementation that holds a single item and is fixed size.

The single key/value pair is specified at creation. The map is fixed size so any action that would change the size is disallowed. However, the put or setValue methods can change the value associated with the key.

If trying to remove or clear the map, an UnsupportedOperationException is thrown. If trying to put a new mapping into the map, an IllegalArgumentException is thrown. The put method will only suceed if the key specified is the same as the singleton key.

The key and value can be obtained by:

• normal Map methods and views
• the MapIterator, see mapIterator()
• the KeyValue interface (just cast - no object creation)

Since:

Commons Collections 3.1

Version:

$Revision: 646777 $ $Date: 2008-04-10 13:33:15 +0100 (Thu, 10 Apr 2008) $

Author:

Stephen Colebourne

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

java.util.Map.Entry

Constructor Summary

SingletonMap()
Constructor that creates a map of null to null.

SingletonMap(KeyValue keyValue)
Constructor specifying the key and value as a KeyValue.

SingletonMap(java.util.Map.Entry mapEntry)
Constructor specifying the key and value as a MapEntry.

SingletonMap(java.util.Map map)
Constructor copying elements from another map.

SingletonMap(java.lang.Object key, java.lang.Object value)
Constructor specifying the key and value.

Method Summary

void	clear() Unsupported operation.
java.lang.Object	clone() Clones the map without cloning the key or value.
boolean	containsKey(java.lang.Object key) Checks whether the map contains the specified key.
boolean	containsValue(java.lang.Object value) Checks whether the map contains the specified value.
java.util.Set	entrySet() Gets the entrySet view of the map.
boolean	equals(java.lang.Object obj) Compares this map with another.
java.lang.Object	firstKey() Gets the first (and only) key in the map.
java.lang.Object	get(java.lang.Object key) Gets the value mapped to the key specified.
java.lang.Object	getKey() Gets the key.
java.lang.Object	getValue() Gets the value.
int	hashCode() Gets the standard Map hashCode.
boolean	isEmpty() Checks whether the map is currently empty, which it never is.
protected boolean	isEqualKey(java.lang.Object key) Compares the specified key to the stored key.
protected boolean	isEqualValue(java.lang.Object value) Compares the specified value to the stored value.
boolean	isFull() Is the map currently full, always true.
java.util.Set	keySet() Gets the unmodifiable keySet view of the map.
java.lang.Object	lastKey() Gets the last (and only) key in the map.
MapIterator	mapIterator() Gets an iterator over the map.
int	maxSize() Gets the maximum size of the map, always 1.
java.lang.Object	nextKey(java.lang.Object key) Gets the next key after the key specified, always null.
OrderedMapIterator	orderedMapIterator() Obtains an OrderedMapIterator over the map.
java.lang.Object	previousKey(java.lang.Object key) Gets the previous key before the key specified, always null.
java.lang.Object	put(java.lang.Object key, java.lang.Object value) Puts a key-value mapping into this map where the key must match the existing key.
void	putAll(java.util.Map map) Puts the values from the specified map into this map.
java.lang.Object	remove(java.lang.Object key) Unsupported operation.
java.lang.Object	setValue(java.lang.Object value) Sets the value.
int	size() Gets the size of the map, always 1.
java.lang.String	toString() Gets the map as a String.
java.util.Collection	values() Gets the unmodifiable values view of the map.

Methods inherited from class java.lang.Object

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

Constructor Detail

SingletonMap

public SingletonMap()

Constructor that creates a map of null to null.

SingletonMap

public SingletonMap(java.lang.Object key,
                    java.lang.Object value)

Constructor specifying the key and value.

Parameters:

key - the key to use

value - the value to use

SingletonMap

public SingletonMap(KeyValue keyValue)

Constructor specifying the key and value as a KeyValue.

Parameters:

keyValue - the key value pair to use

SingletonMap

public SingletonMap(java.util.Map.Entry mapEntry)

Constructor specifying the key and value as a MapEntry.

Parameters:

mapEntry - the mapEntry to use

SingletonMap

public SingletonMap(java.util.Map map)

Constructor copying elements from another map.

Parameters:

map - the map to copy, must be size 1

Throws:

java.lang.NullPointerException - if the map is null

java.lang.IllegalArgumentException - if the size is not 1

Method Detail

getKey

public java.lang.Object getKey()

Gets the key.

Specified by:

getKey in interface KeyValue

Returns:

the key

getValue

public java.lang.Object getValue()

Gets the value.

Specified by:

getValue in interface KeyValue

Returns:

the value

setValue

public java.lang.Object setValue(java.lang.Object value)

Sets the value.

Parameters:

value - the new value to set

Returns:

the old value

isFull

public boolean isFull()

Is the map currently full, always true.

Specified by:

isFull in interface BoundedMap

Returns:

true always

maxSize

public int maxSize()

Gets the maximum size of the map, always 1.

Specified by:

maxSize in interface BoundedMap

Returns:

1 always

get

public java.lang.Object get(java.lang.Object key)

Gets the value mapped to the key specified.

Specified by:

get in interface java.util.Map

Parameters:

key - the key

Returns:

the mapped value, null if no match

size

public int size()

Gets the size of the map, always 1.

Specified by:

size in interface java.util.Map

Returns:

the size of 1

isEmpty

public boolean isEmpty()

Checks whether the map is currently empty, which it never is.

Specified by:

isEmpty in interface java.util.Map

Returns:

false always

containsKey

public boolean containsKey(java.lang.Object key)

Checks whether the map contains the specified key.

Specified by:

containsKey in interface java.util.Map

Parameters:

key - the key to search for

Returns:

true if the map contains the key

containsValue

public boolean containsValue(java.lang.Object value)

Checks whether the map contains the specified value.

Specified by:

containsValue in interface java.util.Map

Parameters:

value - the value to search for

Returns:

true if the map contains the key

put

public java.lang.Object put(java.lang.Object key,
                            java.lang.Object value)

Puts a key-value mapping into this map where the key must match the existing key.

An IllegalArgumentException is thrown if the key does not match as the map is fixed size.

Specified by:

put in interface java.util.Map

Parameters:

key - the key to set, must be the key of the map

value - the value to set

Returns:

the value previously mapped to this key, null if none

Throws:

java.lang.IllegalArgumentException - if the key does not match

putAll

public void putAll(java.util.Map map)

Puts the values from the specified map into this map.

The map must be of size 0 or size 1. If it is size 1, the key must match the key of this map otherwise an IllegalArgumentException is thrown.

Specified by:

putAll in interface java.util.Map

Parameters:

map - the map to add, must be size 0 or 1, and the key must match

Throws:

java.lang.NullPointerException - if the map is null

java.lang.IllegalArgumentException - if the key does not match

remove

public java.lang.Object remove(java.lang.Object key)

Unsupported operation.

Specified by:

remove in interface java.util.Map

Parameters:

key - the mapping to remove

Returns:

the value mapped to the removed key, null if key not in map

Throws:

java.lang.UnsupportedOperationException - always

clear

public void clear()

Unsupported operation.

Specified by:

clear in interface java.util.Map

entrySet

public java.util.Set entrySet()

Gets the entrySet view of the map. Changes made via setValue affect this map. To simply iterate through the entries, use mapIterator().

Specified by:

entrySet in interface java.util.Map

Returns:

the entrySet view

keySet

public java.util.Set keySet()

Gets the unmodifiable keySet view of the map. Changes made to the view affect this map. To simply iterate through the keys, use mapIterator().

Specified by:

keySet in interface java.util.Map

Returns:

the keySet view

values

public java.util.Collection values()

Gets the unmodifiable values view of the map. Changes made to the view affect this map. To simply iterate through the values, use mapIterator().

Specified by:

values in interface java.util.Map

Returns:

the values view

mapIterator

public MapIterator mapIterator()

Gets an iterator over the map. Changes made to the iterator using setValue affect this map. The remove method is unsupported.

A MapIterator returns the keys in the map. It also provides convenient methods to get the key and value, and set the value. It avoids the need to create an entrySet/keySet/values object. It also avoids creating the Map Entry object.

Specified by:

mapIterator in interface IterableMap

Returns:

the map iterator

orderedMapIterator

public OrderedMapIterator orderedMapIterator()

Obtains an OrderedMapIterator over the map.

A ordered map iterator is an efficient way of iterating over maps in both directions.

Specified by:

orderedMapIterator in interface OrderedMap

Returns:

an ordered map iterator

firstKey

public java.lang.Object firstKey()

Gets the first (and only) key in the map.

Specified by:

firstKey in interface OrderedMap

Returns:

the key

lastKey

public java.lang.Object lastKey()

Gets the last (and only) key in the map.

Specified by:

lastKey in interface OrderedMap

Returns:

the key

nextKey

public java.lang.Object nextKey(java.lang.Object key)

Gets the next key after the key specified, always null.

Specified by:

nextKey in interface OrderedMap

Parameters:

key - the next key

Returns:

null always

previousKey

public java.lang.Object previousKey(java.lang.Object key)

Gets the previous key before the key specified, always null.

Specified by:

previousKey in interface OrderedMap

Parameters:

key - the next key

Returns:

null always

isEqualKey

protected boolean isEqualKey(java.lang.Object key)

Compares the specified key to the stored key.

Parameters:

key - the key to compare

Returns:

true if equal

isEqualValue

protected boolean isEqualValue(java.lang.Object value)

Compares the specified value to the stored value.

Parameters:

value - the value to compare

Returns:

true if equal

clone

public java.lang.Object clone()

Clones the map without cloning the key or value.

Overrides:

clone in class java.lang.Object

Returns:

a shallow clone

equals

public boolean equals(java.lang.Object obj)

Compares this map with another.

Specified by:

equals in interface java.util.Map

Overrides:

equals in class java.lang.Object

Parameters:

obj - the object to compare to

Returns:

true if equal

hashCode

public int hashCode()

Gets the standard Map hashCode.

Specified by:

hashCode in interface java.util.Map

Overrides:

hashCode in class java.lang.Object

Returns:

the hash code defined in the Map interface

toString

public java.lang.String toString()

Gets the map as a String.

Overrides:

toString in class java.lang.Object

Returns:

a string version of the map