Migrated source code from Simantics SVN

[simantics/platform.git] / bundles / org.simantics.history / history.txt

diff --git a/bundles/org.simantics.history/history.txt b/bundles/org.simantics.history/history.txt
new file mode 100644 (file)
index 0000000..6fa06b0
--- /dev/null
+++ b/bundles/org.simantics.history/history.txt
@@ -0,0 +1,102 @@
+This plugin(org.simantics.history) contains a library for history service.\r
+\r
+== Details ==\r
+\r
+HistoryManager manages persistent and stateful objects called "Subscription".\r
+Subscription has globally unique id (GUID).\r
+\r
+When a subscription is recorded, it is opened and a handle is received. \r
+To record the user supplies time code and values for each variable. \r
+  \r
+A subscription consists of items that describe how a variable is to be recorded\r
+and stored in a file. For each item: interval, deadband, variableId, enabled, \r
+and the sample format are provided.  \r
+\r
+Sample format describes the format how the data is stored in the stream file, the\r
+primitive types and fields to record. There is a well-known set of \r
+fields that the recording supports. Unknown fields are left unchanged. \r
+Fields "time", "endTime", and "value" are mandatory.\r
+\r
+Sample = {\r
+   // Time\r
+   time         : Double,      // Time of the first sample (mandatory field) \r
+   endTime      : Double,      // Time of the last sample (mandatory field)\r
+\r
+   // Values\r
+   value        : Double,      // First value (mandatory field)  \r
+   lastValue    : Double,      // Last value \r
+   avg          : Double,      // Avg value of source valus within the band's time range\r
+   median       : Double,      // Median value\r
+   min          : Double, \r
+   max          : Double,\r
+   \r
+   quality      : Byte,        // 0-Good, -1=Novalue\r
+   count        : Integer      // The number of source values acquired \r
+}\r
+\r
+One variable is typically subscribed with multiple items. For instance, simantics\r
+chart subscribes the chart_raw, chart_1s, chart_10s, chart_60s, and chart_min-max \r
+items. 1s, 10s, and 60s have corresponding interval value (eg. max. 1 entry per 10s of data). \r
+"min-max" is an subscription item that tracks down the minimum and maximum\r
+value of the variable. It has infinitely long interval value and thus records\r
+only one sample (unless there is discontinuation). \r
+ \r
+The sample entry is basically a band of values. The entry is packed even if \r
+deadband and interval are disabled. The system packs the unchanged set of values \r
+into a single entry. \r
+\r
+Simple = {\r
+   time         : Double, \r
+   endTime      : Double,\r
+   value        : Double\r
+}\r
+\r
+The system can write down any primitive fields. Even arrays, enums, records\r
+and strings. Time and endTime fields must be numeric, values not.\r
+\r
+Example1 = {\r
+   time         : Long, \r
+   endTime      : Long,\r
+   value        : Double,\r
+   avg          : Float\r
+}\r
+\r
+VectorSample = {\r
+   time         : Long, \r
+   endTime      : Long,\r
+   value        : Double[ 3 ]\r
+}\r
+\r
+\r
+Discontinuation\r
+--------------- \r
+\r
+The assumption is that two consecutive stream entries describe a data that is sampled \r
+continuously from the source. If there is non-continuation in the source data or\r
+if the recording was disabled temporarily, a discontinuation marker is added. \r
+\r
+To support discontinuation in the data stream, there must be quality-field.\r
+\r
+Example = {\r
+   time         : Long, \r
+   endTime      : Long,\r
+   value        : Double,\r
+   quality      : Byte    // 0 Good, -1 No value\r
+}\r
+\r
+\r
+File History\r
+=================\r
+\r
+File based implementation is the only existing implementation. Files are \r
+managed in workarea (folder). Subscription state and recording metadata is in one \r
+file, and all subscription items each in a separate file. \r
+\r
+ Subscription        -    [SubscriptionId].dbb\r
+ SubscriptionItem    -    [SubscriptionId]-VariableId-[sampling hash hex]-[sampling name].stm\r
+\r
+When a subscription is created, it prepares all related files. If a subscription\r
+is modified, it reflects to files by deleting and creating new. \r
+\r
+An open subscription recording can be closed and opened, the state data is persisted \r
+when the handle is closed. \r