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

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