1 /*******************************************************************************
\r
2 * Copyright (c) 2007, 2011 Association for Decentralized Information Management in
\r
4 * All rights reserved. This program and the accompanying materials
\r
5 * are made available under the terms of the Eclipse Public License v1.0
\r
6 * which accompanies this distribution, and is available at
\r
7 * http://www.eclipse.org/legal/epl-v10.html
\r
10 * VTT Technical Research Centre of Finland - initial API and implementation
\r
11 *******************************************************************************/
\r
12 package org.simantics.history;
\r
14 import org.simantics.databoard.Bindings;
\r
15 import org.simantics.databoard.accessor.StreamAccessor;
\r
16 import org.simantics.databoard.binding.Binding;
\r
17 import org.simantics.databoard.binding.NumberBinding;
\r
18 import org.simantics.databoard.binding.mutable.MutableVariant;
\r
19 import org.simantics.databoard.util.Bean;
\r
20 import org.simantics.history.impl.FlushPolicy;
\r
21 import org.simantics.history.util.subscription.SubscriptionItem;
\r
24 * Collector manages recoding of variables to subscribed items.
\r
26 * Single variable is typically recorded to multiple subscription items with
\r
27 * different recording parameters. The variable source is identified with
\r
28 * "variableId" field in historyItem (given at #addItem()).
\r
30 * The actual collecting uses the following procedure:
\r
31 * If same value repeats, or is considered repeating because of deadband or interval setting,
\r
32 * then the values are packed in to a single entry (called value band).
\r
34 * An entry can be represented with either (a) as ranged or as (b) non-ranged format.
\r
35 * In ranged format, the entry represents multiple values from the datasource.
\r
36 * There are fields such as: start time, end time, min, max value, first and last value.
\r
38 * In non-ranged format, the entry represents a single sample from the datasource.
\r
39 * The format is very simple (time, value). When same value repeats, two samples
\r
40 * are written, one at the start of the new value, another at to represent the
\r
41 * last entry with the same value. At run-time, the sample is forwarded in time.
\r
43 * @author toni.kalajainen
\r
45 public interface Collector {
\r
48 * Get a snapshot of all the item configurations.
\r
50 * Note, The resulting bean can be converted to {@link SubscriptionItem} or {@link HistoryAndCollectorItem}
\r
51 * with {@link Bean#readAvailableFields(Bean)} method.
\r
53 * Note, this bean also contains "collectorState" object.
\r
57 SubscriptionItem[] getItems();
\r
60 * Subscribe an item.
\r
62 * The item is opened when the collecting starts at {@link #beginStep(NumberBinding, Object)}.
\r
64 * Collector requres these fields are required:
\r
66 * o variableId - String
\r
67 * o deadband - double
\r
68 * o interval - double
\r
71 * o enabled - boolean
\r
73 * It is recommended to use {@link SubscriptionItem} or {@link HistoryAndCollectorItem}.
\r
74 * Although you may use your own classes aslong as they have the fields and extend Bean.
\r
78 void addItem(Bean item) throws HistoryException;
\r
79 void addItems(Bean...item) throws HistoryException;
\r
82 * Remove the subscribed item from the collector.
\r
84 * Item's CollectorState is written to the history's meta-data.
\r
85 * "collectorState"-field is added if it did not exist.
\r
88 * @throws HistoryException
\r
90 void removeItem(String id) throws HistoryException;
\r
93 * Add or update subscription item.
\r
96 * @throws HistoryException
\r
98 void setItem(Bean item) throws HistoryException;
\r
101 * Get associated history manager
\r
103 * @return history manager
\r
105 HistoryManager getHistory();
\r
110 * @return flush policy
\r
112 FlushPolicy getFlushPolicy();
\r
116 * @param flushPolicy
\r
118 void setFlushPolicy(FlushPolicy flushPolicy);
\r
121 * Begin a new time step.
\r
123 * @param binding (for example {@link Bindings#DOUBLE})
\r
125 * @throws HistoryException
\r
127 void beginStep(NumberBinding binding, Object time) throws HistoryException;
\r
134 * @throws HistoryException
\r
136 Object getTime(Binding binding) throws HistoryException;
\r
139 * Set a value for a variable. If there are multiple items for one
\r
140 * variable, the value is written to all streams.
\r
145 * @throws HistoryException
\r
147 void setValue(String id, Binding binding, Object value) throws HistoryException;
\r
150 * Get the value the collector has about a variable.
\r
153 * @param binding in which to get result
\r
154 * @return true if value existed
\r
156 Object getValue(String id, Binding binding) throws HistoryException;
\r
157 boolean getValue(String id, MutableVariant result);
\r
160 * End the time step. Values are commited to history.
\r
162 * @throws HistoryException
\r
164 void endStep() throws HistoryException;
\r
167 * Flush any pending changes to all time series.
\r
169 * A few flush policies are, to flush after every step (not good
\r
170 * performance), to flush on time interval, say, every second.
\r
171 * And third, to flush after one second since last flush and step.
\r
173 * @throws HistoryException
\r
175 void flush() throws HistoryException;
\r
178 * Save and Close the collector session.
\r
179 * CollectorStates are written back to the history.
\r
180 * "collectorState"-field is added if it did not exist.
\r
185 * Open stream from associated history manager
\r
190 * @throws HistoryException
\r
192 StreamAccessor openStream(String itemId, String mode) throws HistoryException;
\r
195 * Get the complete state of this collector as a bean. Required for
\r
196 * supporting serialization of the internal collector state.
\r
198 * Not intended to be thread-safe, i.e. do not invoke this while in a
\r
201 * @return current collector state data
\r
206 * Required for supporting deserialization of the internal collector state.
\r
207 * Do not invoke this during data collection. It is only intended for
\r
208 * initializing a collector instance properly when a collector is used for
\r
209 * appending to an existing history.
\r
212 * a new complete state to set for this collector. Must be a
\r
213 * value that's been previously retrieved from
\r
214 * {@link #getCollectorState()}.
\r
216 void setState(Bean newState);
\r