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

java.lang.Object
  sos.dated.util.AbstractDatedObject<D>
      sos.dated.util.AbstractDatedMap<K,V,D>
          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