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

   1 =Collector=
   2 Collector is an utility that writes to history the data that is read from a data source.
   3 Collector is instantiated to write to a specific history.
   4 <pre>
   5         Collector collector = History.createCollector(history, FlushPolicy.NoFlush);
   6 </pre>
   7
   8 Collector reads its configuration from collector items.
   9 As convenience, due to overlapping fields, the collector item configuration is often passed with same instance as with history item. There are two classes that are suitable for configuring both history and collector: HistoryAndCollectorItem and SubscriptionItem. User provided classes can also be used as long as they contain the minimum set of fields (See HistoryAndCollectorItem).
  10
  11 <pre>
  12         // Create collector item
  13         HistoryAndCollectorItem ci = new HistoryAndCollectorItem();
  14         ci.id = "history-item-0";
  15         ci.format = sampleFormat;
  16         ci.interval = 0.2;
  17         ci.deadband = 1;
  18         ci.enabled = true;
  19         ci.gain = 10.0;
  20         ci.variableId = "MyDatasourceVariable";
  21
  22         // Initialize Collector (Item)
  23         collector.addItem( ci );
  24 </pre>
  25
  26 The data is written in steps. If flush policy was FlushOnEveryStep then disc buffers are flushed
  27 at endStep().
  28 <pre>
  29         try {
  30                 // Simulate 100 steps
  31                 for ( int i = 0; i<100; i++ ) {
  32
  33                         // Our "simulation" results
  34                         double time = i * 0.1;
  35                         double myDatasourceVariable = -20 + i*0.1;
  36
  37                         // Begin collector writing step
  38                         collector.beginStep(Bindings.DOUBLE, time);
  39
  40                         // Enter values
  41                         collector.setValue("MyDatasourceVariable", Bindings.DOUBLE, myDatasourceVariable);
  42
  43                         // End collector step
  44                         collector.endStep();
  45                 }
  46
  47         } finally {
  48                 // Flush values
  49                 collector.flush();
  50                 collector.close();
  51         }
  52 </pre>
  53
  54 When collector is closed, the initial parameters and state data are written to and persisted in the history.
  55 A field called "collectorState" is created, if did not exist before-hand.
  56
  57 ==Banded mode==
  58 If there is interval or deadband in the collector, the collector records the data in banded mode (start and end time).
  59 But in case the sample format doesn't support banded mode, then the collector writes the data in a way where it puts a sample at the start of a band, and another at the end of the band.
  60
  61 For example if datasource produces value every 0.1 second and interval value was 1.0 seconds; then there would be sample
  62 at 0.0, 0.9 (to represent a band), and then a new sample at 1.0 to represent a start of a new band.
  63
  64 ==How to collect with multiple subscription parameters==
  65 The collector is often used for recording one variable to multiple history items with different collecting parameters; such as interval and deadband. As the user passes collector items to the collector, the user gives and "id" and "variableId" values. "id" determines history item where the data is written to, and "variableId" where associated from in the Collector#setValue() method.
  66
  67 <pre>
  68
  69         /// Configure items for the history and collector
  70         // Create a sample format
  71         RecordType sampleFormat = new RecordType();
  72         sampleFormat.addComponent("time", Datatypes.DOUBLE );
  73         sampleFormat.addComponent("value", Datatypes.DOUBLE );
  74         sampleFormat.addComponent("quality", Datatypes.BYTE );
  75
  76         // Create two item configurations for the history and the collector
  77         HistoryAndCollectorItem i1 = new HistoryAndCollectorItem();
  78         i1.id = "MyVariable-interval=0.5";
  79         i1.format = sampleFormat;
  80         i1.interval = 0.5;
  81         i1.variableId = "MyVariable";
  82
  83         HistoryAndCollectorItem i2 = new HistoryAndCollectorItem();
  84         i2.id = "MyVariable-deadband=5";
  85         i2.format = sampleFormat;
  86         i2.deadband = 5.0;
  87         i2.variableId = "MyVariable";
  88
  89         /// Create History Manager and add Items
  90         HistoryManager history = History.createMemoryHistory();
  91         history.create( i1 );
  92         history.create( i2 );
  93
  94         /// Create Collector and initialize items
  95         Collector collector = History.createCollector(history, FlushPolicy.NoFlush);
  96         collector.addItem( i1 );
  97         collector.addItem( i2 );
  98
  99         /// Collect some data
 100         try {
 101                 // Simulate 100 steps
 102                 for ( int i = 0; i<100; i++ ) {
 103
 104                         // Our "simulation" results
 105                         double time = i * 0.1;
 106                         double myItemValue = -20 + i*0.1;
 107
 108                         // Begin collector writing step
 109                         collector.beginStep(Bindings.DOUBLE, time);
 110
 111                         // Enter values for one variable.
 112                         collector.setValue("MyVariable", Bindings.DOUBLE, myItemValue);
 113
 114                         // End collector step - MyVariable is written to two HistoryItems
 115                         collector.endStep();
 116                 }
 117
 118         } finally {
 119                 // Flush last values
 120                 collector.flush();
 121                 // Write the collector state back to the history
 122                 collector.close();
 123         }
 124 </pre>