Side of Software
Dated Collections Library 2.0

sos.dated.util
Interface DatedMap<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 Superinterfaces:
DatedObject<D>
All Known Subinterfaces:
DatedSortedMap<K,V,D>
All Known Implementing Classes:
AbstractDatedMap, AbstractMapByDate, HashMapByDate, HashMapByKey, IdentityHashMapByDate, IdentityHashMapByKey, LinkedHashMapByDate, TreeMapByDate, TreeMapByKey

public interface DatedMap<K,V,D>
extends DatedObject<D>

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.

HashMapByDateHashMapByKeyTreeMapByDateTreeMapByKey
clearTT*NTT*N
containsKeylog(T)log(T)log(T)+log(N)log(T)+log(N)
containsKeyThroughoutTTT*log(N)T+log(N)
containsValuelog(T)+Nlog(T)+Nlog(T)+Nlog(T)+N
containsValueThroughoutT*NT*NT*NT*N
dateIteratorlog(T)T*Nlog(T)T*N
getlog(T)log(T)log(T)+log(N)log(T)+log(N)
hashCodeT*NT*NT*NT*N
hashCode(d)log(T)+Nlog(T)*Nlog(T)+Nlog(T)*N
putT*NTT*NT+log(N)
removeT*NTT*NT+log(N)
sizelog(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:

Since:
1.0
See Also:
HashMapByDate, HashMapByKey, TreeMapByDate, TreeMapByKey, Adapters.asMap(DatedMap,Object), Adapters.asDatedMap(Map,Object,Object)

Nested Class Summary
static interface DatedMap.Entry<K,V,D>
          An entry in a dated map.
 
Method Summary
 void clear(D from, D to)
          Removes all mappings from this dated map for the specified date range (optional operation).
 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.
 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 map at at is equal to obj at objDate.
 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 map 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.
 DatedCollection<V,D> 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

void clear(D from,
           D to)
Removes all mappings from this dated map for the specified date range (optional operation).

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 this dated map does not support clear

containsKey

boolean containsKey(java.lang.Object key,
                    D at)
Returns true if this dated map contains the specified key at the specified date.

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

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.

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

boolean containsValue(java.lang.Object value,
                      D at)
Returns true if any key maps to the specified value at the specified date.

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

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.

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

DatedSet<DatedMap.Entry<K,V,D>,D> entrySet()
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.

Returns:
a dated set of the entries in this dated map

equals

boolean equals(D at,
               DatedObject<D> obj,
               D objAt)
Indicates if this dated map at at is equal to obj at objDate. Two maps are equivalent if they contain the same mappings.

Specified by:
equals in interface DatedObject<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 map at at equals another dated object at objDate
Throws:
java.lang.NullPointerException - if any argument is null

excludesKeyThroughout

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.

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

excludesValueThroughout

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.

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

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.

Parameters:
key - key whose values are to be returned
Returns:
a dated value of the values associated with key

get

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.

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

int hashCode(D at)
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<D>
Parameters:
at - 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 at is null

hasSizeThroughout

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.

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

boolean isEmpty(D at)
Returns true if this map contains no mappings on the specified date.

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

boolean isEmptyThroughout(D from,
                          D to)
Returns true if this map contains no mappings throughout the specified date range.

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

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.

Returns:
a dated set of the keys of this dated map

put

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

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.ClassCastException - if the underlying type of key or value prevents it from being stored in this dated map
java.lang.IllegalArgumentException - if from does not precede to or if some property of key or value prevents it from being stored in this dated map
java.lang.NullPointerException - if from or to is null or if key or value is null and this dated collection cannot hold null keys or values
java.lang.UnsupportedOperationException - if this dated map does not support put

putAll

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.

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 this dated map does not support putAll

remove

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

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 this dated map does not support remove

size

int size(D at)
Returns the number of mappings in this dated map at the specified date.

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

values

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.

Returns:
a modifiable dated collection of this map's values

Side of Software
Dated Collections Library 2.0

Copyright 2003-09 Side of Software (SOS). All rights reserved.