org.dhmp.util
Class LinkedHashMultiMap

java.lang.Object
  extended byorg.dhmp.util.AbstractMap
      extended byorg.dhmp.util.HashMap
          extended byorg.dhmp.util.LinkedHashMap
              extended byorg.dhmp.util.LinkedHashMultiMap
All Implemented Interfaces:
java.lang.Cloneable, java.util.Map, java.io.Serializable

public class LinkedHashMultiMap
extends org.dhmp.util.LinkedHashMap

Author:
twilight0
See Also:
Serialized Form

Nested Class Summary
protected  class LinkedHashMultiMap.EntrySet
          Create an AbstractSet with custom implementations of those methods that can be overridden easily and efficiently.
 
Field Summary
static int ACCESS_ORDER
           
static int INSERTION_ORDER
           
static int REVERSE_ACCESS_ORDER
           
 
Constructor Summary
LinkedHashMultiMap()
          Construct a new insertion-ordered LinkedHashMultiMap with the default capacity (11) and the default load factor (0.75).
LinkedHashMultiMap(int initialCapacity)
          Construct a new insertion-ordered LinkedHashMultiMap with a specific inital capacity and default load factor of 0.75.
LinkedHashMultiMap(int initialCapacity, float loadFactor)
          Construct a new insertion-orderd LinkedHashMultiMap with a specific inital capacity and load factor.
LinkedHashMultiMap(int initialCapacity, float loadFactor, boolean accessOrder)
          Construct a new LinkedHashMultiMap with a specific inital capacity, load factor, and ordering mode.
LinkedHashMultiMap(int initialCapacity, float loadFactor, int accessFormat)
          Construct a new LinkedHashMultiMap with a specific inital capacity, load factor, and ordering mode.
LinkedHashMultiMap(java.util.Map m)
          Construct a new insertion-ordered LinkedHashMultiMap from the given Map, with initial capacity the greater of the size of m or the default of 11.
 
Method Summary
 java.lang.Object add(java.lang.Object key, java.lang.Object value)
          Puts the supplied value into the Map, mapped by the supplied key.
 void clear()
          Clears the Map so it has no keys.
 java.lang.Object clone()
          Returns a shallow clone of this HashMap.
 boolean containsKey(java.lang.Object key)
          Returns true if the supplied object equals() a key in this HashMap.
 boolean containsValue(java.lang.Object value)
          Returns true if this LinkedHashMultiMap contains a value o, such that o.equals(value).
 java.util.Set entrySet()
          Returns a "set view" of this LinkedHashMultiMap's entries.
 boolean equals(java.lang.Object o)
          Compares the specified object with this map for equality.
 org.dhmp.util.HashMap.HashEntry fetchEntry(java.lang.Object key)
          Return the value in this Map associated with the supplied key, or null if the key maps to nothing.
 int fullSize()
          Returns the number of key-value mappings currently in this Map, including repetitive keys.
 java.lang.Object get()
          Return the first value in this Map.
 java.lang.Object get(java.lang.Object key)
          Return the value in this Map associated with the supplied key, or null if the key maps to nothing.
 org.dhmp.util.HashMap.HashEntry getEntry()
          Return the first entry in this Map.
 org.dhmp.util.HashMap.HashEntry getEntry(java.lang.Object key)
          Return the value in this Map associated with the supplied key, or null if the key maps to nothing.
protected  int getState()
           
 int hashCode()
          Returns the hash code for this map.
 boolean isEmpty()
          Returns true if there are no key-value mappings currently in this Map.
 java.util.Set keySet()
          Returns a "set view" of this LinkedHashMultiMap's keys.
 java.lang.Object put(java.lang.Object key, java.lang.Object value)
          Puts the supplied value into the Map, mapped by the supplied key.
 void putAll(java.util.Map m)
          Copies all elements of the given map into this hashtable.
 java.lang.Object remove(java.lang.Object key)
          Removes a single entry from the LinkedHashMultiMap and returns the value which is mapped by the supplied key.
 java.lang.Object removeAll(java.lang.Object key)
          Removes all entries from the LinkedHashMultiMap and returns the oldest value which is mapped by the supplied key.
