bundles/org.simantics.history/src/org/simantics/history/HistoryManager.java

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