Side of Software
Dated Collections Library 2.0

sos.dated.util
Class HashMapByKey<K,V,D>

java.lang.Object
  extended by sos.dated.util.AbstractDatedObject<D>
      extended by sos.dated.util.AbstractDatedMap<K,V,D>
          extended by sos.dated.util.HashMapByKey<K,V,D>
Type Parameters:
K - the type of keys maintained by this dated map
V - the type of values maintained by this dated map
D - the type of dates used by this dated map
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable, DatedMap<K,V,D>, DatedObject<D>

public class HashMapByKey<K,V,D>
extends AbstractDatedMap<K,V,D>
implements DatedMap<K,V,D>, java.io.Serializable, java.lang.Cloneable

An implementation of DatedMap that indexes its keys with a java.util.HashMap, yielding fast insertions and removals. The following illustration shows a conceptual view of a small HashMapByKey where the "dates" are integers, the keys are characters, and the values are special characters:

In the above picture, the dated map contains the following entries for the following ranges:
   [1,2): {(K,$),(B,+),(M,%)}
   [3,5): {(K,+),(A,+),(B,$),(M,^)}
   [5,6): {(K,#),(M,^)}
   [6,9): {(K,#),(A,@),(B,%)}
This implementation is serializable and cloneable; however, it is not synchronized. To use it safely in a multi-threaded situation, wrap an instance of the dated map with a call to DatedCollections.synchronizedDatedMap.

Since:
1.0
See Also:
HashMapByDate, TreeMapByKey, DatedMap, DatedCollections.synchronizedDatedMap(DatedMap)

Nested Class Summary
 
Nested classes/interfaces inherited from interface sos.dated.util.DatedMap
DatedMap.Entry<K,V,D>
 
Constructor Summary
HashMapByKey()
          Creates a new instance of HashMapByKey.
HashMapByKey(DatedMap<? extends K,? extends V,D> datedMap)
          Creates a new instance of HashMapByKey from the specified dated map.
HashMapByKey(int initialCapacity)
          Creates a new instance of HashMapByKey with the specified initial capacity and default load factor (0.75).
HashMapByKey(int initialCapacity, float loadFactor)
          Creates a new instance of HashMapByKey with the specified initial capacity and load factor.
 
Method Summary
protected  void checkForComodification(int expectedModCount, D date)
          Throws a ConcurrentModificationException if the expected modification count does not equal the actual modification count for the specified date.
 java.lang.Object clone()
          Creates and returns a shallow copy of this object.
 boolean containsKey(java.lang.Object key, D at)
          Returns true if this dated map contains the specified key at the specified date.
 boolean containsKeyThroughout(java.lang.Object key, D from, D to)
          Returns true if this dated map contains the specified key throughout the specified date range.
 DateIterator<D> dateIterator(D at)
          Returns an iterator of the date ranges of when this dated object has changed, starting at the range that contains the specified date.
 DatedSet<DatedMap.Entry<K,V,D>,D> entrySet()
          Returns a modifiable view of the mappings of this dated map.
 boolean excludesKeyThroughout(java.lang.Object key, D from, D to)
          Returns true if this dated map does not contain the specified key at any date within the specified date range.
 DatedValue<V,D> get(java.lang.Object key)
          Returns the values associated with the specified key for all dates.
protected  int modCount(D at)
          Returns the modification count at the specified date.
 DatedValue<V,D> put(K key, V value, D from, D to)
          Associates key with value in this dated map during the specified date range.
 DatedValue<V,D> remove(java.lang.Object key, D from, D to)
          Removes any values associated with the specified key in the specified date range.
protected  void upModCount(D from, D to)
          Adds 1 to the modification count for the specified date range.
 
Methods inherited from class sos.dated.util.AbstractDatedMap
clear, containsValue, containsValueThroughout, equals, excludesValueThroughout, get, hashCode, hasSizeThroughout, isEmpty, isEmptyThroughout, keySet, putAll, size, toString, values
 
Methods inherited from class sos.dated.util.AbstractDatedObject
dateIterator, equals, hashCode, toString
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface sos.dated.util.DatedMap
clear, containsKey, containsKeyThroughout, containsValue, containsValueThroughout, entrySet, equals, excludesKeyThroughout, excludesValueThroughout, get, get, hashCode, hasSizeThroughout, isEmpty, isEmptyThroughout, keySet, put, putAll, remove, size, values
 
Methods inherited from interface sos.dated.util.DatedObject
dateIterator, dateIterator, equals, hashCode, toString
 

Constructor Detail

HashMapByKey

public HashMapByKey()
Creates a new instance of HashMapByKey.


HashMapByKey

public HashMapByKey(int initialCapacity)
Creates a new instance of HashMapByKey with the specified initial capacity and default load factor (0.75). The initial capacity is used to initialize the underlying java.util.HashMap, which holds all mappings across all time.

Parameters:
initialCapacity - initial capacity of the underlying hash map
Throws:
java.lang.IllegalArgumentException - if initialCapacity < 0

HashMapByKey

public HashMapByKey(int initialCapacity,
                    float loadFactor)
Creates a new instance of HashMapByKey with the specified initial capacity and load factor.

Parameters:
initialCapacity - initial capacity of the underlying hash map
loadFactor - load factor of the underlying hash map
Throws:
java.lang.IllegalArgumentException - if initialCapacity < 0 or if loadFactor <= 0.0

HashMapByKey

public HashMapByKey(DatedMap<? extends K,? extends V,D> datedMap)
Creates a new instance of HashMapByKey from the specified dated map.

Parameters:
datedMap - dated map for which to initialize this HashMapByKey
Throws:
java.lang.NullPointerException - if the parameter is null
Method Detail

clone

public java.lang.Object clone()
Creates and returns a shallow copy of this object.

Returns:
a copy of this dated map

checkForComodification

protected void checkForComodification(int expectedModCount,
                                      D date)
Throws a ConcurrentModificationException if the expected modification count does not equal the actual modification count for the specified date.

Parameters:
expectedModCount - the caller's expected modification count
date - the date in question
Throws:
java.util.ConcurrentModificationException - if the expected modification count does not equal the actual modification count for the specified date

containsKey

public boolean containsKey(java.lang.Object key,
                           D at)
Returns true if this dated map contains the specified key at the specified date.

Specified by:
containsKey in interface DatedMap<K,V,D>
Overrides:
containsKey in class AbstractDatedMap<K,V,D>
Parameters:
key - key whose presence is to be tested
at - date at which this map is to be queried
Returns:
true if this dated map contains the specified key at the specified date
Throws:
java.lang.NullPointerException - if at is null

containsKeyThroughout

public boolean containsKeyThroughout(java.lang.Object key,
                                     D from,
                                     D to)
Returns true if this dated map contains the specified key throughout the specified date range.

Specified by:
containsKeyThroughout in interface DatedMap<K,V,D>
Overrides:
containsKeyThroughout in class AbstractDatedMap<K,V,D>
Parameters:
key - key whose presence is to be tested
from - starting date (inclusive) at which containment should be tested
to - ending date (exclusive) at which containment should be tested
Returns:
true if this dated map contains the specified key throughout the specified date range
Throws:
java.lang.IllegalArgumentException - if from does not precede to
java.lang.NullPointerException - if from or to is null

dateIterator

public DateIterator<D> dateIterator(D at)
Description copied from interface: DatedObject
Returns an iterator of the date ranges of when this dated object has changed, starting at the range that contains the specified date. Throughout a range returned by the iterator, the state of the dated object must be the same. Also, the states of the dated object must be different in two consecutive ranges returned by the iterator. There are no gaps in the ranges returned by the iterator. That is, if a previous date range exists, then a call to nextFrom returns the same date as previousTo. Passing null as the argument will return an iterator positioned at the beginning of the sequence.

Specified by:
dateIterator in interface DatedObject<D>
Specified by:
dateIterator in class AbstractDatedObject<D>
Parameters:
at - date to position the iteration
Returns:
an iterator of the dates of when this dated object has changed, positioned immediately before the date range that contains the specified date

excludesKeyThroughout

public boolean excludesKeyThroughout(java.lang.Object key,
                                     D from,
                                     D to)
Returns true if this dated map does not contain the specified key at any date within the specified date range.

Specified by:
excludesKeyThroughout in interface DatedMap<K,V,D>
Overrides:
excludesKeyThroughout in class AbstractDatedMap<K,V,D>
Parameters:
key - key whose presence is to be tested
from - starting date (inclusive) at which exclusion should be tested
to - ending date (exclusive) at which exclusion should be tested
Returns:
true if this dated map does not contain key key between from and to
Throws:
java.lang.IllegalArgumentException - if from does not precede to
java.lang.NullPointerException - if if from or to is null

get

public DatedValue<V,D> get(java.lang.Object key)
Returns the values associated with the specified key for all dates.

Specified by:
get in interface DatedMap<K,V,D>
Overrides:
get in class AbstractDatedMap<K,V,D>
Parameters:
key - key whose values are to be returned
Returns:
a dated value of the values associated with key

modCount

protected int modCount(D at)
Returns the modification count at the specified date. The return value should be used to detect concurrent modifications and other programming errors. The value is only meaningful if assertions are turned on. If assertions are enabled for this class, the returned value is the number of times upModCount has been called with a date range that includes at. If assertions are not enabled, the returned value is always zero.

Parameters:
at - date to request the modification count
Returns:
the modification count at the specified date

put

public DatedValue<V,D> put(K key,
                           V value,
                           D from,
                           D to)
Associates key with value in this dated map during the specified date range.

Specified by:
put in interface DatedMap<K,V,D>
Overrides:
put in class AbstractDatedMap<K,V,D>
Parameters:
key - key to put in this dated map
value - value to map to the key
from - starting date (inclusive) at which to put the mapping
to - ending date (exclusive) at which to put the mapping
Returns:
the value(s) mapped to the specified key in the specified range before the invocation
Throws:
java.lang.IllegalArgumentException - if from does not precede to
java.lang.NullPointerException - if from or to is null

upModCount

protected void upModCount(D from,
                          D to)
Adds 1 to the modification count for the specified date range. The modification count keeps track of the number of times this dated map has been structurally modified, allowing iterators to check for concurrent modifications.

Parameters:
from - starting date (inclusive) for which to increment the count
to - ending date (exclusive) for which to increment the count

entrySet

public DatedSet<DatedMap.Entry<K,V,D>,D> entrySet()
Returns a modifiable view of the mappings of this dated map.

Specified by:
entrySet in interface DatedMap<K,V,D>
Specified by:
entrySet in class AbstractDatedMap<K,V,D>
Returns:
a dated set of the entries in this dated map

remove

public DatedValue<V,D> remove(java.lang.Object key,
                              D from,
                              D to)
Removes any values associated with the specified key in the specified date range.

Specified by:
remove in interface DatedMap<K,V,D>
Overrides:
remove in class AbstractDatedMap<K,V,D>
Parameters:
key - key indicating which mapping to remove
from - starting date (inclusive) at which to remove the mapping
to - ending date (exclusive) at which to remove the mapping
Returns:
the value(s) mapped to the specified key in the specified range before the invocation
Throws:
java.lang.IllegalArgumentException - if from does not precede to
java.lang.NullPointerException - if from or to is null

Side of Software
Dated Collections Library 2.0

Copyright 2003-09 Side of Software (SOS). All rights reserved.