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

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

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

An implementation of DatedSortedMap that uses an underlying TreeMap to keep all keys in sorted order and to achieve fast access to all keys.

The following illustration shows a conceptual view of a small TreeMapByKey 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): {(B,+),(K,$),(M,%)}
   [3,5): {(A,+),(B,$),(K,+),(M,^)}
   [5,6): {(K,#),(M,^)}
   [6,9): {(A,@),(B,%),(K,#)}

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:

TreeMapByDate, HashMapByKey, DatedMap, DatedCollections.synchronizedDatedMap(DatedMap)

Nested Class Summary

Nested classes/interfaces inherited from interface sos.dated.util.DatedMap

DatedMap.Entry<K,V,D>

Constructor Summary

TreeMapByKey()
Creates an empty TreeMapByKey that sorts its keys by their natural ordering.

TreeMapByKey(java.util.Comparator<? super K> comparator)
Creates an empty TreeMapByKey that uses the specified comparator to sort the keys.

TreeMapByKey(DatedMap<? extends K,? extends V,D> datedMap)
Creates a TreeMapByKey containing the entries and date ranges of the specified dated map, sorted by the keys' natural ordering.

TreeMapByKey(DatedSortedMap<K,? extends V,D> datedSortedMap)
Creates a TreeMapByKey containing the entries and date ranges of the specified dated sorted map, ordered by the parameter's comparator object.

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.
java.util.Comparator<? super K>	comparator() Returns the comparator used to sorted the keys of this dated map.
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.
K	firstKey(D at) Returns the smallest key in this dated map at the specified date.
DatedValue<V,D>	get(java.lang.Object key) Returns the values associated with the specified key for all dates.
DatedSortedMap<K,V,D>	headMap(K toKey) Returns a view of this dated map of all mappings whose keys precede toKey.
K	lastKey(D at) Returns the largest key in this dated map at the specified date.
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.
DatedSortedMap<K,V,D>	subMap(K fromKey, K toKey) Returns a view of this dated map of all mappings whose keys fall between fromKey (inclusive) and toKey (exclusive).
DatedSortedMap<K,V,D>	tailMap(K fromKey) Returns a view of this dated map of all mappings whose keys are greater than or equal to fromKey.
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

TreeMapByKey

public TreeMapByKey()

Creates an empty TreeMapByKey that sorts its keys by their natural ordering.

TreeMapByKey

public TreeMapByKey(java.util.Comparator<? super K> comparator)

Creates an empty TreeMapByKey that uses the specified comparator to sort the keys. If the comparator is null, then the keys' natural ordering is used.

Parameters:

comparator - object to use to sort the keys (may be null)

TreeMapByKey

public TreeMapByKey(DatedMap<? extends K,? extends V,D> datedMap)

Creates a TreeMapByKey containing the entries and date ranges of the specified dated map, sorted by the keys' natural ordering.

Parameters:

datedMap - entries and corresponding date ranges to store in the new TreeMapByKey

Throws:

java.lang.NullPointerException - if the parameter is null

TreeMapByKey

public TreeMapByKey(DatedSortedMap<K,? extends V,D> datedSortedMap)

Creates a TreeMapByKey containing the entries and date ranges of the specified dated sorted map, ordered by the parameter's comparator object.

Parameters:

datedSortedMap - entries and corresponding date ranges to store in the new TreeMapByKey

Throws:

java.lang.NullPointerException - if the parameter is null

Method Detail

comparator

public java.util.Comparator<? super K> comparator()

Description copied from interface: DatedSortedMap

Returns the comparator used to sorted the keys of this dated map. A returned null value indicates that this dated map uses the keys' natural ordering.

Specified by:

comparator in interface DatedSortedMap<K,V,D>

Returns:

the comparator that orders the keys (may be null)

clone

public java.lang.Object clone()

Creates and returns a shallow copy of this object.

Returns:

a copy of this dated map

firstKey

public K firstKey(D at)

Description copied from interface: DatedSortedMap

Returns the smallest key in this dated map at the specified date.

Specified by:

firstKey in interface DatedSortedMap<K,V,D>

Parameters:

at - date for which to find the smallest key

Returns:

the smallest key at at

headMap

public DatedSortedMap<K,V,D> headMap(K toKey)

Description copied from interface: DatedSortedMap

Returns a view of this dated map of all mappings whose keys precede toKey. The key toKey does not have to appear in this dated map nor will it ever appear in the returned map. The returned map is a fully functional dated sorted map that is tied to this map. Changes to either will be reflected in the other. Any attempt to add a key greater than or equal to toKey will throw an IllegalArgumentException.

Specified by:

headMap in interface DatedSortedMap<K,V,D>

Parameters:

toKey - upper bound of the keys of the returned map (exclusive)

Returns:

the front portion of this ordered dated map up to, but not including, the specified key

lastKey

public K lastKey(D at)

Description copied from interface: DatedSortedMap

Returns the largest key in this dated map at the specified date.

Specified by:

lastKey in interface DatedSortedMap<K,V,D>

Parameters:

at - date for which to find the largest key

Returns:

the largest key at at

subMap

public DatedSortedMap<K,V,D> subMap(K fromKey,
                                    K toKey)

Description copied from interface: DatedSortedMap

Returns a view of this dated map of all mappings whose keys fall between fromKey (inclusive) and toKey (exclusive). Neither key has to appear in this dated map. The returned map is a fully functional dated sorted map that is closely tied to this map. Changes to either will be reflected in the other. Any attempt to add a key outside the specified key range will throw an IllegalArgumentException.

Specified by:

subMap in interface DatedSortedMap<K,V,D>

Parameters:

fromKey - lower bound of the keys of the returned map (inclusive)

toKey - upper bound of the keys of the returned map (exclusive)

Returns:

the middle portion of this ordered dated map from fromKey (inclusive) to toKey (exclusive)

tailMap

public DatedSortedMap<K,V,D> tailMap(K fromKey)

Description copied from interface: DatedSortedMap

Returns a view of this dated map of all mappings whose keys are greater than or equal to fromKey. The key fromKey does not have to appear in this dated map. The returned map is a fully functional dated sorted map that is closely tied to this map. Changes to either will be reflected in the other. Any attempt to add a key less than fromKey will throw an IllegalArgumentException.

Specified by:

tailMap in interface DatedSortedMap<K,V,D>

Parameters:

fromKey - lower bound of the keys of the returned map (inclusive)

Returns:

the back portion of this ordered dated map starting from the specified key

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