protected  boolean removeEldestEntry(java.util.Map.Entry eldest)
          Returns true if this map should remove the eldest entry.
 java.lang.Object removeEntry(org.dhmp.util.LinkedHashMultiMap.Entry target)
          Removes a single entry from the LinkedHashMultiMap and returns the value which is mapped by the supplied key.
protected  int setState(int state)
           
 int size()
          Returns the number of kay-value mappings currently in this Map.
 java.lang.String toString()
          Returns a String representation of this map.
 java.util.Collection values()
          Returns a "collection view" (or "bag view") of this HashMap's values.
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface java.util.Map
equals, hashCode
 

Field Detail

INSERTION_ORDER

public static final int INSERTION_ORDER
See Also:
Constant Field Values

ACCESS_ORDER

public static final int ACCESS_ORDER
See Also:
Constant Field Values

REVERSE_ACCESS_ORDER

public static final int REVERSE_ACCESS_ORDER
See Also:
Constant Field Values
Constructor Detail

LinkedHashMultiMap

public LinkedHashMultiMap()
Construct a new insertion-ordered LinkedHashMultiMap with the default capacity (11) and the default load factor (0.75).


LinkedHashMultiMap

public LinkedHashMultiMap(java.util.Map m)
Construct a new insertion-ordered LinkedHashMultiMap from the given Map, with initial capacity the greater of the size of m or the default of 11.

Every element in Map m will be put into this new HashMap, in the order of m's iterator.

Parameters:
m - a Map whose key / value pairs will be put into the new HashMap. NOTE: key / value pairs are not cloned in this constructor.
Throws:
java.lang.NullPointerException - if m is null

LinkedHashMultiMap

public LinkedHashMultiMap(int initialCapacity)
Construct a new insertion-ordered LinkedHashMultiMap with a specific inital capacity and default load factor of 0.75.

Parameters:
initialCapacity - the initial capacity of this HashMap (>= 0)
Throws:
java.lang.IllegalArgumentException - if (initialCapacity < 0)

LinkedHashMultiMap

public LinkedHashMultiMap(int initialCapacity,
                          float loadFactor)
Construct a new insertion-orderd LinkedHashMultiMap with a specific inital capacity and load factor.

Parameters:
initialCapacity - the initial capacity (>= 0)
loadFactor - the load factor (> 0, not NaN)
Throws:
java.lang.IllegalArgumentException - if (initialCapacity < 0) || ! (loadFactor > 0.0)

LinkedHashMultiMap

public LinkedHashMultiMap(int initialCapacity,
                          float loadFactor,
                          boolean accessOrder)
Construct a new LinkedHashMultiMap with a specific inital capacity, load factor, and ordering mode.

Parameters:
initialCapacity - the initial capacity (>=0)
loadFactor - the load factor (>0, not NaN)
accessOrder - true for access-order, false for insertion-order
Throws:
java.lang.IllegalArgumentException - if (initialCapacity < 0) || ! (loadFactor > 0.0)

LinkedHashMultiMap

public LinkedHashMultiMap(int initialCapacity,
                          float loadFactor,
                          int accessFormat)
Construct a new LinkedHashMultiMap with a specific inital capacity, load factor, and ordering mode.

Parameters:
initialCapacity - the initial capacity (>=0)
loadFactor - the load factor (>0, not NaN)
accessFormat - ACCESS_ORDER, INSERTION_ORDER or REVERSE_ACCESS_ORDER
Throws:
java.lang.IllegalArgumentException - if (initialCapacity < 0) || ! (loadFactor > 0.0)
Method Detail

fullSize

public int fullSize()
Returns the number of key-value mappings currently in this Map, including repetitive keys.

Returns:
the size

put

public java.lang.Object put(java.lang.Object key,
                            java.lang.Object value)
Puts the supplied value into the Map, mapped by the supplied key. The value may be retrieved by any object which equals() this key. NOTE: Since the prior value could also be null, you must first use containsKey if you want to see if you are replacing the key's mapping.

Parameters:
key - the key used to locate the value
value - the value to be stored in the HashMap
Returns:
the prior mapping of the key, or null if there was none
See Also:
add(Object, Object), get(Object), Object.equals(Object)

add

public java.lang.Object add(java.lang.Object key,
                            java.lang.Object value)
