Difference between revisions of "Org.simantics.history"

From Developer Documents
Jump to navigation Jump to search
m
 
(8 intermediate revisions by 2 users not shown)
Line 1: Line 1:
This plugin''(org.simantics.history'') contains a library for history service.  
+
This plugin (''org.simantics.history'') contains a library for history service.  
*[[svn:foundation/trunk/org.simantics.history/src/org/simantics/history/HistoryManager.java|HistoryManager]] Historian Interface.
+
*[[svn:foundation/trunk/org.simantics.history/src/org/simantics/history/Historian.java|Historian]] Historian Interface ([[svn:foundation/trunk/org.simantics.history/src/org/simantics/history/HistoryCollector.java|HistoryCollector]]/[[svn:foundation/trunk/org.simantics.history/src/org/simantics/history/HistoryManager.java|HistoryManager]]).
 
*[[svn:foundation/trunk/org.simantics.history/src/org/simantics/history/Subscription.java|Subscription]] Subscription configuration
 
*[[svn:foundation/trunk/org.simantics.history/src/org/simantics/history/Subscription.java|Subscription]] Subscription configuration
 
*[[svn:foundation/trunk/org.simantics.history/src/org/simantics/history/SamplingFormat.java|SamplingFormat]] Sampling format
 
*[[svn:foundation/trunk/org.simantics.history/src/org/simantics/history/SamplingFormat.java|SamplingFormat]] Sampling format
Line 19: Line 19:
 
Sample format describes the format how the data is stored in the stream file, the
 
Sample format describes the format how the data is stored in the stream file, the
 
primitive types and fields to record. There is a well-known set of  
 
primitive types and fields to record. There is a well-known set of  
fields that the recording supports. Unknown fields are left unchanged.  
+
fields that the recording supports. Unknown fields are left untouched.  
 
Fields "time", "endTime", and "value" are mandatory.
 
Fields "time", "endTime", and "value" are mandatory.
  
Line 56: Line 56:
 
  }
 
  }
  
The system can write down any primitive fields. Even arrays, enums, records
+
The system can write down values of any type. Even arrays, enums, records
and strings. Time and endTime fields must be numeric, values not.
+
and strings. There is a restriction in the file historian that the data type must be constant sized, e.g. double[3]. Thus variable sized arrays and strings are not supported.
 +
Time and endTime fields must be numeric, values not.
  
 
  Example1 = {
 
  Example1 = {
Line 89: Line 90:
 
==File History==
 
==File History==
  
File based implementation is the only existing implementation. Files are  
+
Files are managed in workarea (folder).  
managed in workarea (folder).  
 
  
 
<syntaxHighlight lang="java">
 
<syntaxHighlight lang="java">
  HistoryManager historian = Historian.openFileHistory( workarea );
+
  Historian historian = History.openFileHistory( workarea );
 
</syntaxHighlight>
 
</syntaxHighlight>
  
Line 108: Line 108:
 
An open subscription recording can be closed and opened, the state data is persisted  
 
An open subscription recording can be closed and opened, the state data is persisted  
 
when the handle is closed.
 
when the handle is closed.
 +
 +
== Collector ==
 +
''Collector'' is a versatile utility that writes values to history items. The data is read from ''DataSource'' interface, and written to ''HistoryManager''. DataSource's variable is often recorded to multiple ''HistoryItems'' with different recording settings. Writing step has three calls:
 +
# beginStep()
 +
# setValue() called for each variable
 +
# endStep().
 +
Collector has ''FlushPolicy'', either ''FlushOnEveryStep'' or ''NoFlush''. Flushing can be invoked manually too with ''Collector.flush()''.

Latest revision as of 10:28, 27 June 2012

This plugin (org.simantics.history) contains a library for history service.

Details

HistoryManager manages persistent and stateful objects called "Subscription". Subscriptions have globally unique identifier (GUID).

When a subscription is recorded, it is opened and a handle is received. To record the user supplies time code and values for each variable.

A subscription consists of items that describe how a variable is to be recorded and stored in a file. For each item: interval, deadband, variableId, enabled, and the sample format are provided.

Sample format describes the format how the data is stored in the stream file, the primitive types and fields to record. There is a well-known set of fields that the recording supports. Unknown fields are left untouched. Fields "time", "endTime", and "value" are mandatory.

Sample = {
  // Time
  time         : Double,      // Time of the first sample (mandatory field) 
  endTime      : Double,      // Time of the last sample (mandatory field)
 
  // Values
  value        : Double,      // First value (mandatory field)  
  lastValue    : Double,      // Last value 
  avg          : Double,      // Avg value of source valus within the band's time range
  median       : Double,      // Median value
  min          : Double, 
  max          : Double,
    
  quality      : Byte,        // 0-Good, -1=Novalue
  count        : Integer      // The number of source values acquired 
}

One variable is typically subscribed with multiple items. For instance, simantics chart subscribes the chart_raw, chart_1s, chart_10s, chart_60s, and chart_min-max items. 1s, 10s, and 60s have corresponding interval value (eg. max. 1 entry per 10s of data). "min-max" is an subscription item that tracks down the minimum and maximum value of the variable. It has infinitely long interval value and thus records only one sample (unless there is discontinuation).

The sample entry is basically a band of values. The entry is packed even if deadband and interval are disabled. The system packs the unchanged set of values into a single entry.

Simple = {
  time         : Double, 
  endTime      : Double,
  value        : Double
}

The system can write down values of any type. Even arrays, enums, records and strings. There is a restriction in the file historian that the data type must be constant sized, e.g. double[3]. Thus variable sized arrays and strings are not supported. Time and endTime fields must be numeric, values not.

Example1 = {
  time         : Long, 
  endTime      : Long,
  value        : Double,
  avg          : Float
}
VectorSample = {
  time         : Long, 
  endTime      : Long,
  value        : Double[ 3 ]
}

Discontinuity

The assumption is that two consecutive stream entries describe a data that is sampled continuously from the source. If there is non-continuation in the source data or if the recording was disabled temporarily, a discontinuation marker is added.

To support discontinuation in the data stream, there must be quality-field.

Example = {
   time         : Long, 
   endTime      : Long,
   value        : Double,
   quality      : Byte    // 0 Good, -1 No value
}

File History

Files are managed in workarea (folder).

<syntaxHighlight lang="java">

Historian historian = History.openFileHistory( workarea );

</syntaxHighlight>


Subscription state and recording metadata is in one file, and all subscription items each in a separate file.

Subscription        -    [SubscriptionId].dbb
SubscriptionItem    -    [SubscriptionId]-VariableId-[sampling hash hex]-[sampling name].stm

When a subscription is created, it prepares all related files. If a subscription is modified, it reflects to files by deleting and creating new.

An open subscription recording can be closed and opened, the state data is persisted when the handle is closed.

Collector

Collector is a versatile utility that writes values to history items. The data is read from DataSource interface, and written to HistoryManager. DataSource's variable is often recorded to multiple HistoryItems with different recording settings. Writing step has three calls:

  1. beginStep()
  2. setValue() called for each variable
  3. endStep().

Collector has FlushPolicy, either FlushOnEveryStep or NoFlush. Flushing can be invoked manually too with Collector.flush().