net.sf.jtemporal.spi
Interface TemporalSetStorage

All Known Implementing Classes:

CompactTemporalSetStorage

public interface TemporalSetStorage

Defines the contract the storage must fulfil to store and retrieve values.
You typically implement this interface to provide persistence.
TemporalSetImpl talks to the storage using this interface, in order to provide a TemporalSet implementation.

Version:

$Id: TemporalSetStorage.java,v 1.4 2005/06/11 19:59:21 tabeck Exp $

See Also:

TemporalAttributeImpl

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(Instant i, java.lang.Object value) Returns true if this storage contains a mapping for the specified value at the given instant.
boolean	containsValue(java.lang.Object value) Returns true if this storage contains one or more mappings for the specified value.
void	endAtomicOperation() Tells the storage that an atomic operation has finished.
CloseableIterator	entryIterator() Iterates over all the entries of the storage.
CloseableIterator	entryIterator(Instant instant) Returns an iterator looping over the entries contained et the given instant.
CloseableIterator	entryIterator(Period period) Iterates over all the entries of the storage that intersects the period P.
CloseableIterator	entryIterator(Period period, java.lang.Object value) Iterates over all the entries of the storage for the given value that intersects the given period.
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.
Period	getPeriodEndingAt(Instant instant, java.lang.Object value) Returns the period finishing exactly at the given instant, for the given value, if any is found.
Period	getPeriodStartingAt(Instant instant, java.lang.Object value) Returns the period starting exactly at the given instant, for the given value, if any is found.
boolean	isEmpty() Returns true if this storage does not contain entries.
boolean	isEmpty(Instant i) Returns true if this storage does not contain entries at the given instant.
Period	lastPeriod(java.lang.Object value) Returns the last (highest) period currently defined for the given value.
CloseableIterator	periodIterator(java.lang.Object value) Iterates over all the periods of the entries having the given value.
void	put(Period p, java.lang.Object value) Stores a mapping (entry, tuple, row) composed by period and value.
void	remove(Period p, java.lang.Object value) Removes a mapping (entry, tuple, row) composed by period and value previously stored.
boolean	removeValue(java.lang.Object value) Removes all the entries having the given value.
int	size() Returns the number of Period-value mappings in this map.
int	sizeAt(Instant i) Returns the number of entries, at the given instant.
int	sizeFor(java.lang.Object value) Returns the number of entries in this map whose value equals the given one.
int	sizeValues() Returns the number of distinct values in this storage.
CloseableIterator	valueIterator() Iterates over all the distinct values of the entries in the storage.
CloseableIterator	valueIterator(Instant instant) Iterates over the set of values valid at the given instant.

Method Detail

lastPeriod

Period lastPeriod(java.lang.Object value)

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

Parameters:

value - the values whose last period must be returned.

Returns:

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

Throws:

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

firstPeriod

Period firstPeriod(java.lang.Object value)

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

Parameters:

value - the values whose first period must be returned.

Returns:

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

Throws:

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

isEmpty

boolean isEmpty()

Returns true if this storage does not contain entries.

Returns:

true if this storage does not contain entries.

isEmpty

boolean isEmpty(Instant i)

Returns true if this storage does not contain entries at the given instant.

Parameters:

i - the instant to be checked

Returns:

true if this storage does not contain entries at the given instant.

containsValue

boolean containsValue(java.lang.Object value)

Returns true if this storage contains one or more mappings 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.

containsValue

boolean containsValue(Instant i,
                      java.lang.Object value)

Returns true if this storage contains a mapping for the specified value at the given instant.

Parameters:

i - the instant to be checked

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

Returns:

true if this map maps to the given value at the given instant.

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 - the instant where the value is valid

value - valid for the returned period. The returned period contains the passed instant.

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.

getPeriodEndingAt

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

Returns the period finishing exactly at the given instant, for the given value, if any is found.

Parameters:

instant - the instant the equals the entry end

value - of the entry finishing at the given instant

Returns:

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

getPeriodStartingAt

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

Returns the period starting exactly at the given instant, for the given value, if any is found.

Parameters:

instant - the instant the equals the entry end

value - of the entry starting at the given instant

Returns:

the Period 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 TemporalSetImpl at the beginning of the put(Period, Object) method, then TemporalSetImpl 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.

sizeFor

int sizeFor(java.lang.Object value)

Returns the number of entries in this map whose value equals the given one. If the there are more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.

Parameters:

value - the value of the entries to be counted

Returns:

the number of entries in this map whose value equals the given one.

sizeValues

int sizeValues()

Returns the number of distinct values in this storage. If there are more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.

Returns:

the number of distinct values in this map.

sizeAt

int sizeAt(Instant i)

Returns the number of entries, at the given instant. If there are more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.

Parameters:

i - the instant to be checked

Returns:

the number of entries intersecting the given instant.

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.

remove

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

Removes a mapping (entry, tuple, row) composed by period and value previously stored.

The period and the value must match the parameter previously used to call the put method.

Parameters:

p - the period of the entry to be removed

value - the value of the entry to be removed

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

removeValue

boolean removeValue(java.lang.Object value)

Removes all the entries having the given value.

Parameters:

value - the value of the entry to be removed

Returns:

true if the storage contained at least one entry for the given value

Throws:

java.lang.IllegalArgumentException - if value 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(Instant instant)

Returns an iterator looping over the entries contained et the given instant.

Parameters:

instant - instant whose entries are to be returned

Returns:

an iterator of instances of TimedObject

See Also:

TimedObject

entryIterator

CloseableIterator entryIterator(Period period)

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:

period - the intersecting period.

Returns:

instances of TimedObject

See Also:

TimedObject

entryIterator

CloseableIterator entryIterator(Period period,
                                java.lang.Object value)

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

Parameters:

period - the intersecting period.

value - the value to be iterated

Returns:

instances of TimedObject

See Also:

TimedObject

periodIterator

CloseableIterator periodIterator(java.lang.Object value)

Iterates over all the periods of the entries having the given value.

The instances are sorted by Comparable.compareTo(Object)

Parameters:

value - the selected value

Returns:

instances of Period

See Also:

Period

valueIterator

CloseableIterator valueIterator()

Iterates over all the distinct values of the entries in the storage.

Returns:

instances of Object

valueIterator

CloseableIterator valueIterator(Instant instant)

Iterates over the set of values valid at the given instant.
Returns a read-only iterator.

Parameters:

instant - the instant where all the returned value are valid

Returns:

instances of Object, the iterator is read-only