sos.dated.util
Interface DatedMap

All Superinterfaces:

DatedObject

All Known Subinterfaces:

DatedSortedMap

All Known Implementing Classes:

AbstractDatedMap, AbstractMapByDate, sos.dated.util.AbstractMapByKey, HashMapByDate, HashMapByKey, IdentityHashMapByDate, IdentityHashMapByKey, TreeMapByDate, TreeMapByKey

public interface DatedMap

extends DatedObject

A mapping of elements over time. It provides an interface similar to java.util.Map with the requirement that either a date or a date range be specified, depending on the type of method. A method that changes the map requires a date range, while a method that queries the map requires either a date or a date range. A non-dated map is equivalent to a dated map in which all mappings are defined from the beginning of time to the end of time.

The following table compares the efficiencies of the four implementations in this package. Each cell is the average big-Oh notation, where T denotes the number of dates in the map and N denotes the number of mappings at any given date.

	HashMapByDate	HashMapByKey	TreeMapByDate	TreeMapByKey
clear	T	T*N	T	T*N
containsKey	log(T)	log(T)	log(T)+log(N)	log(T)+log(N)
containsKeyThroughout	T	T	T*log(N)	T+log(N)
containsValue	log(T)+N	log(T)+N	log(T)+N	log(T)+N
containsValueThroughout	T*N	T*N	T*N	T*N
dateIterator	log(T)	T*N	log(T)	T*N
get	log(T)	log(T)	log(T)+log(N)	log(T)+log(N)
hashCode	T*N	T*N	T*N	T*N
hashCode(d)	log(T)+N	log(T)*N	log(T)+N	log(T)*N
put	T*N	T	T*N	T+log(N)
remove	T*N	T	T*N	T+log(N)
size	log(T)	log(T)	log(T)	log(T)

This interface is based on the interface java.util.Map. It does not extend java.util.Map directly, however, because one or more dates are needed for each operation. To make a dated map appear like a non-dated map, use Adapters.asMap(DatedMap,Date). Similarly, to treat a non-dated map as dated, use Adapters.asDatedMap(Map,Date,Date).

This interface contains additional methods that do not correspond to a method in java.util.Map:

• containsKeyThroughout(Object,Date,Date)
• containsValueThroughout(Object,Date,Date)
• excludesKeyThroughout(Object,Date,Date)
• excludesValueThroughout(Object,Date,Date)
• hasSizeThroughout(int,Date,Date)
• isEmptyThroughout(Date,Date)

Since:

1.0

See Also:

HashMapByDate, HashMapByKey, TreeMapByDate, TreeMapByKey, Adapters.asMap(DatedMap,Date), Adapters.asDatedMap(Map,Date,Date)

Nested Class Summary

static interface

DatedMap.Entry An entry in a dated map.

Field Summary

Fields inherited from interface sos.dated.util.DatedObject

MAX_DATE, MIN_DATE

Method Summary

