net.sf.jtemporal.spi
Interface TemporalAttributeStorage

All Known Implementing Classes:

LazyTemporalAttributeStorage, ORMTemporalAttributeStorage, TemporalAttributeStorageProxy, TreeTemporalAttributeStorage

public interface TemporalAttributeStorage

Defines the contract the storage must fulfil to store and retrieve values.
You typically implement this interface when you want to provide persistence.
TemporalAttributeImpl talks to the storage using this interface, in order to provide a TemporalAttribute implementation.

Version:

$Id: TemporalAttributeStorage.java,v 1.4 2005/06/05 21:49:30 tabeck Exp $

See Also:

TemporalSetImpl

Method Summary

void	beginAtomicOperation() Tells the storage that the JTemporal client is calling a method that can result in multiples updates in the storage.
void	clear() Removes all the stored mappings.
boolean	containsValue(java.lang.Object value) Returns true if this map maps one or more Periods to the specified value.
boolean	containsValue(java.lang.Object value, Period range) Returns true if this map maps one or more Periods to the specified value, during the specified period.
void	endAtomicOperation() Tells the storage that an atomic operation has finished.
CloseableIterator	entryIterator() Iterates over all the entries of the storage.
CloseableIterator	entryIterator(Period p) Iterates over all the entries of the storage that intersects the period P.
Period	firstPeriod() Returns the first (lowest) period currently in this storage.
Period	firstPeriod(Period p) Returns the first (lowest) period currently in this storage, that intersects the given period.
TimedObject	getEntry(Instant instant) Returns the entry valid at the given instant, if any is found.
TimedObject	getEntryEndingAt(Instant instant) Returns the entry finishing exactly at the given instant, if any is found.
TimedObject	getEntryStartingAt(Instant instant) Returns the entry starting exactly at the given instant, if any is found.
Period	getPeriod(Instant instant) Returns the period that encloses the given instant, if any is found.
java.lang.Object	getValue(Instant instant) Returns the value to which this map maps the specified Instant.
boolean	isEmpty() Returns true if this storage does not contain objects.
boolean	isEmpty(Period p) Returns true if this storage does not contain objects intersecting the given period.
Period	lastPeriod() Returns the last (highest) period currently in this storage.
Period	lastPeriod(Period p) Returns the last (highest) period currently in this storage, that intersects the given period.
CloseableIterator	periodIterator() Iterates over all the periods of the storage.
CloseableIterator	periodIterator(Period p) Iterates over all the periods of the storage that intersects the period P.
void	put(Period p, java.lang.Object value) Stores a mapping (entry, tuple, row) composed by period and value.
void	removeEntry(Period p) Removes an entry composed by period and value previously stored.
int	removeRange(Period p) Removes all the entries whose period indersects the given period.
int	size() Returns the number of Period-value mappings in this map.
int	size(Period p) Returns the number of Period-value mappings in this map, for the given priod.

Method Detail

lastPeriod

Period lastPeriod()

Returns the last (highest) period currently in this storage.

Returns:

the last (highest) period currently in this storage.

Throws:

java.util.NoSuchElementException - if the storage is empty.

lastPeriod

Period lastPeriod(Period p)

Returns the last (highest) period currently in this storage, that intersects the given period.
Note the the returned period may be larger than p.

Parameters:

p - the intersecting period

Returns:

the last (highest) period currently in this storage.

Throws:

java.util.NoSuchElementException - if none.

firstPeriod

Period firstPeriod()

Returns the first (lowest) period currently in this storage.

Returns:

the first (lowest) period currently in this storage.

Throws:

java.util.NoSuchElementException - if this storage is empty.

firstPeriod

Period firstPeriod(Period p)

Returns the first (lowest) period currently in this storage, that intersects the given period.
Note the the returned period may be larger than p.

Parameters:

p - the intersecting period

Returns:

the first (lowest) period currently in this storage.

Throws:

java.util.NoSuchElementException - if none.

isEmpty

boolean isEmpty()

Returns true if this storage does not contain objects.

Returns:

true if this storage does not contain objects..

isEmpty

boolean isEmpty(Period p)

Returns true if this storage does not contain objects intersecting the given period.

Parameters:

p - the intersecting period

Returns:

true if this storage does not contain objects intersecting the given period.

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.

containsValue

boolean containsValue(java.lang.Object value,
                      Period range)

Returns true if this map maps one or more Periods to the specified value, during the specified period.

Parameters:

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

range - the period intersecting the value mappings

Returns:

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

getValue

java.lang.Object getValue(Instant instant)

Returns the value to which this map maps the specified Instant. Returns null if the map contains no mapping at this Instant. It is not possible to map to a null Instant.

