net.sf.jtemporal
Interface TemporalSet<V>

Type Parameters:

V - the type of the value

All Known Implementing Classes:

AbstractTemporalSet, TemporalSetImpl, TreeTemporalSet

public interface TemporalSet<V>

This is a map, whose key is a Period when adding mappings (entries) and an Instant when getting mappings.
Associates periods to a Set of objects (values).
This is typically used to implement temporal associations with non-unary cardinality, for example Employee-Skills.
You can get the Set of values valid at a given time by calling valueSet(Instant).
To add a mapping, you call put(Period, Object).

Note: the Object value (passed to many methods) must have equals and hashCode defined consistently, as described in the java.lang.Object documentation.

Version:

$Id: TemporalSet.java,v 1.9 2007/09/14 20:03:10 tabeck Exp $

Method Summary

void	clear() Removes all the mappings from this map.
boolean	contains(Instant instant, java.lang.Object value) Returns true if there is a mapping for this value at the given instant.
boolean	containsValue(java.lang.Object value) Returns true if there is a mapping for the specified value.
java.util.Set<TimedObject<V>>	entrySet() Returns a set view of the entries (instances of TimedObject) contained in this map.
Period	extent(java.lang.Object value) Return a period enclosing firstInstant(value) and lastInstantvalue()
Instant	firstInstant(java.lang.Object value) Returns the first (lowest) instant currently defined for the given value.
Period	firstPeriod(java.lang.Object value) Returns the first (lowest) period currently defined for the given value.
Period	getPeriod(Instant instant, java.lang.Object value) Returns the period of the mapping valid at the specified instant for the given value.
boolean	isEmpty() Returns true if this map contains no Period-value mappings.
boolean	isEmpty(Instant i) Returns true if this map does not contain mappings valid at the given intant.
Instant	lastInstant(java.lang.Object value) Returns the last (highest) instant currently defined for the given value.
Period	lastPeriod(java.lang.Object value) Returns the last (highest) period currently defined for the given value.
java.util.Set<Period>	periodSet(java.lang.Object value) Returns a set view of the periods contained in this map for the give value.
boolean	put(Period p, V value) Associates the specified value with the specified Period in this map.
boolean	putAll(TemporalSet<? extends V> ts) Copies all of the mappings from the specified map to this map.
boolean	remove(Period p, java.lang.Object value) Removes the mapping(s) for this period and value from this map if present.
boolean	removePeriod(Period p) Removes all the mapping(s) for this period from this map if present.
boolean	removeValue(java.lang.Object value) Removes all the mapping(s) for this value from this map if present.
int	size() Returns the number of Period-value mappings in this map.
int	sizeAt(Instant instant) Returns the number values in this map valid at the given instant.
int	sizeFor(java.lang.Object value) Returns the number of Period-value mappings in this map for the given value.
int	sizeValues() Returns the number of distinct values in this map.
java.util.Set<V>	valueSet() Returns a read-only Set containing the distinct values defined somewhen in this map.
java.util.Set<V>	valueSet(Instant instant) Returns a read-only Set containing the values defined in this map at the specified instant.

Method Detail

clear

void clear()

Removes all the mappings from this map.

Throws:

java.lang.UnsupportedOperationException - if clear is not supported by this map.

size

int size()

Returns the number of Period-value mappings in this map. If the map contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.

Returns:

the number of Period-value mappings in this map.

sizeValues

int sizeValues()

Returns the number of distinct values in this map. If the map contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.

Returns:

the number of distinct values in this map.

sizeFor

int sizeFor(java.lang.Object value)

Returns the number of Period-value mappings in this map for the given value. If the map contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.

Parameters:

value - the number of entries for the given value

Returns:

the number of Instant-value mappings in this map.

sizeAt

int sizeAt(Instant instant)

Returns the number values in this map valid at the given instant. If the map contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.

Parameters:

instant - the instant at which the counted entries are valid

Returns:

the number of entries valid at the given instant.

isEmpty

boolean isEmpty()

Returns true if this map contains no Period-value mappings.

Returns:

true if this map contains no Period-value mappings.

isEmpty

boolean isEmpty(Instant i)

Returns true if this map does not contain mappings valid at the given intant.

Parameters:

i - when this temporal set is empty

Returns:

true if this map does not contain mappings valid at the given intant.

valueSet

java.util.Set<V> valueSet(Instant instant)

Returns a read-only Set containing the values defined in this map at the specified instant. Returns an empty set if the map contains no mapping at this Instant.

Parameters:

instant - instant whose associated value is to be returned

Returns:

a read-only Set containing the values defined in this map at the specified instant.

valueSet

java.util.Set<V> valueSet()

Returns a read-only Set containing the distinct values defined somewhen in this map. Returns an empty set if the map contains no mapping at all.

Returns:

a read-only Set containing the distinct values defined somewhen in this map.

entrySet

java.util.Set<TimedObject<V>> entrySet()

Returns a set view of the entries (instances of TimedObject) contained in this map. The set is backed by the map, so changes to the map are reflected in the set, and vice-versa. If the map is modified while an iteration over the set is in progress, the results of the iteration are undefined. The set supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove, Set.remove, removeAll retainAll, and clear operations. It does not support the add or addAll operations.

Returns:

