X-Git-Url: https://gerrit.simantics.org/r/gitweb?a=blobdiff_plain;f=bundles%2Forg.simantics.history%2Fsrc%2Forg%2Fsimantics%2Fhistory%2FCollector.java;h=234c832f52dc640e8097067b9876830d71dcaa91;hb=refs%2Fchanges%2F38%2F238%2F2;hp=01624fe6da392a2b50731da79d2cd6d4bdddbd19;hpb=969bd23cab98a79ca9101af33334000879fb60c5;p=simantics%2Fplatform.git diff --git a/bundles/org.simantics.history/src/org/simantics/history/Collector.java b/bundles/org.simantics.history/src/org/simantics/history/Collector.java index 01624fe6d..234c832f5 100644 --- a/bundles/org.simantics.history/src/org/simantics/history/Collector.java +++ b/bundles/org.simantics.history/src/org/simantics/history/Collector.java @@ -1,218 +1,218 @@ -/******************************************************************************* - * 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); - -} +/******************************************************************************* + * 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); + +}