org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/statesystem/helpers/IStateHistoryBackend.java

   1 /*******************************************************************************
   2  * Copyright (c) 2012 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.tmf.core.statesystem.helpers;
  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.tmf.core.interval.ITmfStateInterval;
  21 import org.eclipse.linuxtools.tmf.core.statesystem.AttributeNotFoundException;
  22 import org.eclipse.linuxtools.tmf.core.statesystem.TimeRangeException;
  23 import org.eclipse.linuxtools.tmf.core.statevalue.ITmfStateValue;
  24
  25 /**
  26  * The main difference between StateSystem and StateHistorySystem is that SHS
  27  * allows 'seeking' back in time to reload a Current State at a previous time.
  28  * "How to go back in time" is defined by the implementation of the
  29  * HistoryBackend.
  30  *
  31  * A StateHistorySystem contains one and only one HistoryBackend. If you want to
  32  * use a paradigm with more than one provider (eg. more or less precision
  33  * depending on what's asked by the user), implement one wrapper HistoryBackend
  34  * which can then contain your 2-3 other backends underneath.
  35  *
  36  * @author alexmont
  37  *
  38  */
  39 public interface IStateHistoryBackend {
  40
  41     /**
  42      * Get the start time of this state history. This is usually the same as the
  43      * start time of the originating trace.
  44      *
  45      * @return The start time
  46      */
  47     public long getStartTime();
  48
  49     /**
  50      * Get the current end time of the state history. It will change as the
  51      * history is being built.
  52      *
  53      * @return The end time
  54      */
  55     public long getEndTime();
  56
  57     /**
  58      * Main method to insert state intervals into the history.
  59      *
  60      * @param stateStartTime
  61      *            The start time of the interval
  62      * @param stateEndTime
  63      *            The end time of the interval
  64      * @param quark
  65      *            The quark of the attribute this interval refers to
  66      * @param value
  67      *            The StateValue represented by this interval
  68      * @throws TimeRangeException
  69      *             If the start or end time are invalid
  70      */
  71     // FIXME change to IStateInterval?
  72     public void insertPastState(long stateStartTime, long stateEndTime,
  73             int quark, ITmfStateValue value) throws TimeRangeException;
  74
  75     /**
  76      * Indicate to the provider that we are done building the history (so it can
  77      * close off, stop threads, etc.)
  78      *
  79      * @param endTime
  80      *            The end time to assign to this state history. It could be
  81      *            farther in time than the last state inserted, for example.
  82      * @throws TimeRangeException
  83      *             If the requested time makes no sense.
  84      */
  85     public void finishedBuilding(long endTime) throws TimeRangeException;
  86
  87     /**
  88      * It is the responsibility of the backend to define where to save the
  89      * Attribute Tree (since it's only useful to "reopen" an Attribute Tree if
  90      * we have the matching History).
  91      *
  92      * This method defines where to read for the attribute tree when opening an
  93      * already-existing history. Refer to the file format documentation.
  94      *
  95      * @return A FileInputStream object pointing to the correct file/location in
  96      *         the file where to read the attribute tree information.
  97      */
  98     public FileInputStream supplyAttributeTreeReader();
  99
 100     // FIXME change to FOS too?
 101     public File supplyAttributeTreeWriterFile();
 102
 103     public long supplyAttributeTreeWriterFilePosition();
 104
 105     /**
 106      * @name Query methods
 107      */
 108
 109     /**
 110      * Complete "give me the state at a given time" method 'currentStateInfo' is
 111      * an "out" parameter, that is, write to it the needed information and
 112      * return. DO NOT 'new' currentStateInfo, it will be lost and nothing will
 113      * be returned!
 114      *
 115      * @param currentStateInfo
 116      *            List of StateValues (index == quark) to fill up
 117      * @param t
 118      *            Target timestamp of the query
 119      */
 120     public void doQuery(List<ITmfStateInterval> currentStateInfo, long t)
 121             throws TimeRangeException;
 122
 123     /**
 124      * Some providers might want to specify a different way to obtain just a
 125      * single StateValue instead of updating the whole list. If the method to
 126      * use is the same, then feel free to just implement this as a wrapper using
 127      * doQuery().
 128      *
 129      * @param t
 130      *            The target timestamp of the query.
 131      * @param attributeQuark
 132      *            The single attribute for which you want the state interval
 133      * @return The state interval matching this timestamp/attribute pair
 134      * @throws TimeRangeException
 135      *             If the timestamp was invalid
 136      * @throws AttributeNotFoundException
 137      *             If the quark was invalid
 138      */
 139     public ITmfStateInterval doSingularQuery(long t, int attributeQuark)
 140             throws TimeRangeException, AttributeNotFoundException;
 141
 142     /**
 143      * Debug method to print the contents of the history backend.
 144      *
 145      * @param writer
 146      *            The PrintWriter where to write the output
 147      */
 148     public void debugPrint(PrintWriter writer);
 149 }