void	clear(java.util.Date from, java.util.Date to) Removes all mappings from this dated map for the specified date range.
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.
boolean	containsValue(java.lang.Object value, java.util.Date date) Returns true if any key maps to the specified value at the specified date.
boolean	containsValueThroughout(java.lang.Object value, java.util.Date from, java.util.Date to) Returns true if a key maps to the specified value throughout the specified date range.
DatedSet	entrySet() Returns a modifiable view of the mappings of this dated map.
boolean	equals(java.util.Date date, DatedObject obj, java.util.Date objDate) Indicates if this dated map at date is equal to obj at objDate.
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.
boolean	excludesValueThroughout(java.lang.Object value, java.util.Date from, java.util.Date to) Returns true if no key maps to the specified value at any date within the specified date range.
DatedValue	get(java.lang.Object key) Returns the values associated with the specified key for all dates.
java.lang.Object	get(java.lang.Object key, java.util.Date date) Retrieves the value associated with the specified key on the specified date.
int	hashCode(java.util.Date date) Returns a hash code value of this dated map at the specified date.
boolean	hasSizeThroughout(int size, java.util.Date from, java.util.Date 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(java.util.Date date) Returns true if this map contains no mappings on the specified date.
boolean	isEmptyThroughout(java.util.Date from, java.util.Date to) Returns true if this map contains no mappings throughout the specified date range.
DatedSet	keySet() Returns a modifiable view of the keys of this dated map.
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.
void	putAll(DatedMap datedMap) Places all mappings in datedMap into this dated map.
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.
int	size(java.util.Date date) Returns the number of mappings in this dated map at the specified date.
DatedCollection	values() Returns a view of the values mapped to keys in this dated map.

Methods inherited from interface sos.dated.util.DatedObject

dateIterator, dateIterator, equals, hashCode, toString

Method Detail

clear

public void clear(java.util.Date from,
                  java.util.Date to)

Removes all mappings from this dated map for the specified date range.

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.NullPointerException - if any argument is null

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

containsKey

public boolean containsKey(java.lang.Object key,
                           java.util.Date date)

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

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

Throws:

java.lang.NullPointerException - if date is null

containsKeyThroughout

public 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.

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.NullPointerException - if from or to is null

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

containsValue

public boolean containsValue(java.lang.Object value,
                             java.util.Date date)

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

Parameters:

value - value whose presence is to be tested

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

containsValueThroughout

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

Returns true if a key maps to the specified value throughout the specified date range.

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.NullPointerException - if from or to is null

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

entrySet

public DatedSet entrySet()

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

Returns:

a dated set of the entries of this dated map

equals

public boolean equals(java.util.Date date,
                      DatedObject obj,
                      java.util.Date objDate)

Indicates if this dated map at date is equal to obj at objDate. Two maps are equivalent if they contain the same mappings.

Specified by:

equals in interface DatedObject

Parameters:

date - date at which this object should be tested

obj - the other dated object to be compared to

objDate - the date of the other dated object

Returns:

true if this dated map at date equals another dated object at objDate

Throws:

java.lang.NullPointerException - if any argument is null

excludesKeyThroughout

public 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.

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.NullPointerException - if from or to is null

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

excludesValueThroughout

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

Returns true if no key maps to the specified value at any date within the specified date range.

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.NullPointerException - if from or to is null

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

get

public DatedValue 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 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.

Parameters:

key - key whose values are to be returned

Returns:

a dated value of the values associated with key

get

public java.lang.Object get(java.lang.Object key,
                            java.util.Date date)

Retrieves the value associated with the specified key on the specified date.

Parameters:

key - key whose mapping is to be retrieved

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

hashCode

public int hashCode(java.util.Date date)

Returns a hash code value of this dated map at the specified date. The hash code of a DatedMap at a date is calculated the same way as in hashCode of java.util.Map.

Specified by:

hashCode in interface DatedObject

Parameters:

date - date to which the value should correspond

Returns:

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

Throws:

java.lang.NullPointerException - if date is null

hasSizeThroughout

public boolean hasSizeThroughout(int size,
                                 java.util.Date from,
                                 java.util.Date to)

Returns true if the size of this dated map is greater than or equal to the specified size throughout the specified date range.

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.NullPointerException - if from or to is null

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

isEmpty

public boolean isEmpty(java.util.Date date)

Returns true if this map contains no mappings on the specified date.

Parameters:

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

isEmptyThroughout

public boolean isEmptyThroughout(java.util.Date from,
                                 java.util.Date to)

Returns true if this map contains no mappings throughout the specified date range.

Parameters:

from - starting date of range (inclusive) to test for inclusion

to - ending date of range (exclusive) to test for inclusion

Returns:

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

Throws:

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

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

keySet

public DatedSet keySet()

Returns a modifiable view of the keys of this dated map.

Returns:

a dated set of the keys of this dated map

put

public 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.

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

putAll

public void putAll(DatedMap datedMap)

Places all mappings in datedMap into this dated map. 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.

Parameters:

datedMap - mappings to put in this dated map

Throws:

java.lang.NullPointerException - if datedMap is null

remove

public 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.

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

size

public int size(java.util.Date date)

Returns the number of mappings in this dated map at the specified date.

Parameters:

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

values

public DatedCollection values()

Returns a view of the values mapped to keys in this dated map.

Returns:

a modifiable dated collection of this map's values