sos.dated.util
Class TreeMapByKey

java.lang.Object
  |
  +--sos.dated.util.AbstractDatedObject
        |
        +--sos.dated.util.AbstractDatedMap
              |
              +--sos.dated.util.AbstractMapByKey
                    |
                    +--sos.dated.util.TreeMapByKey

All Implemented Interfaces:

java.lang.Cloneable, DatedMap, DatedObject, DatedSortedMap, java.io.Serializable

public class TreeMapByKey

extends sos.dated.util.AbstractMapByKey

implements DatedSortedMap, 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.

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 inherited from class sos.dated.util.DatedMap

DatedMap.Entry

Field Summary

Fields inherited from interface sos.dated.util.DatedObject

MAX_DATE, MIN_DATE

Constructor Summary

TreeMapByKey()
Creates a new instance of TreeMapByKey.

TreeMapByKey(java.util.Comparator comparator)
Creates a new instance of TreeMapByKey that uses the specified comparator to sort the keys.

TreeMapByKey(DatedMap datedMap)
Creates a new instance of TreeMapByKey from the specified dated map.

TreeMapByKey(DatedSortedMap datedSortedMap)
Creates a new instance of TreeMapByKey from the specified dated sorted map.

Method Summary

protected void	checkForComodification(int expectedModCount, java.util.Date 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 copy of this object.
java.util.Comparator	comparator() Returns the comparator used to sorted the keys of this dated map.
boolean	containsKey(java.lang.Object key, java.util.Date date) Returns true if this dated map contains the specified key at the specified date.
boolean	containsKeyThroughout(java.lang.Object key, java.util.Date from, java.util.Date to) Returns true if this dated map contains the specified key throughout the specified date range.
DateIterator	dateIterator(java.util.Date date) Returns an iterator of the date ranges of when this dated type has changed.
DatedSet	entrySet() Returns a modifiable view of the mappings of this dated map.
boolean	excludesKeyThroughout(java.lang.Object key, java.util.Date from, java.util.Date to) Returns true if this dated map does not contain the specified key at any date within the specified date range.
java.lang.Object	firstKey(java.util.Date date) Returns the smallest key in this dated map at the specified date.
DatedValue	get(java.lang.Object key) Returns the values associated with the specified key for all dates.
DatedSortedMap	headMap(java.lang.Object toKey) Returns a view of this dated map of all mappings whose keys precede toKey.
java.lang.Object	lastKey(java.util.Date date) Returns the largest key in this dated map at the specified date.
protected int	modCount(java.util.Date date)
DatedValue	put(java.lang.Object key, java.lang.Object value, java.util.Date from, java.util.Date to) Associates key with value in this dated map during the specified date range.
DatedValue	remove(java.lang.Object key, java.util.Date from, java.util.Date to) Removes any values associated with the specified key in the specified date range.
DatedSortedMap	subMap(java.lang.Object fromKey, java.lang.Object toKey) Returns a view of this dated map of all mappings whose keys fall between fromKey (inclusive) and toKey (exclusive).
DatedSortedMap	tailMap(java.lang.Object fromKey) Returns a view of this dated map of all mappings whose keys are greater than or equal to toKey.
protected void	upModCount(java.util.Date from, java.util.Date to)

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 a new instance of TreeMapByKey.

TreeMapByKey

public TreeMapByKey(java.util.Comparator comparator)

Creates a new instance of TreeMapByKey that uses the specified comparator to sort the keys.

TreeMapByKey

public TreeMapByKey(DatedMap datedMap)

Creates a new instance of TreeMapByKey from the specified dated map.

TreeMapByKey

public TreeMapByKey(DatedSortedMap datedSortedMap)

Creates a new instance of TreeMapByKey from the specified dated sorted map.

Method Detail

comparator

public java.util.Comparator 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

Returns:

the comparator that orders the keys (may be null)

clone

public java.lang.Object clone()

Description copied from class: AbstractDatedMap

Creates and returns a copy of this object. Subclasses that wish to be cloneable should override this method but first call their parent's clone method.

Overrides:

clone in class sos.dated.util.AbstractMapByKey

Returns:

a copy of this dated map

firstKey

public java.lang.Object firstKey(java.util.Date date)

Description copied from interface: DatedSortedMap

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

Specified by:

firstKey in interface DatedSortedMap

Parameters:

date - date for which to find the smallest key

Returns:

the smallest key at date

headMap

public DatedSortedMap headMap(java.lang.Object 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

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 java.lang.Object lastKey(java.util.Date date)

Description copied from interface: DatedSortedMap

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

Specified by:

lastKey in interface DatedSortedMap

Parameters:

date - date for which to find the largest key

Returns:

the largest key at date

subMap

public DatedSortedMap subMap(java.lang.Object fromKey,
                             java.lang.Object 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

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 tailMap(java.lang.Object fromKey)

Description copied from interface: DatedSortedMap

Returns a view of this dated map of all mappings whose keys are greater than or equal to toKey. The key toKey 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

Parameters:

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

Returns:

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

checkForComodification

protected void checkForComodification(int expectedModCount,
                                      java.util.Date 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,
                           java.util.Date date)

Description copied from interface: DatedMap

Returns true if this dated map contains the specified key at the specified date.

Specified by:

containsKey in interface DatedMap

Overrides:

containsKey in class AbstractDatedMap

Parameters:

key - key whose presence is to be tested

date - date at which this map is to be queried

Returns:

true if this dated map contains the specified key at the specified date

containsKeyThroughout

public boolean containsKeyThroughout(java.lang.Object key,
                                     java.util.Date from,
                                     java.util.Date to)

Description copied from interface: DatedMap

Returns true if this dated map contains the specified key throughout the specified date range.

Specified by:

containsKeyThroughout in interface DatedMap

Overrides:

containsKeyThroughout in class AbstractDatedMap

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

dateIterator

public DateIterator dateIterator(java.util.Date date)

Returns an iterator of the date ranges of when this dated type has changed. 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.

Specified by:

dateIterator in interface DatedObject

Specified by:

dateIterator in class AbstractDatedObject

Parameters:

date - date to position the iteration

Returns:

an iterator of the dates of when this dated type has changed.

Throws:

java.lang.IllegalArgumentException - if from does not precede to

excludesKeyThroughout

public boolean excludesKeyThroughout(java.lang.Object key,
                                     java.util.Date from,
                                     java.util.Date to)

Description copied from interface: DatedMap

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

Overrides:

excludesKeyThroughout in class AbstractDatedMap

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

get

public DatedValue get(java.lang.Object key)

Description copied from interface: DatedMap

Returns the values associated with the specified key for all dates. The returned dated value is backed by this dated map. Thus, changes to the dated value are reflected in this map and vice versa. Setting a value in the dated value is equivalent to invoking put on this map. Setting a value to null is not equivalent to removing the key from this map. A null value may mean either that the key is associated with null or that the key is not present in this map. (This behavior is consistent with the specification of get in java.util.Map).

If this map does not support put, then set of the dated value will throw an UnsupportedOperationException.

Iteration through the dates of the dated value may result in a ConcurrentModificationException if this map's dates are altered during the iteration.

Specified by:

get in interface DatedMap

Overrides:

get in class AbstractDatedMap

Parameters:

key - key whose values are to be returned

Returns:

a dated value of the values associated with key

modCount

protected int modCount(java.util.Date date)

put

public DatedValue put(java.lang.Object key,
                      java.lang.Object value,
                      java.util.Date from,
                      java.util.Date to)

Description copied from interface: DatedMap

Associates key with value in this dated map during the specified date range.

Specified by:

put in interface DatedMap

Overrides:

put in class AbstractDatedMap

Parameters:

key - key to put in this dated map

value - value to map to the key

from - starting date of the range (inclusive) to put the mapping

to - ending date of the range (exclusive) to put the mapping

Returns:

the value(s) mapped to the specified key in the specified range before the invocation

upModCount

protected void upModCount(java.util.Date from,
                          java.util.Date to)

entrySet

public DatedSet entrySet()

Description copied from interface: DatedMap

Returns a modifiable view of the mappings of this dated map. Each element of the returned view implement java.util.Map.

Specified by:

entrySet in interface DatedMap

Specified by:

entrySet in class AbstractDatedMap

Returns:

a dated set of the entries of this dated map

remove

public DatedValue remove(java.lang.Object key,
                         java.util.Date from,
                         java.util.Date to)

Description copied from interface: DatedMap

Removes any values associated with the specified key in the specified date range.

Specified by:

remove in interface DatedMap

Overrides:

remove in class AbstractDatedMap

Parameters:

key - key indicating which mapping to remove

from - starting date of the range (inclusive) to remove the mapping

to - ending date of the range (exclusive) to remove the mapping

Returns:

the value(s) mapped to the specified key in the specified range before the invocation