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