Puts the supplied value into the Map, mapped by the supplied key. The value may be retrieved by any object which equals() this key. NOTE: Since the prior value could also be null, you must first use containsKey if you want to see if you are replacing the key's mapping.

Parameters:
key - the key used to locate the value
value - the value to be stored in the HashMap
Returns:
the prior mapping of the key, or null if there was none
See Also:
add(Object, Object), get(Object), Object.equals(Object)

get

public java.lang.Object get(java.lang.Object key)
Return the value in this Map associated with the supplied key, or null if the key maps to nothing. If this is an access-ordered Map and the key is found, this performs structural modification, moving the key to the newest end of the list. NOTE: Since the value could also be null, you must use containsKey to see if this key actually maps to something. If this is an reverse-access-order, it returns the end of the list value for the key.

Parameters:
key - the key for which to fetch an associated value
Returns:
what the key maps to, if present
See Also:
add(Object, Object), put(Object, Object), HashMap.containsKey(Object)

get

public java.lang.Object get()
Return the first value in this Map. If this is an access-ordered Map, this performs structural modification, moving the value to the newest end of the list. If this is an reverse-access-order, it returns the end of the list value.

Returns:
first value in access-order or last otherwise

getEntry

public org.dhmp.util.HashMap.HashEntry getEntry(java.lang.Object key)
Return the value in this Map associated with the supplied key, or null if the key maps to nothing. If this is an access-ordered Map and the key is found, this performs structural modification, moving the key to the newest end of the list. NOTE: Since the value could also be null, you must use containsKey to see if this key actually maps to something. If this is an reverse-access-order, it returns the end of the list value for the key.

Parameters:
key - the key for which to fetch an associated value
Returns:
what the key maps to, if present
See Also:
add(Object, Object), put(Object, Object), HashMap.containsKey(Object)

getEntry

public org.dhmp.util.HashMap.HashEntry getEntry()
Return the first entry in this Map. If this is an access-ordered, this performs structural modification, moving the entry to the newest end of the list. If this is an reverse-access-order, it returns the end of the list entry.

Returns:
first entry in access-order or last entry otherwise

fetchEntry

public org.dhmp.util.HashMap.HashEntry fetchEntry(java.lang.Object key)
Return the value in this Map associated with the supplied key, or null if the key maps to nothing. It differs from getEntry because no structural modification is performed. If this is an reverse-access-order, it returns the end of the list value for the key.

Parameters:
key - the key for which to fetch an associated value
Returns:
what the key maps to, if present
See Also:
getEntry(Object)

entrySet

public java.util.Set entrySet()
Returns a "set view" of this LinkedHashMultiMap's entries. The set is backed by the LinkedHashMultiMap, so changes in one show up in the other. The set supports element removal, but not element addition.

Note that the iterators for all three views, from keySet(), entrySet(), and values(), traverse the HashMap in the same sequence.

Returns:
a set view of the entries
See Also:
keySet(), HashMap.values()

keySet

public java.util.Set keySet()
Returns a "set view" of this LinkedHashMultiMap's keys. The set is backed by the HashMap, so changes in one show up in the other. The set supports element removal, but not element addition.

Returns:
a set view of the keys
See Also:
HashMap.values(), entrySet()

removeEntry

public java.lang.Object removeEntry(org.dhmp.util.LinkedHashMultiMap.Entry target)
Removes a single entry from the LinkedHashMultiMap and returns the value which is mapped by the supplied key. If the key maps to nothing, then the LinkedHashMultiMap remains unchanged, and null is returned. NOTE: Since the value could also be null, you must use containsKey to see if you are actually removing a mapping.

Parameters:
target - the entry to be removed
Returns:
whatever the key mapped to, if present

remove

public java.lang.Object remove(java.lang.Object key)
Removes a single entry from the LinkedHashMultiMap and returns the value which is mapped by the supplied key. If the key maps to nothing, then the LinkedHashMultiMap remains unchanged, and null is returned. NOTE: Since the value could also be null, you must use containsKey to see if you are actually removing a mapping.

Parameters:
key - the key used to locate the value to remove
Returns:
whatever the key mapped to, if present

removeAll

public java.lang.Object removeAll(java.lang.Object key)
Removes all entries from the LinkedHashMultiMap and returns the oldest value which is mapped by the supplied key. If the key maps to nothing, then the LinkedHashMultiMap remains unchanged, and null is returned. NOTE: Since the value could also be null, you must use containsKey to see if you are actually removing a mapping.

