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

java.lang.Object
  sos.dated.util.AbstractDatedObject<D>
      sos.dated.util.AbstractDatedMap<K,V,D>
          sos.dated.util.AbstractMapByDate<K,V,D>
              sos.dated.util.TreeMapByDate<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 TreeMapByDate<K,V,D>
extends AbstractMapByDate<K,V,D>
implements DatedSortedMap<K,V,D>, java.io.Serializable, java.lang.Cloneable

An implementation of DatedSortedMap that maintains a java.util.TreeMap at each date where a change occurs, yielding fast date iterations and logarithmic retrievals. The following illustration shows a conceptual view of a small TreeMapByDate where the "dates" are integers, the keys are characters, and the values are special characters:

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:

TreeMapByKey, HashMapByDate, DatedMap, DatedCollections.synchronizedDatedMap(DatedMap)

Nested Class Summary

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

DatedMap.Entry<K,V,D>

Constructor Summary

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

TreeMapByDate(java.util.Comparator<? super K> comparator)
Constructs a TreeMapByDate that uses the specified comparator to order the keys.

TreeMapByDate(DatedMap<? extends K,? extends V,D> datedMap)
Constructs a TreeMapByDate that uses the natural ordering of keys and initially contains the mappings of datedMap.

TreeMapByDate(DatedSortedMap<K,? extends V,D> datedSortedMap)
Constructs a TreeMapByDate that initially contains the entries of datedSortedMap.

Method Summary

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.
protected java.util.Map<K,V>	copyMap(java.util.Map<K,V> map, D from, D to) Returns a new TreeMap initialized with the mappings of map.
protected java.util.Map<K,V>	createMap(D from, D to) Returns a freshly created, empty TreeMap.
K	firstKey(D date) Returns the smallest key in this dated map at the specified date.
DatedSortedMap<K,V,D>	headMap(K toKey) Returns a view of this dated map of all mappings whose keys precede toKey.
K	lastKey(D date) Returns the largest key in this dated map at the specified date.
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.

Methods inherited from class sos.dated.util.AbstractMapByDate

checkForComodification, containsKey, containsValue, dateIterator, entrySet, get, modCount, put, putAll, remove, upModCount

Methods inherited from class sos.dated.util.AbstractDatedMap

clear, containsKeyThroughout, containsValueThroughout, equals, excludesKeyThroughout, excludesValueThroughout, get, hashCode, hasSizeThroughout, isEmpty, isEmptyThroughout, keySet, 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

TreeMapByDate

public TreeMapByDate()

Creates an empty TreeMapByKey that sorts its keys by their natural ordering. All keys placed in this map must implement the Comparable interface.

TreeMapByDate

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

Constructs a TreeMapByDate that uses the natural ordering of keys and initially contains the mappings of datedMap. All keys placed in this map must implement the Comparable interface.

Parameters:

datedMap - dated map with which to initialize this TreeMapByDate

Throws:

java.lang.NullPointerException - if datedMap is null.

TreeMapByDate

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

Constructs a TreeMapByDate that uses the specified comparator to order the keys. The comparator should not throw an exception for any key placed in this map. A comparator with the value null causes this map to rely on the natural ordering of the keys.

Parameters:

comparator - object used to order the keys (may be null)

TreeMapByDate

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

Constructs a TreeMapByDate that initially contains the entries of datedSortedMap. This dated map uses the specified dated map's comparator to order the keys.

Parameters:

datedSortedMap - dated sorted map with which to initialize this TreeMapByDate

Throws:

java.lang.NullPointerException - if datedSortedMap is null.

Method Detail

clone

public java.lang.Object clone()

Description copied from class: AbstractDatedMap

Creates and returns a shallow 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 AbstractMapByDate<K,V,D>

Returns:

a copy of this dated map

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)

createMap

protected java.util.Map<K,V> createMap(D from,
                                       D to)

Returns a freshly created, empty TreeMap.

Specified by:

createMap in class AbstractMapByDate<K,V,D>

Parameters:

from - start date (inclusive) for which to create the map

to - end date (exclusive) for which to create the map

Returns:

a freshly created, empty TreeMap.

copyMap

protected java.util.Map<K,V> copyMap(java.util.Map<K,V> map,
                                     D from,
                                     D to)

Returns a new TreeMap initialized with the mappings of map.

Overrides:

copyMap in class AbstractMapByDate<K,V,D>

Parameters:

map - mappings to be included in the new map

Returns:

a new TreeMap initialized with the mappings of map.

firstKey

public K firstKey(D date)

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:

date - 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 date)

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:

date - 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