com.inductiveautomation.gateway.tsdb.api

Interface Historian

All Known Implementing Classes:

AbstractHistorian, FixedDailyDataHistorian, MemoryBackedHistorian, SQLiteHistorian

public interface Historian

Represents a simple time-series tag historian.

Field Summary

Fields

Modifier and Type	Field and Description
static int	QUALITY_NOT_FOUND

Method Summary

Modifier and Type	Method and Description
java.util.List<java.lang.String>	browse(java.util.Optional<java.lang.String> filter) Returns a list of paths with data stored, optionally matching a filter.
StorageSession	createStorageSession() Used to store values to the historian.
void	delete(java.util.List<java.lang.String> paths) Deletes the tags and all data for the specified paths.
<T> T	getProperty(Property<T> prop) Returns the configured or status property requested, or the default value if no further info is available.
Status	getQueryStatus() Returns the status of the storage system.
Status	getStorageStatus() Returns the status of the storage system.
void	initialize(PropertySet historianProperties)
QueryResult	query(java.util.List<java.lang.String> tags, long startTime, long endTime, boolean includeBounding) Queries the values for the given paths over the specified span of time.
void	register(java.lang.String tag, PropertySet properties) Provides information about a path.
void	shutdown()

Field Detail

QUALITY_NOT_FOUND

static final int QUALITY_NOT_FOUND

See Also:

Constant Field Values

Method Detail

getProperty

<T> T getProperty(Property<T> prop)

Returns the configured or status property requested, or the default value if no further info is available. Most of these properties are defined in HistorianProperties.

Parameters:

prop -

Returns:

getStorageStatus

Status getStorageStatus()

Returns the status of the storage system. If the system does not support storage, NotAvailable will be returned. If this is the case, calls to createStorageSession will fail.

getQueryStatus

Status getQueryStatus()

Returns the status of the storage system. If the system does not support querying, NotAvailable will be returned.

initialize

void initialize(PropertySet historianProperties)
         throws java.lang.Exception

Throws:

java.lang.Exception

shutdown

void shutdown()

register

void register(java.lang.String tag,
              PropertySet properties)
       throws java.lang.Exception

Provides information about a path. May be called before or after values have been stored, will replace any previous information stored for a path. The property values are usually defined in HistorianProperties.

Throws:

java.lang.Exception

createStorageSession

StorageSession createStorageSession()
                             throws java.lang.Exception

Used to store values to the historian. Should be used for the immediate set of values and then closed. It should not be held open for longer than necessary.

It implements AutoClosable, and should often be used in a try-with-resources block, such as:
try(StorageSession s = historian.createStorageSession()){ s.store... }

Important: Not every historian will support storage, some are read-only. This can be checked by calling getStorageStatus() and checking the return for "NotSupported".

Throws:

java.lang.Exception

delete

void delete(java.util.List<java.lang.String> paths)

Deletes the tags and all data for the specified paths. Paths may be wildcards using "*". Only expected to work if the historian supports storage, as indicated by getStorageStatus().

browse

java.util.List<java.lang.String> browse(java.util.Optional<java.lang.String> filter)

Returns a list of paths with data stored, optionally matching a filter.

Parameters:

filter - a wildcard ("Tag*") based string that will be used to filter tags. If empty, all paths will be returned.

query

QueryResult query(java.util.List<java.lang.String> tags,
                  long startTime,
                  long endTime,
                  boolean includeBounding)

Queries the values for the given paths over the specified span of time. The implementation will conform to the following rules:

1. If endTime is less than start time, results MAY be provided latest first. If that is not possible, the parameters will be swapped and values returned as normal.
2. The result will have a unique PathInfo item for EACH of the paths passed in. If a path is specified multiple times, it will be returned multiple times.
3. If a path is not valid, the query result will return ONE DataPoint for the query start time with a quality of 404 (NOT FOUND)
4. The timestamps for a given path will be ascending, though between paths they may not be.

Parameters:

includeBounding - if true, the closest value previous to the start time will be returned, as well as the closest value following the end time.