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

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

DatedMap<K,V,D>, DatedObject<D>

Direct Known Subclasses:

AbstractMapByDate, HashMapByKey, IdentityHashMapByKey, TreeMapByKey

public abstract class AbstractDatedMap<K,V,D>
extends AbstractDatedObject<D>
implements DatedMap<K,V,D>

A partial implementation of a dated map. This class is designed to make it easier to implement the DatedMap interface. To create an unmodifiable dated map, the client should subclass this class and implement entrySet. The set returned by this method should be unmodifiable as well. To create a modifiable dated map, the client should subclass this class, implement the put method, and return an entry set that supports clear and has an iterator that supports remove.

Since:

1.0

See Also:

DatedMap

Nested Class Summary

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

DatedMap.Entry<K,V,D>

Constructor Summary

protected

AbstractDatedMap() No-argument constructor available only to subclasses.

Method Summary

void	clear(D from, D to) Removes all mappings from this dated map for the specified date range (optional operation).
protected 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.
boolean	containsValue(java.lang.Object value, D at) Returns true if any key maps to the specified value at the specified date.
boolean	containsValueThroughout(java.lang.Object value, D from, D to) Returns true if a key maps to the specified value throughout the specified date range.
abstract DatedSet<DatedMap.Entry<K,V,D>,D>	entrySet() Returns a modifiable view of the mappings of this dated map.
boolean	equals(D at, DatedObject<D> obj, D objAt) Indicates if this dated object at at is equal to obj at objAt.
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.
boolean	excludesValueThroughout(java.lang.Object value, D from, D to) Returns true if no key maps to the specified value 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.
V	get(java.lang.Object key, D at) Retrieves the value associated with the specified key on the specified date, or null if this dated map does not contain a mapping for the key at that date.
int	hashCode(D at) Returns a hash code value of this dated object at the specified date.
boolean	hasSizeThroughout(int size, D from, D to) Returns true if the size of this dated map is greater than or equal to the specified size throughout the specified date range.
boolean	isEmpty(D at) Returns true if this map contains no mappings on the specified date.
boolean	isEmptyThroughout(D from, D to) Returns true if this map contains no mappings throughout the specified date range.
DatedSet<K,D>	keySet() Returns a modifiable view of the keys of this dated map.
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 (optional operation).
void	putAll(DatedMap<? extends K,? extends V,D> datedMap) Places all mappings in datedMap into this dated map (optional operation).
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 (optional operation).
int	size(D at) Returns the number of mappings in this dated map at the specified date.
java.lang.String	toString(D at) Returns a string representation of this dated object at the specified date.
DatedCollection<V,D>	values() Returns a view of the values mapped to keys in this dated map.

Methods inherited from class sos.dated.util.AbstractDatedObject

dateIterator, 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.DatedObject

dateIterator, dateIterator, equals, hashCode

Constructor Detail

AbstractDatedMap

protected AbstractDatedMap()

No-argument constructor available only to subclasses.

Method Detail

clear

public void clear(D from,
                  D to)

Removes all mappings from this dated map for the specified date range (optional operation). This implementation invokes clear on the dated entry set.

Specified by:

clear in interface DatedMap<K,V,D>

Parameters:

from - starting date (inclusive) at which this map should be cleared

to - ending date (exclusive) at which this map should be cleared

Throws:

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

java.lang.NullPointerException - if any argument is null

java.lang.UnsupportedOperationException - if the entry set throws this exception in clear

clone

protected java.lang.Object clone()
                          throws java.lang.CloneNotSupportedException

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 java.lang.Object

Returns:

a copy of this dated map

Throws:

java.lang.CloneNotSupportedException - if this object's class does not support the Cloneable interface.

containsKey

public boolean containsKey(java.lang.Object key,
                           D at)

Returns true if this dated map contains the specified key at the specified date. This implementation iterates through the entries at the specified date, returning true if the specified key is found.

Specified by:

containsKey in interface DatedMap<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. This implementation uses the date iterator to iterate through this map's changed states, calling containsKey at each date range.

Specified by:

containsKeyThroughout in interface DatedMap<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

containsValue

public boolean containsValue(java.lang.Object value,
                             D at)

Returns true if any key maps to the specified value at the specified date. This implementation iterates through the entries at the specified date and returns true if it encounters the specified value.

Specified by:

containsValue in interface DatedMap<K,V,D>

Parameters:

value - value whose presence is to be tested

at - date at which this map is to be queried

Returns:

true if any key maps to the specified value at the specified date

Throws:

