--- /dev/null
+\r
+=History Manager=\r
+HistoryManager is an interface for managing time-series streams (called ''items'') of sample data. There are two implementations FileHistory and MemoryHistory. The data is based on files and in-memory arrays.\r
+<pre>\r
+ // Create History Manager\r
+ HistoryManager history = History.createMemoryHistory();\r
+</pre>\r
+\r
+Items can be created, modified, opened, deleted. \r
+An item is a description, that carries related meta-data aswell. The file history persists the configuration data on disc.\r
+\r
+To create a history item you must provide an item description for each stream.\r
+The description is a class inherited from Bean-class. \r
+Two fields are mandatory id:String, and format:Datatype. \r
+Other fields are meta-data that are stored along with the history. \r
+\r
+Therefore it is suggested to use one of the following classes:\r
+{| border="1" cellpadding="3" cellspacing="0" align="center" style="background-color: #f9f9f9;"\r
+|'''Class''' || '''Description'''\r
+|- style="background-color: #fff;"\r
+|HistoryItem || Simplest format of HistoryManager Item { id:String, format:Datatype }\r
+|- style="background-color: #fff;"\r
+|HistoryAndCollectorItem || Item format for both HistoryManager and Collector.\r
+|- style="background-color: #fff;"\r
+|SubscriptionItem || Item format for HistoryManager, Collector, and meta-data for Simantics subscription configurations. \r
+|}\r
+\r
+To create create an item in the history, specify a format, id, and an item format.\r
+<pre>\r
+ // Create a sample format ( simple though )\r
+ RecordType sampleFormat = new RecordType();\r
+ sampleFormat.addComponent("time", Datatypes.DOUBLE );\r
+ sampleFormat.addComponent("value", Datatypes.DOUBLE );\r
+ sampleFormat.addComponent("quality", Datatypes.BYTE );\r
+ \r
+ // Create History Item configuration\r
+ String id = UUID.randomUUID().toString();\r
+ HistoryItem hi = new HistoryItem(id, sampleFormat);\r
+ \r
+ // Create the item in the history\r
+ history.create( hi );\r
+</pre>\r
+\r
+The data can be written by using a collector, or by adding samples directly to a array (stream) accessor.\r
+<pre>\r
+ // Open item for writing\r
+ StreamAccessor sa = history.openStream(id, "rw");\r
+ // Read sample type\r
+ RecordType sampleFormat = (RecordType) sa.type().componentType;\r
+ // Create bean based binding for the sample\r
+ RecordBinding sampleBinding = (RecordBinding) Bindings.getBeanBinding( sampleFormat );\r
+ // Create sample object\r
+ Bean sample = (Bean) sampleBinding.createPartial();\r
+ \r
+ try {\r
+ \r
+ // Set quality\r
+ sample.setField(2, Bindings.BYTE, (byte)0);\r
+ \r
+ // Write 10 samples\r
+ for (int i=0; i<10; i++) {\r
+ \r
+ // Set time\r
+ sample.setField(0, Bindings.DOUBLE, 1.0*i );\r
+ // Set Value\r
+ sample.setField(1, Bindings.DOUBLE, 100.0*i );\r
+ \r
+ sa.add(sampleBinding, sample); \r
+ }\r
+ \r
+ } finally {\r
+ sa.flush();\r
+ sa.close();\r
+ }\r
+</pre>\r
+\r
+The data is read in a similiar fashion; by opening an accessor and reading samples.\r
+<pre> \r
+ // Open stream from history\r
+ StreamAccessor sa = history.openStream(id, "r");\r
+ // Read sample type\r
+ RecordType sampleFormat = (RecordType) sa.type().componentType;\r
+ // Create bean binding\r
+ RecordBinding sampleBinding = (RecordBinding) Bindings.getBeanBinding( sampleFormat );\r
+ // Create sample object\r
+ Bean sample = (Bean) sampleBinding.createPartial();\r
+ \r
+ try {\r
+ for (int i=0; i<sa.size(); i++) {\r
+ sa.get(i, sampleBinding, sample);\r
+ System.out.println(i+": "+sample);\r
+ }\r
+ } finally {\r
+ sa.close();\r
+ }\r
+</pre>\r
+\r
+\r
+=File History=\r
+FileHistory is a file and directory based history manager. \r
+<pre>\r
+ // Create History Manager in a workarea (directory)\r
+ HistoryManager history = History.openFileHistory( workarea );\r
+</pre>\r
+\r
+\r
+A history item is uses 2 - 3 files. All the files are located in a directory called workarea.\r
+The file is named by escaping the id using URI encoding, and appending three file name extensions.\r
+\r
+{| border="1" cellpadding="3" cellspacing="0" align="center"\r
+|- style="background-color: #f9f9f9;" \r
+|'''File''' || '''Description''' \r
+|- \r
+|<id>.txt || The item's meta-data written as serialization of the variant. The file format is no longer ascii text, but binary data.\r
+|-\r
+|<id>.data || A series of samples serialized with no header.\r
+|-\r
+|<id>.index || Index file that contains <tt>long</tt> offsets for each sample. Index file is used for variable sized samples only, such as strings and variable-lengthed arrays.\r
+|}\r
+\r
+=Item Manager=\r
+Item descriptions are aquired with HistoryManager#getItems(). Each item is an record containing the fields\r
+the item was initialized with, and/or possible added later. For instance, if data was written to the item\r
+with a Collector, the collecting parameters and collectin state data is written to a field called "collectorState".\r
+<pre>\r
+ Bean[] items = history.getItems();\r
+</pre>\r
+The record is expressed with an instance of a sub-class of a bean. Known fields can be copied to user\r
+specified class.\r
+<pre>\r
+ HistoryItem i0 = new HistoryItem();\r
+ i0.readAvailableFields( items[0] );\r
+</pre> \r
+ItemManager is an utility that aids in creating, modifying and reading item arrays.\r
+<pre>\r
+ ItemManager im = new ItemManager( items );\r
+</pre>\r
+Item id's can be extracted conveniently.\r
+<pre>\r
+ System.out.println("Items Identifiers:");\r
+ for ( String itemId : im.toIdArray() )\r
+ {\r
+ System.out.println( itemId );\r
+ }\r
+</pre>\r
+The items can be selected using one or multiple fields as patterns. \r
+<pre> \r
+ // To search an item by id, use\r
+ List<Bean> result = im.search("id", id);\r
+ \r
+ // To search items of specific parameter, say file format, use\r
+ im.search("format", sampleFormat);\r
+ \r
+ // Or interval\r
+ im.search("interval", 0.1);\r
+</pre>
\ No newline at end of file
Code Review / simantics / platform.git / blobdiff