Migrated source code from Simantics SVN

[simantics/platform.git] / bundles / org.simantics.history / src / org / simantics / history / HistoryManager.java

diff --git a/bundles/org.simantics.history/src/org/simantics/history/HistoryManager.java b/bundles/org.simantics.history/src/org/simantics/history/HistoryManager.java
new file mode 100644 (file)
index 0000000..b7bf612
--- /dev/null
+++ b/bundles/org.simantics.history/src/org/simantics/history/HistoryManager.java
@@ -0,0 +1,116 @@
+/*******************************************************************************\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.accessor.StreamAccessor;\r
+import org.simantics.databoard.util.Bean;\r
+import org.simantics.history.util.subscription.SubscriptionItem;\r
+\r
+/**\r
+ * HistoryManager is a keeper and manager of streams.\r
+ * \r
+ * Note, use {@link ItemManager} for handling groups of history items. \r
+ * \r
+ * @author toni.kalajainen\r
+ */\r
+public interface HistoryManager {\r
+       \r
+       /**\r
+        * Create a new items. This will initialize the necessary files.\r
+        * A description is a record and that has at minimum the following fields:\r
+        * { id : String, format: Datatype }. Other records may also exist but\r
+        * they are not used by HistoryManager. \r
+        *  \r
+        * If item with the same Id exists an exception is thrown.\r
+        * \r
+        * It is recommended to use {@link SubscriptionItem} class.\r
+        * \r
+        * @see SubscriptionItem\r
+        * @param descs\r
+        * @throws HistoryException\r
+        */\r
+       void create(Bean...descs) throws HistoryException; \r
+       \r
+       /**\r
+        * Delete a item. If an item by id does not exist, nothing happens.\r
+        * If there was problem deleting the item, an exception is thrown. \r
+        *       \r
+        * @param itemIds item ids\r
+        * @throws HistoryException\r
+        */\r
+       void delete(String...itemIds) throws HistoryException;\r
+       \r
+       /**\r
+        * Modify an settings of existing items. If format is changed, the\r
+        * implementation may thrown an exception.<p> \r
+        * \r
+        * If the item does not exist, the item is created.  \r
+        * \r
+        * @param descs \r
+        * @throws HistoryException\r
+        */\r
+       void modify(Bean...descs) throws HistoryException;\r
+\r
+       /**\r
+        * Get item description. If item does not exist, an exception is thrown.\r
+        * \r
+        * @param itemId\r
+        * @return subscription info\r
+        * @throws HistoryException\r
+        */\r
+       Bean getItem(String itemId) throws HistoryException;\r
+       \r
+       /**\r
+        * Tests if item exists in the history. \r
+        * \r
+        * @param itemId\r
+        * @return\r
+        * @throws HistoryException\r
+        */\r
+       boolean exists(String itemId) throws HistoryException;  \r
+                       \r
+       /**\r
+        * Get a snapshot of item descriptions. \r
+        * \r
+        * Note, ItemManager class is a higher level utility for managing the list of \r
+        * items this method returns. \r
+        * \r
+        * @return all items\r
+        * @throws HistoryException\r
+        */\r
+       Bean[] getItems() throws HistoryException;\r
+       \r
+       /**\r
+        * Close the history manager. Note, this does not close open streams. \r
+        */\r
+       void close();\r
+       \r
+       /**\r
+        * Open an accessor to a stream file. Time series may be opened in \r
+        * read or read/write mode. Read mode may be opened even the time series\r
+        * is open in a collector session. Opening may fail if group operation is \r
+        * underway (modify/delete).\r
+        * \r
+        * The accessor must be closed after use.\r
+        * \r
+        * Note, if the data is changed due to an open session, the changes may not\r
+        * reflect to the stream accessor. You need to {@link StreamAccessor#reset()}\r
+        * the accessor to flush internal caches.\r
+        * \r
+        * @param itemId\r
+        * @param mode either "r" or "rw"\r
+        * @return accessor to stream samples.\r
+        * @throws HistoryException\r
+        */\r
+       StreamAccessor openStream(String itemId, String mode) throws HistoryException;\r
+\r
+}\r