java.lang.NullPointerException - if at is null

containsValueThroughout

public boolean containsValueThroughout(java.lang.Object value,
                                       D from,
                                       D to)

Returns true if a key maps to the specified value throughout the specified date range. This implementation invokes containsValue at the start of each date range within from and to.

Specified by:

containsValueThroughout in interface DatedMap<K,V,D>

Parameters:

value - value 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 a key maps to the specified value throughout the specified date range

Throws:

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

java.lang.NullPointerException - if from or to is null

entrySet

public abstract DatedSet<DatedMap.Entry<K,V,D>,D> entrySet()

Description copied from interface: DatedMap

Returns a modifiable view of the mappings of this dated map. The returned dated set is backed by this dated map, so changes to the dated map are reflected in the dated set and vice versa. The dated set supports removal but not insertion.

Specified by:

entrySet in interface DatedMap<K,V,D>

Returns:

a dated set of the entries in this dated map

equals

public boolean equals(D at,
                      DatedObject<D> obj,
                      D objAt)

Indicates if this dated object at at is equal to obj at objAt. This implementation uses object identity to determine equality. In other words, it returns true if

   this == obj && date.equals( objDate )

Subclasses should override this method to impose a weaker equality condition.

Two maps are equivalent if they contain the same mappings. This implementation returns true if this dated map and obj are the same references and if date equals objDate. Then it returns false if obj does not implement DatedMap. Finally, it returns true if this map's entry set and obj's entry set are equivalent at these dates.

Specified by:

equals in interface DatedMap<K,V,D>

Specified by:

equals in interface DatedObject<D>

Overrides:

equals in class AbstractDatedObject<D>

Parameters:

at - date at which this object should be tested

obj - the other dated object to be compared to

objAt - the date of the other dated object

Returns:

true if this dated object at at equals another dated object at objAt

Throws:

java.lang.NullPointerException - if any argument is null

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. This implementation uses the date iterator to iterate through this map's changed states, calling containsKey at each date range.

Specified by:

excludesKeyThroughout in interface DatedMap<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

excludesValueThroughout

public boolean excludesValueThroughout(java.lang.Object value,
                                       D from,
                                       D to)

Returns true if no key maps to the specified value at any date within the specified date range. This implementation invokes containsValue at the start of each date range within from and to.

Specified by:

excludesValueThroughout in interface DatedMap<K,V,D>

Parameters:

value - value 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 no key maps to the value at any date between from and to

Throws:

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

java.lang.NullPointerException - 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. The returned dated value is backed by this dated map. Thus, changes to the dated value are reflected in this dated 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.

This implementation returns a freshly constructed DatedValue that invokes AbstractDatedMap.this.get(K,D) in response to get(D) and AbstractDatedMap.this.put(K,V,D,D) in response to set(V,D,D). The date iterator that it returns is this map's date iterator adapted to ignore dates that do not reflect a change in the key's mapping.

Specified by:

get in interface DatedMap<K,V,D>

Parameters:

key - key whose values are to be returned

Returns:

a dated value of the values associated with key

get

public V get(java.lang.Object key,
             D at)

Retrieves the value associated with the specified key on the specified date, or null if this dated map does not contain a mapping for the key at that date.

This implementation iterates through the entry set at this date, returning the associated value if the key is found.

Specified by:

get in interface DatedMap<K,V,D>

Parameters:

key - key whose mapping is to be retrieved

at - date at which this map is to be queried

Returns:

the value associated with the specified key on the specified date

Throws:

java.lang.NullPointerException - if at is null

hashCode

public int hashCode(D at)

Returns a hash code value of this dated object at the specified date. For two dated objects o1 and o2 and two dates d1 and d2, if o1.equals( d1, o2, d2 ) returns true, then o1.hashCode( d1 ) must equal o2.hashCode( d2 ). This implementation returns the identity hash code value of this dated object.

The hash code of a DatedMap at a date is calculated the same way as in hashCode of java.util.Map. This implementation invokes hashCode(date) on the entry set.

Specified by:

hashCode in interface DatedMap<K,V,D>

Specified by:

hashCode in interface DatedObject<D>

Overrides:

hashCode in class AbstractDatedObject<D>

Parameters:

at - date to which the hash code value should correspond

Returns:

the hash code value of this dated object at the specified date

Throws:

java.lang.NullPointerException - if at is null

hasSizeThroughout

public boolean hasSizeThroughout(int size,
                                 D from,
                                 D to)

Returns true if the size of this dated map is greater than or equal to the specified size throughout the specified date range. This implementation invokes hasSizeThroughout(size,from,to) on the entry set.

