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

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