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

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