net.wotonomy.foundation.internal
Class QueueMap

java.lang.Object
  net.wotonomy.foundation.internal.QueueMap

All Implemented Interfaces:

java.util.Map

public class QueueMap
extends java.lang.Object
implements java.util.Map

A queue based implementation of the Map interface. This class provides for all the opertions of a map, but keeps the entries in the same sequence as originally added. The first entry placed in the map will be the first entry retreived during iteration: first-in, first-out (FIFO).

Keys cannot be duplicated. If an entry is made using a key that already exists, the value for that key will be replaced with that new value. There are no such restrictions on the values. The values may be null.

Some convenience methods are provided for the queue type operations. The first key can be retreived as well as the last key. A key can be used to retreive its corresponding value from the map. A value can also be used to retreive its key from the map, however, since there may be multiple values of the same equality, the first key found will be returned.

Author:

rglista@blacksmith.com, mpowers@blacksmith.com

Nested Class Summary

static class

QueueMap.KeyValuePair This class contains a key/value pair.

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

java.util.Map.Entry<K,V>

Constructor Summary

QueueMap()
Creates an empty QueueMap.

QueueMap(java.util.Map t)
Creates a QueueMap and places the entries from the passed in map into this map.

Method Summary

void	clear() Removes all the entries from this map.
boolean	containsKey(java.lang.Object key) Tests to see if the key is contained in the map.
boolean	containsValue(java.lang.Object value) Tests to see if the value is contained in the map.
java.util.Set	entrySet() Returns a set view of the mappings contained in this map.
boolean	equals(java.lang.Object o) Compares the specified object with this map for equality.
java.lang.Object	get(java.lang.Object key) Returns the corresponding value for the given key.
java.lang.Object	getFirstKey() Returns the first key in the map.
java.lang.Object	getKeyForValue(java.lang.Object value) Returns the associated key for this value.
java.lang.Object	getLastKey() Returns the last key in the map.
java.lang.Object	getValueForKey(java.lang.Object key) Returns the corresponding value for the given key.
int	hashCode() Returns the hash code value for this map.
boolean	isEmpty() Returns true is this map contains no key-value mappings.
java.util.List	keys() Returns an ordered list of keys from the map.
java.util.Set	keySet() Returns the keys used in the map.
static void	main(java.lang.String[] argv)
java.lang.Object	put(java.lang.Object key, java.lang.Object value) Places the key/value entry into the map at the end position.
void	putAll(java.util.Map t) Places all the entries from this given map into this map.
java.lang.Object	remove(java.lang.Object key) Remove the mapping of the key and associated value from this map.
int	size() Returns the number of key/value pairs in this map.
java.lang.String	toString() Returns a string reprsentation of this class.
java.util.Collection	values() Returns an ordered list of values from the map.

Methods inherited from class java.lang.Object

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

Constructor Detail

QueueMap

public QueueMap()

Creates an empty QueueMap.

QueueMap

public QueueMap(java.util.Map t)

Creates a QueueMap and places the entries from the passed in map into this map. The order of the entries is based on however the iterator iteratated through the map entries.

Parameters:

t - A map object.

Method Detail

clear

public void clear()

Removes all the entries from this map.

Specified by:

clear in interface java.util.Map

containsKey

public boolean containsKey(java.lang.Object key)

Tests to see if the key is contained in the map. If the key is present in the map, then TRUE is returned, otherwise FALSE is returned. The equals() operation is used to determine equality.

Specified by:

containsKey in interface java.util.Map

Returns:

True if the map contains the given key, false otherwise.

containsValue

public boolean containsValue(java.lang.Object value)

Tests to see if the value is contained in the map. If the value is present in the map, then TRUE is returned, otherwise FALSE is returned. The equals() operation is used to determine equality. The value can be null and will return TRUE if null is a value in the map. If TRUE is returned, then there may be more than one values in the map.

Specified by:

containsValue in interface java.util.Map

Returns:

True if the map contains the given value, false otherwise.

entrySet

public java.util.Set entrySet()

Returns a set view of the mappings contained in this map. Each element in the returned set is a Map.Entry. The returned set is NOT backed by the map, so changes to the map are NOT reflected in the set, and vice-versa. The returned set is independent of this Map and its underlying structure.

Specified by:

entrySet in interface java.util.Map

Returns:

a set view of the mappings contained in this map.

equals

public boolean equals(java.lang.Object o)

