--- /dev/null
+/*******************************************************************************\r
+ * Copyright (c) 2007, 2011 Association for Decentralized Information Management in\r
+ * Industry THTH ry.\r
+ * All rights reserved. This program and the accompanying materials\r
+ * are made available under the terms of the Eclipse Public License v1.0\r
+ * which accompanies this distribution, and is available at\r
+ * http://www.eclipse.org/legal/epl-v10.html\r
+ *\r
+ * Contributors:\r
+ * VTT Technical Research Centre of Finland - initial API and implementation\r
+ *******************************************************************************/\r
+package org.simantics.history;\r
+\r
+import org.simantics.databoard.Bindings;\r
+import org.simantics.databoard.accessor.StreamAccessor;\r
+import org.simantics.databoard.binding.Binding;\r
+import org.simantics.databoard.binding.NumberBinding;\r
+import org.simantics.databoard.binding.mutable.MutableVariant;\r
+import org.simantics.databoard.util.Bean;\r
+import org.simantics.history.impl.FlushPolicy;\r
+import org.simantics.history.util.subscription.SubscriptionItem;\r
+\r
+/**\r
+ * Collector manages recoding of variables to subscribed items.\r
+ * \r
+ * Single variable is typically recorded to multiple subscription items with\r
+ * different recording parameters. The variable source is identified with\r
+ * "variableId" field in historyItem (given at #addItem()).\r
+ * \r
+ * The actual collecting uses the following procedure:\r
+ * If same value repeats, or is considered repeating because of deadband or interval setting,\r
+ * then the values are packed in to a single entry (called value band). \r
+ * \r
+ * An entry can be represented with either (a) as ranged or as (b) non-ranged format.\r
+ * In ranged format, the entry represents multiple values from the datasource.\r
+ * There are fields such as: start time, end time, min, max value, first and last value. \r
+ * \r
+ * In non-ranged format, the entry represents a single sample from the datasource.\r
+ * The format is very simple (time, value). When same value repeats, two samples \r
+ * are written, one at the start of the new value, another at to represent the \r
+ * last entry with the same value. At run-time, the sample is forwarded in time.\r
+ * \r
+ * @author toni.kalajainen\r
+ */\r
+public interface Collector { \r
+\r
+ /**\r
+ * Get a snapshot of all the item configurations. \r
+ * \r
+ * Note, The resulting bean can be converted to {@link SubscriptionItem} or {@link HistoryAndCollectorItem} \r
+ * with {@link Bean#readAvailableFields(Bean)} method.\r
+ * \r
+ * Note, this bean also contains "collectorState" object.\r
+ * \r
+ * @return items \r
+ */\r
+ SubscriptionItem[] getItems();\r
+ \r
+ /**\r
+ * Subscribe an item. \r
+ * \r
+ * The item is opened when the collecting starts at {@link #beginStep(NumberBinding, Object)}. \r
+ * \r
+ * Collector requres these fields are required: \r
+ * o id - String \r
+ * o variableId - String\r
+ * o deadband - double\r
+ * o interval - double\r
+ * o gain - double\r
+ * o bias - double\r
+ * o enabled - boolean\r
+ * \r
+ * It is recommended to use {@link SubscriptionItem} or {@link HistoryAndCollectorItem}. \r
+ * Although you may use your own classes aslong as they have the fields and extend Bean.\r
+ * \r
+ * @param item\r
+ */\r
+ void addItem(Bean item) throws HistoryException;\r
+ void addItems(Bean...item) throws HistoryException;\r
+ \r
+ /**\r
+ * Remove the subscribed item from the collector. \r
+ * \r
+ * Item's CollectorState is written to the history's meta-data.\r
+ * "collectorState"-field is added if it did not exist. \r
+ * \r
+ * @param id \r
+ * @throws HistoryException\r
+ */\r
+ void removeItem(String id) throws HistoryException;\r
+ \r
+ /**\r
+ * Add or update subscription item. \r
+ * \r
+ * @param item\r
+ * @throws HistoryException\r
+ */\r
+ void setItem(Bean item) throws HistoryException; \r
+ \r
+ /**\r
+ * Get associated history manager\r
+ * \r
+ * @return history manager\r
+ */\r
+ HistoryManager getHistory();\r
+ \r
+ /**\r
+ * Get flush policy\r
+ * \r
+ * @return flush policy\r
+ */\r
+ FlushPolicy getFlushPolicy();\r
+\r
+ /**\r
+ * Set flush policy\r
+ * @param flushPolicy\r
+ */\r
+ void setFlushPolicy(FlushPolicy flushPolicy);\r
+\r
+ /**\r
+ * Begin a new time step.\r
+ * \r
+ * @param binding (for example {@link Bindings#DOUBLE})\r
+ * @param time\r
+ * @throws HistoryException\r
+ */\r
+ void beginStep(NumberBinding binding, Object time) throws HistoryException;\r
+\r
+ /**\r
+ * Get current time\r
+ * \r
+ * @param binding\r
+ * @return\r
+ * @throws HistoryException\r
+ */\r
+ Object getTime(Binding binding) throws HistoryException;\r
+ \r
+ /**\r
+ * Set a value for a variable. If there are multiple items for one \r
+ * variable, the value is written to all streams.\r
+ * \r
+ * @param id\r
+ * @param binding\r
+ * @param value\r
+ * @throws HistoryException\r
+ */\r
+ void setValue(String id, Binding binding, Object value) throws HistoryException;\r
+ \r
+ /**\r
+ * Get the value the collector has about a variable.\r
+ * \r
+ * @param id\r
+ * @param binding in which to get result \r
+ * @return true if value existed\r
+ */\r
+ Object getValue(String id, Binding binding) throws HistoryException;\r
+ boolean getValue(String id, MutableVariant result);\r
+ \r
+ /**\r
+ * End the time step. Values are commited to history. \r
+ * \r
+ * @throws HistoryException\r
+ */\r
+ void endStep() throws HistoryException;\r
+ \r
+ /**\r
+ * Flush any pending changes to all time series.\r
+ * \r
+ * A few flush policies are, to flush after every step (not good \r
+ * performance), to flush on time interval, say, every second. \r
+ * And third, to flush after one second since last flush and step.\r
+ * \r
+ * @throws HistoryException\r
+ */\r
+ void flush() throws HistoryException;\r
+\r
+ /**\r
+ * Save and Close the collector session.\r
+ * CollectorStates are written back to the history. \r
+ * "collectorState"-field is added if it did not exist. \r
+ */\r
+ void close();\r
+\r
+ /**\r
+ * Open stream from associated history manager\r
+ * \r
+ * @param itemId\r
+ * @param mode\r
+ * @return accessor\r
+ * @throws HistoryException\r
+ */\r
+ StreamAccessor openStream(String itemId, String mode) throws HistoryException;\r
+\r
+ /**\r
+ * Get the complete state of this collector as a bean. Required for\r
+ * supporting serialization of the internal collector state.\r
+ * \r
+ * Not intended to be thread-safe, i.e. do not invoke this while in a\r
+ * collection step.\r
+ * \r
+ * @return current collector state data\r
+ */\r
+ Bean getState();\r
+\r
+ /**\r
+ * Required for supporting deserialization of the internal collector state.\r
+ * Do not invoke this during data collection. It is only intended for\r
+ * initializing a collector instance properly when a collector is used for\r
+ * appending to an existing history.\r
+ * \r
+ * @param newState\r
+ * a new complete state to set for this collector. Must be a\r
+ * value that's been previously retrieved from\r
+ * {@link #getCollectorState()}.\r
+ */\r
+ void setState(Bean newState);\r
+\r
+}\r
Code Review / simantics / platform.git / blobdiff