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>
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
11 *******************************************************************************/
13 package org
.eclipse
.linuxtools
.tmf
.core
.statesystem
;
16 import java
.io
.FileInputStream
;
17 import java
.io
.PrintWriter
;
18 import java
.util
.List
;
20 import org
.eclipse
.linuxtools
.tmf
.core
.exceptions
.AttributeNotFoundException
;
21 import org
.eclipse
.linuxtools
.tmf
.core
.exceptions
.TimeRangeException
;
22 import org
.eclipse
.linuxtools
.tmf
.core
.interval
.ITmfStateInterval
;
23 import org
.eclipse
.linuxtools
.tmf
.core
.statevalue
.ITmfStateValue
;
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
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.
39 public interface IStateHistoryBackend
{
42 * Get the start time of this state history. This is usually the same as the
43 * start time of the originating trace.
45 * @return The start time
47 public long getStartTime();
50 * Get the current end time of the state history. It will change as the
51 * history is being built.
53 * @return The end time
55 public long getEndTime();
58 * Main method to insert state intervals into the history.
60 * @param stateStartTime
61 * The start time of the interval
63 * The end time of the interval
65 * The quark of the attribute this interval refers to
67 * The StateValue represented by this interval
68 * @throws TimeRangeException
69 * If the start or end time are invalid
71 // FIXME change to IStateInterval?
72 public void insertPastState(long stateStartTime
, long stateEndTime
,
73 int quark
, ITmfStateValue value
) throws TimeRangeException
;
76 * Indicate to the provider that we are done building the history (so it can
77 * close off, stop threads, etc.)
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.
85 public void finishedBuilding(long endTime
) throws TimeRangeException
;
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).
92 * This method defines where to read for the attribute tree when opening an
93 * already-existing history. Refer to the file format documentation.
95 * @return A FileInputStream object pointing to the correct file/location in
96 * the file where to read the attribute tree information.
98 public FileInputStream
supplyAttributeTreeReader();
100 // FIXME change to FOS too?
101 public File
supplyAttributeTreeWriterFile();
103 public long supplyAttributeTreeWriterFilePosition();
106 * @name Query methods
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
115 * @param currentStateInfo
116 * List of StateValues (index == quark) to fill up
118 * Target timestamp of the query
120 public void doQuery(List
<ITmfStateInterval
> currentStateInfo
, long t
)
121 throws TimeRangeException
;
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
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
139 public ITmfStateInterval
doSingularQuery(long t
, int attributeQuark
)
140 throws TimeRangeException
, AttributeNotFoundException
;
143 * Simple check to make sure the requested timestamps are within the borders
144 * of this state history. This is used internally, but could also be used
145 * by the request sender (to check before sending in a lot of requests for
149 * The queried timestamp
150 * @return True if the timestamp is within range, false if not.
152 public boolean checkValidTime(long t
);
155 * Debug method to print the contents of the history backend.
158 * The PrintWriter where to write the output
160 public void debugPrint(PrintWriter writer
);