net.sf.jtemporal
Interface TemporalAttribute<V>

Type Parameters:

V - the type of the value

All Superinterfaces:

ReadableTemporalAttribute<V>

All Known Implementing Classes:

AbstractTemporalAttribute, TemporalAttributeImpl, TreeTemporalAttribute

public interface TemporalAttribute<V>
extends ReadableTemporalAttribute<V>

This is a map, whose key is a Period when adding mappings (entries) and an Instant when getting mappings.
Associates periods to zero or one object (value).
This is typically used to implement temporal associations with unary cardinality, for example Employee-Salary.
You can get the value valid at a given time by calling get(Instant).
To add a mapping, you call put(Period, Object). If another mapping already exists valid during the given period (or part of the period), the mapping is overwritten for given period.

Version:

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

Method Summary

void	clear() Removes all mappings from this map (optional operation).
boolean	containsInstant(Instant i) Returns true if this map contains a mapping for the specified Instant.
boolean	containsValue(java.lang.Object value) Returns true if this map maps one or more Periods to 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() Returns a period enclosing firstInstant() and lastInstant()
Instant	firstInstant() Returns the first (lowest) instant currently in this temporal map.
Period	firstPeriod() Returns the first (lowest) period currently in this temporal map.
V	get(Instant instant) Returns the value to which this map maps the specified Instant.
TimedObject<V>	getEntry(Instant instant) Returns the entry active at the given instant.
Period	getPeriod(Instant instant) Returns the period that has a value associated at specified instant.
boolean	isEmpty() Returns true if this map contains no Period-value mappings.
Instant	lastInstant() Returns the last (highest) instant currently in this temporal map.
Period	lastPeriod() Returns the last (highest) period currently in this temporal map.
java.util.Set<Period>	periodSet() Returns a set view of the periods contained in this map.
boolean	put(Period p, V value) Associates the specified value with the specified Period in this map (optional operation).
boolean	putAll(TemporalAttribute<? extends V> tm) Copies all of the mappings from the specified map to this map (optional operation).
boolean	remove(Period p) Removes the mapping(s) for this period from this map if present (optional operation).
int	size() Returns the number of Period-value mappings in this map.
TemporalAttribute<V>	subMap(Period p)

Method Detail

clear

void clear()

Removes all mappings from this map (optional operation).

Throws:

java.lang.UnsupportedOperationException - 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 Instant-value mappings in this map.

isEmpty

boolean isEmpty()

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

Returns:

true if this map contains no Period-value mappings.

get

V get(Instant instant)

Returns the value to which this map maps the specified Instant. Returns null if the map contains no mapping at this Instant.
WARNING: for defragmentation purposes, this method may eventually return a different instance of value that equals the value stored by put(Period).

Specified by:

get in interface ReadableTemporalAttribute<V>

Parameters:

instant - instant whose associated value is to be returned

Returns:

the value to which this map maps the specified instant.

getPeriod

Period getPeriod(Instant instant)

Returns the period that has a value associated at specified instant.

Parameters:

instant - instant whose associated enclosing period is to be returned

Returns:

the period of the entry that overlaps the specified instant. returns null if this map does not contain a mapping for the specified instant.

getEntry

TimedObject<V> getEntry(Instant instant)

Returns the entry active at the given instant.
This method is like a get(Instant) and getPeriod(Instant) in a single shot.
WARNING: for defragmentation purposes, this method may eventually return a different instance of value that equals the value stored by put(Period).

Parameters:

instant - instant whose associated entry is to be returned

Returns:

the entry active at the given instant. returns null if this map does not contain a mapping for the specified instant.

containsInstant

boolean containsInstant(Instant i)

Returns true if this map contains a mapping for the specified Instant.

Parameters:

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

Returns:

true if this map contains a mapping for the specified instant.

containsValue

boolean containsValue(java.lang.Object value)

Returns true if this map maps one or more Periods to 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 (optional operation). If the map previously contained a mapping to a period overlapping this period, the old value is replaced for the given period.
WARNING: for defragmentation purposes, get(Instant) and getEntry(Instant) may eventually return a a different instance of value that equals(value).

Parameters:

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

value - value to be associated with the specified key. 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)

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

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(TemporalAttribute<? extends V> tm)

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

Parameters:

tm - 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()

Returns a set view of the periods 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.

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

firstInstant

Instant firstInstant()

Returns the first (lowest) instant currently in this temporal map.

Returns:

the first (lowest) instant currently in this temporal map.

Throws:

java.util.NoSuchElementException - TemporalAttribute is empty.

lastInstant

Instant lastInstant()

Returns the last (highest) instant currently in this temporal map.

Returns:

the last (highest) instant currently in this temporal map.

Throws:

java.util.NoSuchElementException - TemporalAttribute is empty.

firstPeriod

Period firstPeriod()

Returns the first (lowest) period currently in this temporal map.

Returns:

the first (lowest) period currently in this temporal map.

Throws:

java.util.NoSuchElementException - TemporalAttribute is empty.

lastPeriod

Period lastPeriod()

Returns the last (highest) period currently in this temporal map.

Returns:

the last (highest) period currently in this temporal map.

Throws:

java.util.NoSuchElementException - TemporalAttribute is empty.

extent

Period extent()

Returns a period enclosing firstInstant() and lastInstant()

Returns:

new Period(firstInstant(), lastInstant())

Throws:

java.util.NoSuchElementException - TemporalAttribute is empty.

See Also:

firstInstant(), lastInstant()

subMap

TemporalAttribute<V> subMap(Period p)