- * - * If the item does not exist, the item is created. - * - * @param descs - * @throws HistoryException - */ - void modify(Bean...descs) throws HistoryException; - - /** - * Get item description. If item does not exist, an exception is thrown. - * - * @param itemId - * @return subscription info - * @throws HistoryException - */ - Bean getItem(String itemId) throws HistoryException; - - /** - * Tests if item exists in the history. - * - * @param itemId - * @return - * @throws HistoryException - */ - boolean exists(String itemId) throws HistoryException; - - /** - * Get a snapshot of item descriptions. - * - * Note, ItemManager class is a higher level utility for managing the list of - * items this method returns. - * - * @return all items - * @throws HistoryException - */ - Bean[] getItems() throws HistoryException; - - /** - * Close the history manager. Note, this does not close open streams. - */ - void close(); - - /** - * Open an accessor to a stream file. Time series may be opened in - * read or read/write mode. Read mode may be opened even the time series - * is open in a collector session. Opening may fail if group operation is - * underway (modify/delete). - * - * The accessor must be closed after use. - * - * Note, if the data is changed due to an open session, the changes may not - * reflect to the stream accessor. You need to {@link StreamAccessor#reset()} - * the accessor to flush internal caches. - * - * @param itemId - * @param mode either "r" or "rw" - * @return accessor to stream samples. - * @throws HistoryException - */ - StreamAccessor openStream(String itemId, String mode) throws HistoryException; - -} +/******************************************************************************* + * Copyright (c) 2007, 2011 Association for Decentralized Information Management in + * Industry THTH ry. + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Eclipse Public License v1.0 + * which accompanies this distribution, and is available at + * http://www.eclipse.org/legal/epl-v10.html + * + * Contributors: + * VTT Technical Research Centre of Finland - initial API and implementation + *******************************************************************************/ +package org.simantics.history; + +import org.simantics.databoard.accessor.StreamAccessor; +import org.simantics.databoard.util.Bean; +import org.simantics.history.util.subscription.SubscriptionItem; + +/** + * HistoryManager is a keeper and manager of streams. + * + * Note, use {@link ItemManager} for handling groups of history items. + * + * @author toni.kalajainen + */ +public interface HistoryManager { + + /** + * Create a new items. This will initialize the necessary files. + * A description is a record and that has at minimum the following fields: + * { id : String, format: Datatype }. Other records may also exist but + * they are not used by HistoryManager. + * + * If item with the same Id exists an exception is thrown. + * + * It is recommended to use {@link SubscriptionItem} class. + * + * @see SubscriptionItem + * @param descs + * @throws HistoryException + */ + void create(Bean...descs) throws HistoryException; + + /** + * Delete a item. If an item by id does not exist, nothing happens. + * If there was problem deleting the item, an exception is thrown. + * + * @param itemIds item ids + * @throws HistoryException + */ + void delete(String...itemIds) throws HistoryException; + + /** + * Modify an settings of existing items. If format is changed, the + * implementation may thrown an exception.
+ * + * If the item does not exist, the item is created. + * + * @param descs + * @throws HistoryException + */ + void modify(Bean...descs) throws HistoryException; + + /** + * Get item description. If item does not exist, an exception is thrown. + * + * @param itemId + * @return subscription info + * @throws HistoryException + */ + Bean getItem(String itemId) throws HistoryException; + + /** + * Tests if item exists in the history. + * + * @param itemId + * @return + * @throws HistoryException + */ + boolean exists(String itemId) throws HistoryException; + + /** + * Get a snapshot of item descriptions. + * + * Note, ItemManager class is a higher level utility for managing the list of + * items this method returns. + * + * @return all items + * @throws HistoryException + */ + Bean[] getItems() throws HistoryException; + + /** + * Close the history manager. Note, this does not close open streams. + */ + void close(); + + /** + * Open an accessor to a stream file. Time series may be opened in + * read or read/write mode. Read mode may be opened even the time series + * is open in a collector session. Opening may fail if group operation is + * underway (modify/delete). + * + * The accessor must be closed after use. + * + * Note, if the data is changed due to an open session, the changes may not + * reflect to the stream accessor. You need to {@link StreamAccessor#reset()} + * the accessor to flush internal caches. + * + * @param itemId + * @param mode either "r" or "rw" + * @return accessor to stream samples. + * @throws HistoryException + */ + StreamAccessor openStream(String itemId, String mode) throws HistoryException; + +}