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