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