Specified by:

hasSizeThroughout in interface DatedMap<K,V,D>

Parameters:

size - number of mappings in question

from - starting date (inclusive) at which the size is to be compared

to - ending date (exclusive) at which the size is to be compared

Returns:

true if this dated map has at least the specified size throughout the specified date range

Throws:

java.lang.IllegalArgumentException - if size < 0 or if from does not precede to

java.lang.NullPointerException - if from or to is null

isEmpty

public boolean isEmpty(D at)

Returns true if this map contains no mappings on the specified date. This implementation invokes isEmpty(date) on the entry set.

Specified by:

isEmpty in interface DatedMap<K,V,D>

Parameters:

at - date at which this map is to be queried

Returns:

true if this map contains no mappings on the specified date

Throws:

java.lang.NullPointerException - if at is null

isEmptyThroughout

public boolean isEmptyThroughout(D from,
                                 D to)

Returns true if this map contains no mappings throughout the specified date range. This implementation invokes isEmptyThroughout(from,to) on the entry set.

Specified by:

isEmptyThroughout in interface DatedMap<K,V,D>

Parameters:

from - starting date (inclusive) at which to test for inclusion

to - ending date (exclusive) at which to test for inclusion

Returns:

true if this map contains no mappings in the specified date range

Throws:

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

java.lang.NullPointerException - if any of the parameters equal null

keySet

public DatedSet<K,D> keySet()

Returns a modifiable view of the keys of this dated map. The returned dated set is backed by this dated map, so changes to the dated map are reflected in the dated set and vice versa. The dated set supports removal but not insertion. This implementation returns a DatedSet that implements clear and has an iterator that implements remove. All underlying actions operate on this map's entry set.

Specified by:

keySet in interface DatedMap<K,V,D>

Returns:

a dated set of the keys of this dated map

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 (optional operation). This implementation throws an UnsupportedOperationException.

Specified by:

put in interface DatedMap<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.UnsupportedOperationException - always

putAll

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

Places all mappings in datedMap into this dated map (optional operation). If this dated map and the map passed in are connected in a way that the map changes during any additions, this method is undefined. This means that this method cannot handle this as the parameter. This implementation iterates through the dates of datedMap, invoking put for each mapping and date range defined in datedMap.

Specified by:

putAll in interface DatedMap<K,V,D>

Parameters:

datedMap - mappings to put in this dated map

Throws:

java.lang.ClassCastException - if the type of a key or value of datedMap prevents it from being stored in this dated map

java.lang.IllegalArgumentException - if some property of a key or value of datedMap prevents it from being stored in this dated map

java.lang.NullPointerException - if datedMap is null or if a key or value of datedMap is null and this dated collection cannot hold null keys or values

java.lang.UnsupportedOperationException - if the implementation does not support put

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 (optional operation). This implementation iterates through the entry set at each date between from and to and invokes remove on the iterator at the first occurrence of an entry with the key key.

Specified by:

remove in interface DatedMap<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.ClassCastException - if the underlying type of key prevents it from being removed from this dated map

java.lang.IllegalArgumentException - if from does not precede to or if some property of key prevents it from being removed from this dated map

java.lang.NullPointerException - if from or to is null or if key is null and this dated map cannot hold null keys

java.lang.UnsupportedOperationException - if entry set's iterator throws this exception on removal

size

public int size(D at)

Returns the number of mappings in this dated map at the specified date. This implementation invokes size(at) on the entry set.

Specified by:

size in interface DatedMap<K,V,D>

Parameters:

at - date at which to return the size

Returns:

the number of entries in this dated map at the specified date

Throws:

java.lang.NullPointerException - if at is null

toString

public java.lang.String toString(D at)

Returns a string representation of this dated object at the specified date. This implementation invokes toString(at) on the entry set.

Specified by:

toString in interface DatedObject<D>

Specified by:

toString in class AbstractDatedObject<D>

Parameters:

at - date to which the string should correspond

Returns:

a string representation of this dated object

Throws:

java.lang.NullPointerException - if at is null

values

public DatedCollection<V,D> values()

Returns a view of the values mapped to keys in this dated map. The returned dated collection is backed by this dated map, so changes to the dated map are reflected in the dated collection and vice versa. The dated collection supports removal but not insertion. This implementation returns a dated collection that supports clear and has an iterator that supports remove. All underlying actions operate on this map's entry set.

Specified by:

values in interface DatedMap<K,V,D>

Returns:

a modifiable dated collection of this map's values