Parameters:
key - the key used to locate the value to remove
Returns:
whatever the key mapped to, if present

clear

public void clear()
Clears the Map so it has no keys. This is O(1).


containsValue

public boolean containsValue(java.lang.Object value)
Returns true if this LinkedHashMultiMap contains a value o, such that o.equals(value).

Parameters:
value - the value to search for in this HashMap
Returns:
true if at least one key maps to the value
See Also:
HashMap.containsKey(Object)

toString

public java.lang.String toString()
Returns a String representation of this map. This is a listing of the map entries (which are specified in Map.Entry as being getKey() + "=" + getValue()), separated by a comma and space (", "), and surrounded by braces ('{' and '}'). This implementation uses a StringBuffer and iterates over the entrySet to build the String. Note that this can fail with an exception if underlying keys or values complete abruptly in toString().

Returns:
a String representation

getState

protected int getState()

setState

protected int setState(int state)

removeEldestEntry

protected boolean removeEldestEntry(java.util.Map.Entry eldest)
Returns true if this map should remove the eldest entry. This method is invoked by all calls to put and putAll which place a new entry in the map, providing the implementer an opportunity to remove the eldest entry any time a new one is added. This can be used to save memory usage of the hashtable, as well as emulating a cache, by deleting stale entries.

For example, to keep the Map limited to 100 entries, override as follows:

 private static final int MAX_ENTRIES = 100;
 protected boolean removeEldestEntry(Map.Entry eldest)
 {
   return size() > MAX_ENTRIES;
 }
 

Typically, this method does not modify the map, but just uses the return value as an indication to put whether to proceed. However, if you override it to modify the map, you must return false (indicating that put should leave the modified map alone), or you face unspecified behavior. Remember that in access-order mode, even calling get is a structural modification, but using the collections views (such as keySet) is not.

This method is called after the eldest entry has been inserted, so if put was called on a previously empty map, the eldest entry is the one you just put in! The default implementation just returns false, so that this map always behaves like a normal one with unbounded growth.

Parameters:
eldest - the eldest element which would be removed if this returns true. For an access-order map, this is the least recently accessed; for an insertion-order map, this is the earliest element inserted.
Returns:
true if eldest should be removed

size

public int size()
Returns the number of kay-value mappings currently in this Map.

Specified by:
size in interface java.util.Map
Returns:
the size
See Also:
Set.size()

isEmpty

public boolean isEmpty()
Returns true if there are no key-value mappings currently in this Map.

Specified by:
isEmpty in interface java.util.Map
Returns:
size() == 0
See Also:
AbstractMap.size()

containsKey

public boolean containsKey(java.lang.Object key)
Returns true if the supplied object equals() a key in this HashMap.

Specified by:
containsKey in interface java.util.Map
Parameters:
key - the key to search for in this HashMap
Returns:
true if the key is in the table
See Also:
HashMap.containsValue(Object)

putAll

public void putAll(java.util.Map m)
Copies all elements of the given map into this hashtable. If this table already has a mapping for a key, the new mapping replaces the current one.

Specified by:
putAll in interface java.util.Map
Parameters:
m - the map to be hashed into this
See Also:
AbstractMap.put(Object, Object)

clone

public java.lang.Object clone()
Returns a shallow clone of this HashMap. The Map itself is cloned, but its contents are not. This is O(n).

Returns:
the clone
See Also:
Cloneable, Object.clone()

values

public java.util.Collection values()
Returns a "collection view" (or "bag view") of this HashMap's values. The collection is backed by the HashMap, so changes in one show up in the other. The collection supports element removal, but not element addition.

Specified by:
values in interface java.util.Map
Returns:
a bag view of the values
See Also:
HashMap.keySet(), HashMap.entrySet()

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();

Specified by:
equals in interface java.util.Map
Parameters:
o - the object to be compared
Returns:
true if the object equals this map
See Also:
Set.equals(Object)

hashCode

public int hashCode()
Returns the hash code for this map. As defined in Map, this is the sum of all hashcodes for each Map.Entry object in entrySet, or basically entrySet().hashCode().

Specified by:
hashCode in interface java.util.Map
Returns:
the hash code