org.eclipse.tracecompass.statesystem.core/src/org/eclipse/linuxtools/statesystem/core/backend/IStateHistoryBackend.java

   1 /*******************************************************************************
   2  * Copyright (c) 2012, 2013 Ericsson
   3  * Copyright (c) 2010, 2011 École Polytechnique de Montréal
   4  * Copyright (c) 2010, 2011 Alexandre Montplaisir <alexandre.montplaisir@gmail.com>
   5  *
   6  * All rights reserved. This program and the accompanying materials are
   7  * made available under the terms of the Eclipse Public License v1.0 which
   8  * accompanies this distribution, and is available at
   9  * http://www.eclipse.org/legal/epl-v10.html
  10  *
  11  *******************************************************************************/
  12
  13 package org.eclipse.linuxtools.statesystem.core.backend;
  14
  15 import java.io.File;
  16 import java.io.FileInputStream;
  17 import java.io.PrintWriter;
  18 import java.util.List;
  19
  20 import org.eclipse.linuxtools.statesystem.core.exceptions.AttributeNotFoundException;
  21 import org.eclipse.linuxtools.statesystem.core.exceptions.StateSystemDisposedException;
  22 import org.eclipse.linuxtools.statesystem.core.exceptions.TimeRangeException;
  23 import org.eclipse.linuxtools.statesystem.core.interval.ITmfStateInterval;
  24 import org.eclipse.linuxtools.statesystem.core.statevalue.ITmfStateValue;
  25
  26 /**
  27  * The main difference between StateSystem and StateHistorySystem is that SHS
  28  * allows 'seeking' back in time to reload a Current State at a previous time.
  29  * "How to go back in time" is defined by the implementation of the
  30  * HistoryBackend.
  31  *
  32  * A StateHistorySystem contains one and only one HistoryBackend. If you want to
  33  * use a paradigm with more than one provider (eg. more or less precision
  34  * depending on what's asked by the user), implement one wrapper HistoryBackend
  35  * which can then contain your 2-3 other backends underneath.
  36  *
  37  * @author Alexandre Montplaisir
  38  * @since 3.0
  39  */
  40 public interface IStateHistoryBackend {
  41
  42     /**
  43      * Get the start time of this state history. This is usually the same as the
  44      * start time of the originating trace.
  45      *
  46      * @return The start time
  47      */
  48     long getStartTime();
  49
  50     /**
  51      * Get the current end time of the state history. It will change as the
  52      * history is being built.
  53      *
  54      * @return The end time
  55      */
  56     long getEndTime();
  57
  58     /**
  59      * Main method to insert state intervals into the history.
  60      *
  61      * @param stateStartTime
  62      *            The start time of the interval
  63      * @param stateEndTime
  64      *            The end time of the interval
  65      * @param quark
  66      *            The quark of the attribute this interval refers to
  67      * @param value
  68      *            The StateValue represented by this interval
  69      * @throws TimeRangeException
  70      *             If the start or end time are invalid
  71      */
  72     // FIXME change to IStateInterval?
  73     void insertPastState(long stateStartTime, long stateEndTime,
  74             int quark, ITmfStateValue value) throws TimeRangeException;
  75
  76     /**
  77      * Indicate to the provider that we are done building the history (so it can
  78      * close off, stop threads, etc.)
  79      *
  80      * @param endTime
  81      *            The end time to assign to this state history. It could be
  82      *            farther in time than the last state inserted, for example.
  83      * @throws TimeRangeException
  84      *             If the requested time makes no sense.
  85      */
  86     void finishedBuilding(long endTime) throws TimeRangeException;
  87
  88     /**
  89      * It is the responsibility of the backend to define where to save the
  90      * Attribute Tree (since it's only useful to "reopen" an Attribute Tree if
  91      * we have the matching History).
  92      *
  93      * This method defines where to read for the attribute tree when opening an
  94      * already-existing history. Refer to the file format documentation.
  95      *
  96      * @return A FileInputStream object pointing to the correct file/location in
  97      *         the file where to read the attribute tree information.
  98      */
  99     FileInputStream supplyAttributeTreeReader();
 100
 101     // FIXME change to FOS too?
 102     /**
 103      * Supply the File object to which we will write the attribute tree. The
 104      * position in this file is supplied by -TreeWriterFilePosition.
 105      *
 106      * @return The target File
 107      */
 108     File supplyAttributeTreeWriterFile();
 109
 110     /**
 111      * Supply the position in the file where we should write the attribute tree
 112      * when asked to.
 113      *
 114      * @return The file position (we will seek() to it)
 115      */
 116     long supplyAttributeTreeWriterFilePosition();
 117
 118     /**
 119      * Delete any generated files or anything that might have been created by
 120      * the history backend (either temporary or save files). By calling this, we
 121      * return to the state as it was before ever building the history.
 122      *
 123      * You might not want to call automatically if, for example, you want an
 124      * index file to persist on disk. This could be limited to actions
 125      * originating from the user.
 126      */
 127     void removeFiles();
 128
 129     /**
 130      * Notify the state history back-end that the trace is being closed, so it
 131      * should release its file descriptors, close its connections, etc.
 132      */
 133     void dispose();
 134
 135     // ------------------------------------------------------------------------
 136     // Query methods
 137     // ------------------------------------------------------------------------
 138
 139     /**
 140      * Complete "give me the state at a given time" method 'currentStateInfo' is
 141      * an "out" parameter, that is, write to it the needed information and
 142      * return. DO NOT 'new' currentStateInfo, it will be lost and nothing will
 143      * be returned!
 144      *
 145      * @param currentStateInfo
 146      *            List of StateValues (index == quark) to fill up
 147      * @param t
 148      *            Target timestamp of the query
 149      * @throws TimeRangeException
 150      *             If the timestamp is outside of the history/trace
 151      * @throws StateSystemDisposedException
 152      *             If the state system is disposed while a request is ongoing.
 153      */
 154     void doQuery(List<ITmfStateInterval> currentStateInfo, long t)
 155             throws TimeRangeException, StateSystemDisposedException;
 156
 157     /**
 158      * Some providers might want to specify a different way to obtain just a
 159      * single StateValue instead of updating the whole list. If the method to
 160      * use is the same, then feel free to just implement this as a wrapper using
 161      * doQuery().
 162      *
 163      * @param t
 164      *            The target timestamp of the query.
 165      * @param attributeQuark
 166      *            The single attribute for which you want the state interval
 167      * @return The state interval matching this timestamp/attribute pair
 168      * @throws TimeRangeException
 169      *             If the timestamp was invalid
 170      * @throws AttributeNotFoundException
 171      *             If the quark was invalid
 172      * @throws StateSystemDisposedException
 173      *             If the state system is disposed while a request is ongoing.
 174      */
 175     ITmfStateInterval doSingularQuery(long t, int attributeQuark)
 176             throws TimeRangeException, AttributeNotFoundException,
 177             StateSystemDisposedException;
 178
 179     /**
 180      * Simple check to make sure the requested timestamps are within the borders
 181      * of this state history. This is used internally, but could also be used by
 182      * the request sender (to check before sending in a lot of requests for
 183      * example).
 184      *
 185      * @param t
 186      *            The queried timestamp
 187      * @return True if the timestamp is within range, false if not.
 188      */
 189     boolean checkValidTime(long t);
 190
 191     /**
 192      * Debug method to print the contents of the history backend.
 193      *
 194      * @param writer
 195      *            The PrintWriter where to write the output
 196      */
 197     void debugPrint(PrintWriter writer);
 198 }