bundles/org.simantics.history/src-isv/history_manager.mediawiki

   1 \r
   2 =History Manager=\r
   3 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
   4 <pre>\r
   5         // Create History Manager\r
   6         HistoryManager history = History.createMemoryHistory();\r
   7 </pre>\r
   8 \r
   9 Items can be created, modified, opened, deleted. \r
  10 An item is a description, that carries related meta-data aswell. The file history persists the configuration data on disc.\r
  11 \r
  12 To create a history item you must provide an item description for each stream.\r
  13 The description is a class inherited from Bean-class. \r
  14 Two fields are mandatory id:String, and format:Datatype. \r
  15 Other fields are meta-data that are stored along with the history. \r
  16 \r
  17 Therefore it is suggested to use one of the following classes:\r
  18 {| border="1" cellpadding="3" cellspacing="0" align="center" style="background-color: #f9f9f9;"\r
  19 |'''Class''' || '''Description'''\r
  20 |- style="background-color: #fff;"\r
  21 |HistoryItem || Simplest format of HistoryManager Item { id:String, format:Datatype }\r
  22 |- style="background-color: #fff;"\r
  23 |HistoryAndCollectorItem || Item format for both HistoryManager and Collector.\r
  24 |- style="background-color: #fff;"\r
  25 |SubscriptionItem || Item format for HistoryManager, Collector, and meta-data for Simantics subscription configurations. \r
  26 |}\r
  27 \r
  28 To create create an item in the history, specify a format, id, and an item format.\r
  29 <pre>\r
  30         // Create a sample format ( simple though )\r
  31         RecordType sampleFormat = new RecordType();\r
  32         sampleFormat.addComponent("time", Datatypes.DOUBLE );\r
  33         sampleFormat.addComponent("value", Datatypes.DOUBLE );\r
  34         sampleFormat.addComponent("quality", Datatypes.BYTE );\r
  35         \r
  36         // Create History Item configuration\r
  37         String id = UUID.randomUUID().toString();\r
  38         HistoryItem hi = new HistoryItem(id, sampleFormat);\r
  39         \r
  40         // Create the item in the history\r
  41         history.create( hi );\r
  42 </pre>\r
  43 \r
  44 The data can be written by using a collector, or by adding samples directly to a array (stream) accessor.\r
  45 <pre>\r
  46         // Open item for writing\r
  47         StreamAccessor sa = history.openStream(id, "rw");\r
  48         // Read sample type\r
  49         RecordType sampleFormat = (RecordType) sa.type().componentType;\r
  50         // Create bean based binding for the sample\r
  51         RecordBinding sampleBinding = (RecordBinding) Bindings.getBeanBinding( sampleFormat );\r
  52         // Create sample object\r
  53         Bean sample = (Bean) sampleBinding.createPartial();\r
  54                 \r
  55         try {\r
  56                 \r
  57                 // Set quality\r
  58                 sample.setField(2, Bindings.BYTE, (byte)0);\r
  59                 \r
  60                 // Write 10 samples\r
  61                 for (int i=0; i<10; i++) {\r
  62                         \r
  63                         // Set time\r
  64                         sample.setField(0, Bindings.DOUBLE, 1.0*i );\r
  65                         // Set Value\r
  66                         sample.setField(1, Bindings.DOUBLE, 100.0*i );\r
  67                         \r
  68                         sa.add(sampleBinding, sample);                          \r
  69                 }\r
  70                 \r
  71         } finally {\r
  72                 sa.flush();\r
  73                 sa.close();\r
  74         }\r
  75 </pre>\r
  76 \r
  77 The data is read in a similiar fashion; by opening an accessor and reading samples.\r
  78 <pre> \r
  79         // Open stream from history\r
  80         StreamAccessor sa = history.openStream(id, "r");\r
  81         // Read sample type\r
  82         RecordType sampleFormat = (RecordType) sa.type().componentType;\r
  83         // Create bean binding\r
  84         RecordBinding sampleBinding = (RecordBinding) Bindings.getBeanBinding( sampleFormat );\r
  85         // Create sample object\r
  86         Bean sample = (Bean) sampleBinding.createPartial();\r
  87         \r
  88         try {\r
  89                 for (int i=0; i<sa.size(); i++) {\r
  90                         sa.get(i, sampleBinding, sample);\r
  91                         System.out.println(i+": "+sample);\r
  92                 }\r
  93         } finally {\r
  94                 sa.close();\r
  95         }\r
  96 </pre>\r
  97 \r
  98 \r
  99 =File History=\r
 100 FileHistory is a file and directory based history manager. \r
 101 <pre>\r
 102         // Create History Manager in a workarea (directory)\r
 103         HistoryManager history = History.openFileHistory( workarea );\r
 104 </pre>\r
 105 \r
 106 \r
 107 A history item is uses 2 - 3 files. All the files are located in a directory called workarea.\r
 108 The file is named by escaping the id using URI encoding, and appending three file name extensions.\r
 109 \r
 110 {| border="1" cellpadding="3" cellspacing="0" align="center"\r
 111 |- style="background-color: #f9f9f9;" \r
 112 |'''File''' || '''Description''' \r
 113 |- \r
 114 |<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
 115 |-\r
 116 |<id>.data || A series of samples serialized with no header.\r
 117 |-\r
 118 |<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
 119 |}\r
 120 \r
 121 =Item Manager=\r
 122 Item descriptions are aquired with HistoryManager#getItems(). Each item is an record containing the fields\r
 123 the item was initialized with, and/or possible added later. For instance, if data was written to the item\r
 124 with a Collector, the collecting parameters and collectin state data is written to a field called "collectorState".\r
 125 <pre>\r
 126         Bean[] items = history.getItems();\r
 127 </pre>\r
 128 The record is expressed with an instance of a sub-class of a bean. Known fields can be copied to user\r
 129 specified class.\r
 130 <pre>\r
 131         HistoryItem i0 = new HistoryItem();\r
 132         i0.readAvailableFields( items[0] );\r
 133 </pre>  \r
 134 ItemManager is an utility that aids in creating, modifying and reading item arrays.\r
 135 <pre>\r
 136         ItemManager im = new ItemManager( items );\r
 137 </pre>\r
 138 Item id's can be extracted conveniently.\r
 139 <pre>\r
 140         System.out.println("Items Identifiers:");\r
 141         for ( String itemId : im.toIdArray() )\r
 142         {\r
 143                 System.out.println( itemId );\r
 144         }\r
 145 </pre>\r
 146 The items can be selected using one or multiple fields as patterns. \r
 147 <pre>   \r
 148         // To search an item by id, use\r
 149         List<Bean> result = im.search("id", id);\r
 150         \r
 151         // To search items of specific parameter, say file format, use\r
 152         im.search("format", sampleFormat);\r
 153         \r
 154         // Or interval\r
 155         im.search("interval", 0.1);\r
 156 </pre>