]> gerrit.simantics Code Review - simantics/platform.git/blob - bundles/org.simantics.history/src-isv/collector.mediawiki
Don't create degenerated transient RouteLines to RouteGraph
[simantics/platform.git] / 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>