1 /*******************************************************************************
2 * Copyright (c) 2007, 2011 Association for Decentralized Information Management in
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
10 * VTT Technical Research Centre of Finland - initial API and implementation
11 *******************************************************************************/
12 package org.simantics.history;
14 import org.simantics.databoard.accessor.StreamAccessor;
15 import org.simantics.databoard.util.Bean;
16 import org.simantics.history.util.subscription.SubscriptionItem;
19 * HistoryManager is a keeper and manager of streams.
21 * Note, use {@link ItemManager} for handling groups of history items.
23 * @author toni.kalajainen
25 public interface HistoryManager {
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.
33 * If item with the same Id exists an exception is thrown.
35 * It is recommended to use {@link SubscriptionItem} class.
37 * @see SubscriptionItem
39 * @throws HistoryException
41 void create(Bean...descs) throws HistoryException;
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.
47 * @param itemIds item ids
48 * @throws HistoryException
50 void delete(String...itemIds) throws HistoryException;
53 * Modify an settings of existing items. If format is changed, the
54 * implementation may thrown an exception.<p>
56 * If the item does not exist, the item is created.
59 * @throws HistoryException
61 void modify(Bean...descs) throws HistoryException;
64 * Get item description. If item does not exist, an exception is thrown.
67 * @return subscription info
68 * @throws HistoryException
70 Bean getItem(String itemId) throws HistoryException;
73 * Tests if item exists in the history.
77 * @throws HistoryException
79 boolean exists(String itemId) throws HistoryException;
82 * Get a snapshot of item descriptions.
84 * Note, ItemManager class is a higher level utility for managing the list of
85 * items this method returns.
88 * @throws HistoryException
90 Bean[] getItems() throws HistoryException;
93 * Close the history manager. Note, this does not close open streams.
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).
103 * The accessor must be closed after use.
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.
110 * @param mode either "r" or "rw"
111 * @return accessor to stream samples.
112 * @throws HistoryException
114 StreamAccessor openStream(String itemId, String mode) throws HistoryException;