Parameters:

instant - instant whose associated value is to be returned

Returns:

the value to which this map maps the specified instant. returns null if this map does not contain a mapping for the specified instant.

getPeriod

Period getPeriod(Instant instant)

Returns the period that encloses the given instant, if any is found.

Parameters:

instant - instant whose associated value is to be returned

Returns:

the value to which this map maps the specified instant. returns null if this map does not contain a mapping for the specified instant.

getEntry

TimedObject getEntry(Instant instant)

Returns the entry valid at the given instant, if any is found.

Parameters:

instant - instant whose associated value is to be returned

Returns:

the period and value to which this map maps the specified instant. returns null if this map does not contain a mapping for the specified instant.

getEntryEndingAt

TimedObject getEntryEndingAt(Instant instant)

Returns the entry finishing exactly at the given instant, if any is found.

Parameters:

instant - the instant the equals the entry end

Returns:

the entry ending exactly at the given instant, or null.

getEntryStartingAt

TimedObject getEntryStartingAt(Instant instant)

Returns the entry starting exactly at the given instant, if any is found.

Parameters:

instant - the instant the equals the entry end

Returns:

the entry starting exactly at the given instant, or null.

beginAtomicOperation

void beginAtomicOperation()

Tells the storage that the JTemporal client is calling a method that can result in multiples updates in the storage.
This is not exactly a transaction.
If the storage supports transactions, this method suggests to perform all the following operations inside the same transaction.
For example, this method is called by TemporalAttributeImpl at the beginning of the put(Period, Object) method, then TemporalAttributeImpl calls some times the put and remove methods, then finally it calls endAtomicOperation().
If your storage supports nested transactions, this is the inner one. Non persistent implemetations just return with no action.
Must not throw any exception (including unchecked exceptions).

See Also:

endAtomicOperation()

endAtomicOperation

void endAtomicOperation()

Tells the storage that an atomic operation has finished. If the storage supports transactions, it should commit if a transaction has been started by beginAtomicOperation().
Non persistent implemetations just return with no action.
Must not throw any exception (including unchecked exceptions).

See Also:

beginAtomicOperation()

clear

void clear()

Removes all the stored mappings.

Throws:

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

java.lang.RuntimeException - (or any other subclass) if the operation could not be performed.

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.

size

int size(Period p)

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

Parameters:

p - the intersecting period

Returns:

the number of Instant-value mappings in this map.

put

void put(Period p,
         java.lang.Object value)

Stores a mapping (entry, tuple, row) composed by period and value.
No particular check or rich semantics is expected, this method just stores.

Parameters:

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

value - value to be associated with the specified key. Cannot be null.

Throws:

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

java.lang.IllegalArgumentException - if some aspect of this period or value prevents it from being stored.

java.lang.RuntimeException - (or any other subclass) if the tuple could not be stored for other reasons.

removeEntry

void removeEntry(Period p)

Removes an entry composed by period and value previously stored.

Parameters:

p - period whose mapping is to be removed from the storage. It must exactly match the key of an existing entry.

Throws:

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

java.util.NoSuchElementException - if the entry is not found

java.lang.IllegalArgumentException - if p is null

removeRange

int removeRange(Period p)

Removes all the entries whose period indersects the given period.

Parameters:

p - the period specifying that range whose interecting entries are to be deleted.

Returns:

the number of deleted entries (or Integer.MAX_VALUE if bigger than that).

Throws:

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

java.lang.IllegalArgumentException - if p is null

entryIterator

CloseableIterator entryIterator()

Iterates over all the entries of the storage.
The instances are sorted by Period.equals(Object)

Returns:

instances of TimedObject

See Also:

TimedObject

entryIterator

CloseableIterator entryIterator(Period p)

Iterates over all the entries of the storage that intersects the period P.
Note that the CloseableIterator#remove() method, removes the whole entry, even if the entry has a period lager then the period p.
The instances are sorted by Period.equals(Object)

Parameters:

p - the intersecting period.

Returns:

instances of TimedObject

See Also:

TimedObject

periodIterator

CloseableIterator periodIterator()

Iterates over all the periods of the storage.
The instances are sorted by Period.equals(Object)

Returns:

instances of Period

See Also:

Period

periodIterator

CloseableIterator periodIterator(Period p)

Iterates over all the periods of the storage that intersects the period P.
Note that the CloseableIterator#remove() method, removes the whole entry, even if the entry has a period lager then the period p.
The instances are sorted by Period.equals(Object)

Parameters:

p - the intersecting period.

Returns:

instances of Period

See Also:

Period