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