a set view of the keys contained in this map.

See Also:

TimedObject

getPeriod

Period getPeriod(Instant instant,
                 java.lang.Object value)

Returns the period of the mapping valid at the specified instant for the given value.

Parameters:

instant - when the given value is valid

value - the value of the entry valid during the returned period

Returns:

the period of the mapping valid at the specified instant for the given value. Returns null if this map does not contain a mapping for the given value at the specified instant.

contains

boolean contains(Instant instant,
                 java.lang.Object value)

Returns true if there is a mapping for this value at the given instant. Same as containsValue(Instant instant, Object value)

Parameters:

instant - instant whose presence in this map is to be tested.

value - value whose presence in this map is to be tested.

Returns:

true if there is a mapping for this value at the given instant.

containsValue

boolean containsValue(java.lang.Object value)

Returns true if there is a mapping for the specified value.

Parameters:

value - value whose presence in this map is to be tested.

Returns:

true if this map maps one or more keys to the specified value.

put

boolean put(Period p,
            V value)

Associates the specified value with the specified Period in this map. If the map previously contained a mapping to an equal value, during a period overlapping this period, the periods are merged.

Parameters:

p - period with which the specified value is to be associated.

value - value to be associated with the specified period. Be careful at the equals implementation of the value object: the result of the equals method is supposed to be immutable while it is stored in this collection.

Returns:

true if one or more previous values are overwritten partially or completely. false if there is no conflicting mapping.

Throws:

java.lang.UnsupportedOperationException - if the put operation is not supported by this map.

java.lang.ClassCastException - if the class of the specified value prevents it from being stored in this map.

java.lang.IllegalArgumentException - if some aspect of this period or value prevents it from being stored in this map. or if the period or the value is null

remove

boolean remove(Period p,
               java.lang.Object value)

Removes the mapping(s) for this period and value from this map if present.

Parameters:

p - period whose mappings are to be removed from the map.

value - value whose mapping are to be removed from the map.

Returns:

true if one or more previous values are removed partially or completely. false if there is no mapping changed.

Throws:

java.lang.UnsupportedOperationException - if the remove method is not supported by this map.

java.util.NoSuchElementException - if the value is unknown.

removeValue

boolean removeValue(java.lang.Object value)

Removes all the mapping(s) for this value from this map if present.

Parameters:

value - value whose mapping are to be removed from the map.

Returns:

trueif the TemporalSet contained the specified element.

Throws:

java.lang.UnsupportedOperationException - if the remove method is not supported by this map.

java.util.NoSuchElementException - if the value is unknown.

removePeriod

boolean removePeriod(Period p)

Removes all the mapping(s) for this period from this map if present.

Parameters:

p - period whose mappings are to be removed from the map.

Returns:

true if one or more previous values are removed partially or completely. false if there is any mapping changed.

Throws:

java.lang.UnsupportedOperationException - if the remove method is not supported by this map.

putAll

boolean putAll(TemporalSet<? extends V> ts)

Copies all of the mappings from the specified map to this map. These mappings will replace any mappings that this map had for any of the periods currently in the specified map.

Parameters:

ts - Mappings to be stored in this map.

Returns:

true if one or more previous values are overwritten partially or completely. false if there is any conflicting mapping.

Throws:

java.lang.UnsupportedOperationException - if the putAll method is not supported by this map.

java.lang.ClassCastException - if the class of a value in the specified map prevents it from being stored in this map.

java.lang.IllegalArgumentException - some aspect of a value in the specified map prevents it from being stored in this map.

periodSet

java.util.Set<Period> periodSet(java.lang.Object value)

Returns a set view of the periods contained in this map for the give value. The set is backed by the map, so changes to the map are reflected in the set, and vice-versa. If the map is modified while an iteration over the set is in progress, the results of the iteration are undefined. The set supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove, Set.remove, removeAll retainAll, and clear operations. It does not support the add or addAll operations.

Returns:

a set view of the periods contained in this map for the give value.

Throws:

java.util.NoSuchElementException - if the value is unknown.

firstInstant

Instant firstInstant(java.lang.Object value)

Returns the first (lowest) instant currently defined for the given value.

Returns:

the first (lowest) instant currently defined for the given value.

Throws:

java.util.NoSuchElementException - if the value is unknown.

lastInstant

Instant lastInstant(java.lang.Object value)

Returns the last (highest) instant currently defined for the given value.

Returns:

the last (highest) instant currently defined for the given value.

Throws:

java.util.NoSuchElementException - if the value is unknown.

firstPeriod

Period firstPeriod(java.lang.Object value)

Returns the first (lowest) period currently defined for the given value.

Returns:

the first (lowest) period currently defined for the given value.

Throws:

java.util.NoSuchElementException - if the value is unknown.

lastPeriod

Period lastPeriod(java.lang.Object value)

Returns the last (highest) period currently defined for the given value.

Returns:

the last (highest) period currently defined for the given value.

Throws:

java.util.NoSuchElementException - if the value is unknown.

extent

Period extent(java.lang.Object value)

Return a period enclosing firstInstant(value) and lastInstantvalue()

Returns:

new Period(firstInstant(value), lastInstant(value))

Throws:

java.util.NoSuchElementException - if the value is unknown.

See Also:

firstInstant(Object), lastInstant(Object)