Compares the specified object with this map for equality. Returns true if the given object is also a map and the two Maps represent the same mappings. More formally, two maps t1 and t2 represent the same mappings if t1.entrySet().equals(t2.entrySet()). This ensures that the equals method works properly across different implementations of the Map interface.

Specified by:

equals in interface java.util.Map

Overrides:

equals in class java.lang.Object

Parameters:

o - object to be compared for equality with this map.

Returns:

true if the specified object is equal to this map.

get

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

Returns the corresponding value for the given key. The returned value may be null as that is a legal value in this map. However, if the key is not contained in this map then null is also returned. Use the containsKey() method to distinguish between the two cases.

Specified by:

get in interface java.util.Map

Parameters:

key - A key into the map.

Returns:

The value corresponding to the key (can be null), or null if the key is not contained in the map.

hashCode

public int hashCode()

Returns the hash code value for this map. The hash code of a map is defined to be the sum of the hashCodes of each entry in the map's entrySet view. This ensures that t1.equals(t2) implies that t1.hashCode()==t2.hashCode() for any two maps t1 and t2, as required by the general contract of Object.hashCode.

Specified by:

hashCode in interface java.util.Map

Overrides:

hashCode in class java.lang.Object

Returns:

the hash code value for this map.

isEmpty

public boolean isEmpty()

Returns true is this map contains no key-value mappings.

Specified by:

isEmpty in interface java.util.Map

Returns:

True is this map contains no entries, false otherwise.

keySet

public java.util.Set keySet()

Returns the keys used in the map. There is no order implied in the returned set and may be different than the the order in which they were inserted.

Specified by:

keySet in interface java.util.Map

Returns:

A Set containing all the keys used in the map.

put

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

Places the key/value entry into the map at the end position. If the key already exists in the map, then its value is replaced by the new given value. The mapping does not change order in this case. The specified key cannot be null.

Specified by:

put in interface java.util.Map

Parameters:

key - The key to place into the map, cannot be null.

value - The value to associate with the key, may be null.

Returns:

Null if the key is new, the replaced value if the key already existed. (Note: If the key was null, then null is returned.)

putAll

public void putAll(java.util.Map t)

Places all the entries from this given map into this map. If the keys already exist, then there values are replaced.

Specified by:

putAll in interface java.util.Map

Parameters:

t - A map of key/value entries.

remove

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

Remove the mapping of the key and associated value from this map. Note: null is a valid value in the map.

Specified by:

remove in interface java.util.Map

Parameters:

key - A key to remove from the map, cannot be null.

Returns:

The value of the removed mapping, null if the mapping did not exist. Null could also be returned if the associated value of the key was null.

size

public int size()

Returns the number of key/value pairs in this map.

Specified by:

size in interface java.util.Map

Returns:

The number of pairs.

keys

public java.util.List keys()

Returns an ordered list of keys from the map. The order is the same as the added order of the mapped items.
NOTE: The returned list is the underlying keys list used by this class. If modification are to be made to this list, it should be cloned first.

Returns:

An ordered list of keys.

values

public java.util.Collection values()

Returns an ordered list of values from the map. The order is the same as the added order of the mapped items. NOTE: The returned list is the underlying keys list used by this class. If modification are to be made to this list, it should be cloned first.

Specified by:

values in interface java.util.Map

Returns:

An ordered list of values.

getValueForKey

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

Returns the corresponding value for the given key. The returned value may be null as that is a legal value in this map. However, if the key is not contained in this map then null is also returned. Use the containsKey() method to distinguish between the two cases.

Parameters:

key - A key into the map.

Returns:

The value corresponding to the key (can be null), or null if the key is not contained in the map.

getKeyForValue

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

Returns the associated key for this value. Since there may be more than one of the same value in the map, this returns the first key associated with this value. Null is returned if the value is not in the map.

Parameters:

value - A value that is contained in this map.

Returns:

A first key that corresponds to this value.

getFirstKey

public java.lang.Object getFirstKey()

Returns the first key in the map. If the map is empty, then null is returned.

Returns:

The first key in the map, null if there are no mappings.

getLastKey

public java.lang.Object getLastKey()

Returns the last key in the map. If the map is empty, then null is returned.

Returns:

The last key in the map, null if there are no mappings.

toString

public java.lang.String toString()

Returns a string reprsentation of this class. The contents of the map are placed in the string in its proper order.

Overrides:

toString in class java.lang.Object

main

public static void main(java.lang.String[] argv)