bundles/org.simantics.history/history.txt

   1 This plugin(org.simantics.history) contains a library for history service.
   2
   3 == Details ==
   4
   5 HistoryManager manages persistent and stateful objects called "Subscription".
   6 Subscription has globally unique id (GUID).
   7
   8 When a subscription is recorded, it is opened and a handle is received.
   9 To record the user supplies time code and values for each variable.
  10
  11 A subscription consists of items that describe how a variable is to be recorded
  12 and stored in a file. For each item: interval, deadband, variableId, enabled,
  13 and the sample format are provided.
  14
  15 Sample format describes the format how the data is stored in the stream file, the
  16 primitive types and fields to record. There is a well-known set of
  17 fields that the recording supports. Unknown fields are left unchanged.
  18 Fields "time", "endTime", and "value" are mandatory.
  19
  20 Sample = {
  21    // Time
  22    time         : Double,      // Time of the first sample (mandatory field)
  23    endTime      : Double,      // Time of the last sample (mandatory field)
  24
  25    // Values
  26    value        : Double,      // First value (mandatory field)
  27    lastValue    : Double,      // Last value
  28    avg          : Double,      // Avg value of source valus within the band's time range
  29    median       : Double,      // Median value
  30    min          : Double,
  31    max          : Double,
  32
  33    quality      : Byte,        // 0-Good, -1=Novalue
  34    count        : Integer      // The number of source values acquired
  35 }
  36
  37 One variable is typically subscribed with multiple items. For instance, simantics
  38 chart subscribes the chart_raw, chart_1s, chart_10s, chart_60s, and chart_min-max
  39 items. 1s, 10s, and 60s have corresponding interval value (eg. max. 1 entry per 10s of data).
  40 "min-max" is an subscription item that tracks down the minimum and maximum
  41 value of the variable. It has infinitely long interval value and thus records
  42 only one sample (unless there is discontinuation).
  43
  44 The sample entry is basically a band of values. The entry is packed even if
  45 deadband and interval are disabled. The system packs the unchanged set of values
  46 into a single entry.
  47
  48 Simple = {
  49    time         : Double,
  50    endTime      : Double,
  51    value        : Double
  52 }
  53
  54 The system can write down any primitive fields. Even arrays, enums, records
  55 and strings. Time and endTime fields must be numeric, values not.
  56
  57 Example1 = {
  58    time         : Long,
  59    endTime      : Long,
  60    value        : Double,
  61    avg          : Float
  62 }
  63
  64 VectorSample = {
  65    time         : Long,
  66    endTime      : Long,
  67    value        : Double[ 3 ]
  68 }
  69
  70
  71 Discontinuation
  72 ---------------
  73
  74 The assumption is that two consecutive stream entries describe a data that is sampled
  75 continuously from the source. If there is non-continuation in the source data or
  76 if the recording was disabled temporarily, a discontinuation marker is added.
  77
  78 To support discontinuation in the data stream, there must be quality-field.
  79
  80 Example = {
  81    time         : Long,
  82    endTime      : Long,
  83    value        : Double,
  84    quality      : Byte    // 0 Good, -1 No value
  85 }
  86
  87
  88 File History
  89 =================
  90
  91 File based implementation is the only existing implementation. Files are
  92 managed in workarea (folder). Subscription state and recording metadata is in one
  93 file, and all subscription items each in a separate file.
  94
  95  Subscription        -    [SubscriptionId].dbb
  96  SubscriptionItem    -    [SubscriptionId]-VariableId-[sampling hash hex]-[sampling name].stm
  97
  98 When a subscription is created, it prepares all related files. If a subscription
  99 is modified, it reflects to files by deleting and creating new.
 100
 101 An open subscription recording can be closed and opened, the state data is persisted
 102 when the handle is closed.