bundles/org.simantics.history/src/org/simantics/history/HistoryManager.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.accessor.StreamAccessor;\r
  15 import org.simantics.databoard.util.Bean;\r
  16 import org.simantics.history.util.subscription.SubscriptionItem;\r
  17 \r
  18 /**\r
  19  * HistoryManager is a keeper and manager of streams.\r
  20  * \r
  21  * Note, use {@link ItemManager} for handling groups of history items. \r
  22  * \r
  23  * @author toni.kalajainen\r
  24  */\r
  25 public interface HistoryManager {\r
  26         \r
  27         /**\r
  28          * Create a new items. This will initialize the necessary files.\r
  29          * A description is a record and that has at minimum the following fields:\r
  30          * { id : String, format: Datatype }. Other records may also exist but\r
  31          * they are not used by HistoryManager. \r
  32          *  \r
  33          * If item with the same Id exists an exception is thrown.\r
  34          * \r
  35          * It is recommended to use {@link SubscriptionItem} class.\r
  36          * \r
  37          * @see SubscriptionItem\r
  38          * @param descs\r
  39          * @throws HistoryException\r
  40          */\r
  41         void create(Bean...descs) throws HistoryException; \r
  42         \r
  43         /**\r
  44          * Delete a item. If an item by id does not exist, nothing happens.\r
  45          * If there was problem deleting the item, an exception is thrown. \r
  46          *       \r
  47          * @param itemIds item ids\r
  48          * @throws HistoryException\r
  49          */\r
  50         void delete(String...itemIds) throws HistoryException;\r
  51         \r
  52         /**\r
  53          * Modify an settings of existing items. If format is changed, the\r
  54          * implementation may thrown an exception.<p> \r
  55          * \r
  56          * If the item does not exist, the item is created.  \r
  57          * \r
  58          * @param descs \r
  59          * @throws HistoryException\r
  60          */\r
  61         void modify(Bean...descs) throws HistoryException;\r
  62 \r
  63         /**\r
  64          * Get item description. If item does not exist, an exception is thrown.\r
  65          * \r
  66          * @param itemId\r
  67          * @return subscription info\r
  68          * @throws HistoryException\r
  69          */\r
  70         Bean getItem(String itemId) throws HistoryException;\r
  71         \r
  72         /**\r
  73          * Tests if item exists in the history. \r
  74          * \r
  75          * @param itemId\r
  76          * @return\r
  77          * @throws HistoryException\r
  78          */\r
  79         boolean exists(String itemId) throws HistoryException;  \r
  80                         \r
  81         /**\r
  82          * Get a snapshot of item descriptions. \r
  83          * \r
  84          * Note, ItemManager class is a higher level utility for managing the list of \r
  85          * items this method returns. \r
  86          * \r
  87          * @return all items\r
  88          * @throws HistoryException\r
  89          */\r
  90         Bean[] getItems() throws HistoryException;\r
  91         \r
  92         /**\r
  93          * Close the history manager. Note, this does not close open streams. \r
  94          */\r
  95         void close();\r
  96         \r
  97         /**\r
  98          * Open an accessor to a stream file. Time series may be opened in \r
  99          * read or read/write mode. Read mode may be opened even the time series\r
 100          * is open in a collector session. Opening may fail if group operation is \r
 101          * underway (modify/delete).\r
 102          * \r
 103          * The accessor must be closed after use.\r
 104          * \r
 105          * Note, if the data is changed due to an open session, the changes may not\r
 106          * reflect to the stream accessor. You need to {@link StreamAccessor#reset()}\r
 107          * the accessor to flush internal caches.\r
 108          * \r
 109          * @param itemId\r
 110          * @param mode either "r" or "rw"\r
 111          * @return accessor to stream samples.\r
 112          * @throws HistoryException\r
 113          */\r
 114         StreamAccessor openStream(String itemId, String mode) throws HistoryException;\r
 115 \r
 116 }\r