bundles/org.simantics.history/src/org/simantics/history/Collector.java

   1 /*******************************************************************************
   2  * Copyright (c) 2007, 2011 Association for Decentralized Information Management in
   3  * Industry THTH ry.
   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
   8  *
   9  * Contributors:
  10  *     VTT Technical Research Centre of Finland - initial API and implementation
  11  *******************************************************************************/
  12 package org.simantics.history;
  13
  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;
  22
  23 /**
  24  * Collector manages recoding of variables to subscribed items.
  25  *
  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()).
  29  *
  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).
  33  *
  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.
  37  *
  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.
  42  *
  43  * @author toni.kalajainen
  44  */
  45 public interface Collector {
  46
  47         /**
  48          * Get a snapshot of all the item configurations.
  49          *
  50          * Note, The resulting bean can be converted to {@link SubscriptionItem} or {@link HistoryAndCollectorItem}
  51          * with {@link Bean#readAvailableFields(Bean)} method.
  52          *
  53          * Note, this bean also contains "collectorState" object.
  54          *
  55          * @return items
  56          */
  57         SubscriptionItem[] getItems();
  58
  59         /**
  60          * Subscribe an item.
  61          *
  62          * The item is opened when the collecting starts at {@link #beginStep(NumberBinding, Object)}.
  63          *
  64          * Collector requres these fields are required:
  65          *  o id - String
  66          *  o variableId - String
  67          *  o deadband - double
  68          *  o interval - double
  69          *  o gain - double
  70          *  o bias - double
  71          *  o enabled - boolean
  72          *
  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.
  75          *
  76          * @param item
  77          */
  78         void addItem(Bean item) throws HistoryException;
  79         void addItems(Bean...item) throws HistoryException;
  80
  81         /**
  82          * Remove the subscribed item from the collector.
  83          *
  84          * Item's CollectorState is written to the history's meta-data.
  85          * "collectorState"-field is added if it did not exist.
  86          *
  87          * @param id
  88          * @throws HistoryException
  89          */
  90         void removeItem(String id) throws HistoryException;
  91
  92         /**
  93          * Add or update subscription item.
  94          *
  95          * @param item
  96          * @throws HistoryException
  97          */
  98         void setItem(Bean item) throws HistoryException;
  99
 100         /**
 101          * Get associated history manager
 102          *
 103          * @return history manager
 104          */
 105         HistoryManager getHistory();
 106
 107         /**
 108          * Get flush policy
 109          *
 110          * @return flush policy
 111          */
 112         FlushPolicy getFlushPolicy();
 113
 114         /**
 115          * Set flush policy
 116          * @param flushPolicy
 117          */
 118         void setFlushPolicy(FlushPolicy flushPolicy);
 119
 120         /**
 121          * Begin a new time step.
 122          *
 123          * @param binding (for example {@link Bindings#DOUBLE})
 124          * @param time
 125          * @throws HistoryException
 126          */
 127         void beginStep(NumberBinding binding, Object time) throws HistoryException;
 128
 129         /**
 130          * Get current time
 131          *
 132          * @param binding
 133          * @return
 134          * @throws HistoryException
 135          */
 136         Object getTime(Binding binding) throws HistoryException;
 137
 138         /**
 139          * Set a value for a variable. If there are multiple items for one
 140          * variable, the value is written to all streams.
 141          *
 142          * @param id
 143          * @param binding
 144          * @param value
 145          * @throws HistoryException
 146          */
 147         void setValue(String id, Binding binding, Object value) throws HistoryException;
 148
 149         /**
 150          * Get the value the collector has about a variable.
 151          *
 152          * @param id
 153          * @param binding in which to get result
 154          * @return true if value existed
 155          */
 156         Object getValue(String id, Binding binding) throws HistoryException;
 157         boolean getValue(String id, MutableVariant result);
 158
 159         /**
 160          * End the time step. Values are commited to history.
 161          *
 162          * @throws HistoryException
 163          */
 164         void endStep() throws HistoryException;
 165
 166         /**
 167          * Flush any pending changes to all time series.
 168          *
 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.
 172          *
 173          * @throws HistoryException
 174          */
 175         void flush() throws HistoryException;
 176
 177         /**
 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.
 181          */
 182         void close();
 183
 184         /**
 185          * Open stream from associated history manager
 186          *
 187          * @param itemId
 188          * @param mode
 189          * @return accessor
 190          * @throws HistoryException
 191          */
 192         StreamAccessor openStream(String itemId, String mode) throws HistoryException;
 193
 194         /**
 195          * Get the complete state of this collector as a bean. Required for
 196          * supporting serialization of the internal collector state.
 197          *
 198          * Not intended to be thread-safe, i.e. do not invoke this while in a
 199          * collection step.
 200          *
 201          * @return current collector state data
 202          */
 203         Bean getState();
 204
 205         /**
 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.
 210          *
 211          * @param newState
 212          *            a new complete state to set for this collector. Must be a
 213          *            value that's been previously retrieved from
 214          *            {@link #getCollectorState()}.
 215          */
 216         void setState(Bean newState);
 217
 218 }