|
Side of Software Dated Collections Library 2.0 |
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
K
- the type of keys maintained by this dated mapV
- the type of values maintained by this dated mapD
- the type of dates used by this dated mappublic interface DatedMap<K,V,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.
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
:
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 |
---|
void clear(D from, D to)
from
- starting date (inclusive) at which this map should be clearedto
- ending date (exclusive) at which this map should be cleared
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
boolean containsKey(java.lang.Object key, D at)
true
if this dated map contains the specified key at the
specified date.
key
- key whose presence is to be testedat
- date at which this map is to be queried
true
if this dated map contains the specified key at the
specified date
java.lang.NullPointerException
- if at
is null
boolean containsKeyThroughout(java.lang.Object key, D from, D to)
true
if this dated map contains the specified key
throughout the specified date range.
key
- key whose presence is to be testedfrom
- starting date (inclusive) at which containment should be testedto
- ending date (exclusive) at which containment should be tested
true
if this dated map contains the specified key
throughout the specified date range
java.lang.IllegalArgumentException
- if from
does not precede to
java.lang.NullPointerException
- if from
or to
is null
boolean containsValue(java.lang.Object value, D at)
true
if any key maps to the specified value at the
specified date.
value
- value whose presence is to be testedat
- date at which this map is to be queried
true
if any key maps to the specified value at the
specified date
java.lang.NullPointerException
- if at
is null
boolean containsValueThroughout(java.lang.Object value, D from, D to)
true
if a key maps to the specified value
throughout the specified date range.
value
- value whose presence is to be testedfrom
- starting date (inclusive) at which containment should be testedto
- ending date (exclusive) at which containment should be tested
true
if a key maps to the specified value
throughout the specified date range
java.lang.IllegalArgumentException
- if from
does not precede to
java.lang.NullPointerException
- if from
or to
is null
DatedSet<DatedMap.Entry<K,V,D>,D> entrySet()
boolean equals(D at, DatedObject<D> obj, D objAt)
at
is equal to
obj
at objDate
.
Two maps are equivalent if they contain the same mappings.
equals
in interface DatedObject<D>
at
- date at which this object should be testedobj
- the other dated object to be compared toobjAt
- the date of the other dated object
true
if this dated map at at
equals
another dated object at objDate
java.lang.NullPointerException
- if any argument is null
boolean excludesKeyThroughout(java.lang.Object key, D from, D to)
true
if this dated map does not contain the specified key
at any date within the specified date range.
key
- key whose presence is to be testedfrom
- starting date (inclusive) at which exclusion should be testedto
- ending date (exclusive) at which exclusion should be tested
true
if this dated map does not contain key key
between from
and to
java.lang.IllegalArgumentException
- if from
does not precede to
java.lang.NullPointerException
- if from
or to
is null
boolean excludesValueThroughout(java.lang.Object value, D from, D to)
true
if no key maps to the specified value
at any date within the specified date range.
value
- value whose presence is to be testedfrom
- starting date (inclusive) at which exclusion should be testedto
- ending date (exclusive) at which exclusion should be tested
true
if no key maps to the value
at any date between from
and to
java.lang.IllegalArgumentException
- if from
does not precede to
java.lang.NullPointerException
- if from
or to
is null
DatedValue<V,D> get(java.lang.Object key)
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.
key
- key whose values are to be returned
key
V get(java.lang.Object key, D at)
null
if this dated map does not contain a mapping for the
key at that date.
key
- key whose mapping is to be retrievedat
- date at which this map is to be queried
java.lang.NullPointerException
- if at
is null
int hashCode(D at)
DatedMap
at a date is calculated the same way as in
hashCode
of java.util.Map
.
hashCode
in interface DatedObject<D>
at
- date to which the value should correspond
java.lang.NullPointerException
- if at
is null
boolean hasSizeThroughout(int size, D from, D to)
true
if the size of this dated map is greater than or equal to
the specified size throughout the specified date range.
size
- number of mappings in questionfrom
- starting date (inclusive) at which the size is to be comparedto
- ending date (exclusive) at which the size is to be compared
true
if this dated map has at least the specified size
throughout the specified date range
java.lang.IllegalArgumentException
- if size < 0
or if from
does not precede to
java.lang.NullPointerException
- if from
or to
is null
boolean isEmpty(D at)
true
if this map contains no mappings on the
specified date.
at
- date at which this map is to be queried
true
if this map contains no mappings on the
specified date
java.lang.NullPointerException
- if at
is null
boolean isEmptyThroughout(D from, D to)
true
if this map contains no mappings throughout
the specified date range.
from
- starting date (inclusive) at which to test for inclusionto
- ending date (exclusive) at which to test for inclusion
true
if this map contains no mappings in the
specified date range
java.lang.IllegalArgumentException
- if from
does not precede to
java.lang.NullPointerException
- if any of the parameters equal null
DatedSet<K,D> keySet()
DatedValue<V,D> put(K key, V value, D from, D to)
key
with value
in this dated map during
the specified date range (optional operation).
key
- key to put in this dated mapvalue
- value to map to the keyfrom
- starting date (inclusive) at which to put the mappingto
- ending date (exclusive) at which to put the mapping
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
void putAll(DatedMap<? extends K,? extends V,D> datedMap)
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.
datedMap
- mappings to put in this dated map
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
DatedValue<V,D> remove(java.lang.Object key, D from, D to)
key
- key indicating which mapping to removefrom
- starting date (inclusive) at which to remove the mappingto
- ending date (exclusive) at which to remove the mapping
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
int size(D at)
at
- date at which to return the size
java.lang.NullPointerException
- if at
is null
DatedCollection<V,D> values()
|
Side of Software Dated Collections Library 2.0 |
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |