ch.agent.crnickl.api

Interface Series<T>

Type Parameters:

T - the class of the elements of the underlying time series

All Superinterfaces:

DBObject

All Known Subinterfaces:

UpdatableSeries<T>

All Known Implementing Classes:

SeriesImpl, UpdatableSeriesImpl

public interface Series<T>
extends DBObject

A Series provides access to a time series of values of some type. A series belongs to a Chronicle and has three required Attributes: a name, a value type, and a time domain. These attributes are specified in the Schema defining a collection of chronicles. There can be additional attributes.

The type of a series is not the same as its ValueType but corresponds to the value of the type parameter of its value type.

Author:

Jean-Paul Vetterli

See Also:

TimeAddressable

Method Summary

Modifier and Type	Method and Description
UpdatableSeries<T>	edit() Return an UpdatableSeries corresponding to this series.
Attribute<?>	getAttribute(String name, boolean mustExist) Return the attribute with the given name.
Collection<Attribute<?>>	getAttributes() Return all the series' attributes.
Chronicle	getChronicle() Return the chronicle to which this series belongs.
SeriesDefinition	getDefinition() Return the series' definition.
String	getDescription(boolean full) Return the description of the series.
List<String>	getDescriptions() Return the list of all descriptions along the chronicle chain and the series.
ch.agent.t2.timeseries.Observation<T>	getFirstObservation(ch.agent.t2.time.TimeIndex time) Return the observation at the given time index or the first following observation.
ch.agent.t2.timeseries.Observation<T>	getLastObservation(ch.agent.t2.time.TimeIndex time) Return the observation at the give time index or the last preceding observation.
String	getName(boolean full) Return the simple name or the full name of the series.
List<String>	getNames() Return the list of all names along the chronicle chain and the series.
int	getNumber() Return the series number within the chronicle.
ch.agent.t2.time.Range	getRange() Return the range of values.
ch.agent.t2.time.TimeDomain	getTimeDomain() Return the time domain of the series.
T	getValue(ch.agent.t2.time.TimeIndex time) Return the value of the time series at the time index specified.
ch.agent.t2.timeseries.TimeAddressable<T>	getValues(ch.agent.t2.time.Range range) Return the time series of values in the range specified.
ch.agent.t2.timeseries.TimeAddressable<T>	getValues(ch.agent.t2.time.Range range, boolean forceSparse) Return the time series of values in the range specified.
ValueType<T>	getValueType() Return the value type of the series.
boolean	isSparse() Return true if the series is forced to use sparse time series.
<S> Series<S>	typeCheck(Class<S> type) Cast the series to the type specified.

Methods inherited from interface ch.agent.crnickl.api.DBObject

getDatabase, getId, getSurrogate, inConstruction, isValid

Method Detail

edit

UpdatableSeries<T> edit()

Return an UpdatableSeries corresponding to this series. Successfully getting an Updatable object does not imply that updates can be successfully applied.

Returns:

an updatable series corresponding to this series

getChronicle

Chronicle getChronicle()

Return the chronicle to which this series belongs.

Returns:

the chronicle

getNumber

int getNumber()

Return the series number within the chronicle.

Returns:

the series number

getDefinition

SeriesDefinition getDefinition()
                        throws T2DBException

Return the series' definition.

Returns:

the definition of the series

Throws:

T2DBException

getName

String getName(boolean full)
        throws T2DBException

Return the simple name or the full name of the series. The simple name is specified in the schema, so it is the same across a collection of chronicles with the same schema. The full name of a series is the full name of its chronicle plus its simple name.

Parameters:

full - if true return the full name else the simple name

Returns:

the full name or the simple name

Throws:

T2DBException

getNames

List<String> getNames()
               throws T2DBException

Return the list of all names along the chronicle chain and the series. The last element is the simple name of the series. The previous element is the name of the chronicle. The element before that is the name of the chronicle's collection, and so on until the top chronicle.

Returns:

the list of names along the chronicle chain and the series

Throws:

T2DBException

getDescription

String getDescription(boolean full)
               throws T2DBException

Return the description of the series. The full description includes the description of the chronicle. Like the simple name, the simple description is specified in the schema.

Parameters:

full - if true return the full description, else the simple description

Returns:

the full or the simple description of the chronicle

Throws:

T2DBException

getDescriptions

List<String> getDescriptions()
                      throws T2DBException

Return the list of all descriptions along the chronicle chain and the series. The last element is this series description. The previous element is the description of the chronicle. The element before that is the description of the chronicle collection, and so on until the top chronicle.

Returns:

the list of descriptions along the chronicle chain and the series

Throws:

T2DBException

getValueType

ValueType<T> getValueType()
                   throws T2DBException

Return the value type of the series. For a given series name and schema, the type is always the same.

Returns:

the value type of the series

Throws:

T2DBException

getTimeDomain

ch.agent.t2.time.TimeDomain getTimeDomain()
                                   throws T2DBException

Return the time domain of the series. For a given series name and schema, the time domain is always the same.

Returns:

the time domain of the series

Throws:

T2DBException

getAttribute

Attribute<?> getAttribute(String name,
                          boolean mustExist)
                   throws T2DBException

Return the attribute with the given name. When the parameter mustExist is set, the result is never null. The value of the attribute can always be null. When no attribute with the given name is defined, an exception is thrown.

Parameters:

name - the name of the attribute

Returns:

an attribute

Throws:

T2DBException

getAttributes

Collection<Attribute<?>> getAttributes()
                                throws T2DBException

Return all the series' attributes.

Returns:

all the attributes of the series

Throws:

T2DBException

getValues

ch.agent.t2.timeseries.TimeAddressable<T> getValues(ch.agent.t2.time.Range range)
                                             throws ch.agent.t2.T2Exception,
                                                    T2DBException

Return the time series of values in the range specified. Any pending update is merged into the result. When there is a backing store for the series, values are always fetched from the backing store (they are not cached). The result is never null. When there are no values, the result is a time series with an empty range.

Parameters:

range - the range of values wanted or null for the full range

Returns:

a time series

Throws:

T2DBException

ch.agent.t2.T2Exception

getValues

ch.agent.t2.timeseries.TimeAddressable<T> getValues(ch.agent.t2.time.Range range,
                                                    boolean forceSparse)
                                             throws ch.agent.t2.T2Exception,
                                                    T2DBException

Return the time series of values in the range specified. Any pending update is merged into the result. When there is a backing store for the series, values are always fetched from the backing store (they are not cached). The result is never null. When there are no values, the result is a time series with an empty range. If the forceSparse parameter is true, a sparse time series will be used. If the code is false but the sparsity setting of the schema for the series requires a sparse time series, then one will be used. In all other cases the software will decide whether to use a standard or a sparse time series using heuristics.

Parameters:

range - the range of values wanted or null to get the full range

forceSparse - if true use a sparse time series

Returns:

a time series

Throws:

T2DBException

ch.agent.t2.T2Exception

getValue

T getValue(ch.agent.t2.time.TimeIndex time)
    throws ch.agent.t2.T2Exception,
           T2DBException

Return the value of the time series at the time index specified. When there is no value, the result is a missing value object.

Parameters:

time - a time index

Returns:

a value

Throws:

T2DBException

ch.agent.t2.T2Exception

See Also:

TimeAddressable.getMissingValue()

getLastObservation

ch.agent.t2.timeseries.Observation<T> getLastObservation(ch.agent.t2.time.TimeIndex time)
                                                  throws ch.agent.t2.T2Exception,
                                                         T2DBException

Return the observation at the give time index or the last preceding observation. If the time parameter is null return the last observation. Return null if there is nothing.

Parameters:

time - a time index or null

Returns:

an observation or null

Throws:

T2DBException

ch.agent.t2.T2Exception

getFirstObservation

ch.agent.t2.timeseries.Observation<T> getFirstObservation(ch.agent.t2.time.TimeIndex time)
                                                   throws ch.agent.t2.T2Exception,
                                                          T2DBException

Return the observation at the given time index or the first following observation. If the time parameter is null return the first observation. Return null if there is nothing.

Parameters:

time - a time index or null

Returns:

an observation or null

Throws:

T2DBException

ch.agent.t2.T2Exception

getRange

ch.agent.t2.time.Range getRange()
                         throws ch.agent.t2.T2Exception,
                                T2DBException

Return the range of values. The result is never null. When there are no values, the range is empty.

Returns:

the range of existing values

Throws:

ch.agent.t2.T2Exception

T2DBException

isSparse

boolean isSparse()
          throws T2DBException

Return true if the series is forced to use sparse time series. If true the method getValues(Range) must return a sparse time series, else it can return a sparse or a regular time series.

Returns:

true if the series is forced to use sparse time series

Throws:

T2DBException

typeCheck

<S> Series<S> typeCheck(Class<S> type)
                 throws T2DBException

Cast the series to the type specified. The method performs type checking at run time and allows to catch type errors in controlled fashion.

Parameters:

type - the underlying type required

Returns:

the series cast to the type specified

Throws:

T2DBException