Commit | Line | Data |
---|---|---|
a52fde77 | 1 | /******************************************************************************* |
ed902a2b | 2 | * Copyright (c) 2012, 2014 Ericsson |
a52fde77 AM |
3 | * Copyright (c) 2010, 2011 École Polytechnique de Montréal |
4 | * Copyright (c) 2010, 2011 Alexandre Montplaisir <alexandre.montplaisir@gmail.com> | |
5df842b3 | 5 | * |
a52fde77 AM |
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 | |
5df842b3 | 10 | * |
a52fde77 AM |
11 | *******************************************************************************/ |
12 | ||
e894a508 | 13 | package org.eclipse.tracecompass.statesystem.core.backend; |
a52fde77 AM |
14 | |
15 | import java.io.File; | |
16 | import java.io.FileInputStream; | |
a52fde77 AM |
17 | import java.util.List; |
18 | ||
feea3b3c | 19 | import org.eclipse.jdt.annotation.NonNull; |
aa353506 | 20 | import org.eclipse.jdt.annotation.Nullable; |
5d279031 LPD |
21 | import org.eclipse.tracecompass.internal.provisional.datastore.core.condition.IntegerRangeCondition; |
22 | import org.eclipse.tracecompass.internal.provisional.datastore.core.condition.TimeRangeCondition; | |
e894a508 AM |
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; | |
a52fde77 AM |
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. | |
5df842b3 | 33 | * |
a52fde77 AM |
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. | |
5df842b3 | 38 | * |
bcec0116 | 39 | * @author Alexandre Montplaisir |
a52fde77 AM |
40 | */ |
41 | public interface IStateHistoryBackend { | |
42 | ||
b2f62cb5 AM |
43 | /** |
44 | * Get the ID of the state system that populates this backend. | |
45 | * | |
46 | * @return The state system's ID. | |
dbc7991d | 47 | * @since 1.0 |
b2f62cb5 AM |
48 | */ |
49 | @NonNull String getSSID(); | |
50 | ||
a52fde77 AM |
51 | /** |
52 | * Get the start time of this state history. This is usually the same as the | |
53 | * start time of the originating trace. | |
5df842b3 | 54 | * |
a52fde77 AM |
55 | * @return The start time |
56 | */ | |
57a2a5ca | 57 | long getStartTime(); |
a52fde77 AM |
58 | |
59 | /** | |
60 | * Get the current end time of the state history. It will change as the | |
61 | * history is being built. | |
5df842b3 | 62 | * |
a52fde77 AM |
63 | * @return The end time |
64 | */ | |
57a2a5ca | 65 | long getEndTime(); |
a52fde77 AM |
66 | |
67 | /** | |
68 | * Main method to insert state intervals into the history. | |
5df842b3 | 69 | * |
a52fde77 AM |
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? | |
57a2a5ca | 82 | void insertPastState(long stateStartTime, long stateEndTime, |
aa353506 | 83 | int quark, @NonNull ITmfStateValue value) throws TimeRangeException; |
a52fde77 AM |
84 | |
85 | /** | |
86 | * Indicate to the provider that we are done building the history (so it can | |
87 | * close off, stop threads, etc.) | |
5df842b3 | 88 | * |
a52fde77 AM |
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 | */ | |
57a2a5ca | 95 | void finishedBuilding(long endTime) throws TimeRangeException; |
a52fde77 AM |
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). | |
5df842b3 | 101 | * |
a52fde77 AM |
102 | * This method defines where to read for the attribute tree when opening an |
103 | * already-existing history. Refer to the file format documentation. | |
5df842b3 | 104 | * |
a52fde77 AM |
105 | * @return A FileInputStream object pointing to the correct file/location in |
106 | * the file where to read the attribute tree information. | |
107 | */ | |
57a2a5ca | 108 | FileInputStream supplyAttributeTreeReader(); |
a52fde77 AM |
109 | |
110 | // FIXME change to FOS too? | |
5df842b3 AM |
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 | */ | |
57a2a5ca | 117 | File supplyAttributeTreeWriterFile(); |
a52fde77 | 118 | |
5df842b3 AM |
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 | */ | |
57a2a5ca | 125 | long supplyAttributeTreeWriterFilePosition(); |
a52fde77 | 126 | |
36bf82a2 AM |
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. | |
5df842b3 | 131 | * |
36bf82a2 AM |
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 | */ | |
57a2a5ca | 136 | void removeFiles(); |
36bf82a2 | 137 | |
1a4205d9 AM |
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 | */ | |
57a2a5ca | 142 | void dispose(); |
1a4205d9 | 143 | |
3b7f5abe AM |
144 | // ------------------------------------------------------------------------ |
145 | // Query methods | |
146 | // ------------------------------------------------------------------------ | |
a52fde77 AM |
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! | |
5df842b3 | 153 | * |
a52fde77 AM |
154 | * @param currentStateInfo |
155 | * List of StateValues (index == quark) to fill up | |
156 | * @param t | |
157 | * Target timestamp of the query | |
5df842b3 AM |
158 | * @throws TimeRangeException |
159 | * If the timestamp is outside of the history/trace | |
3b7f5abe AM |
160 | * @throws StateSystemDisposedException |
161 | * If the state system is disposed while a request is ongoing. | |
a52fde77 | 162 | */ |
aa353506 | 163 | void doQuery(@NonNull List<@Nullable ITmfStateInterval> currentStateInfo, long t) |
3b7f5abe | 164 | throws TimeRangeException, StateSystemDisposedException; |
a52fde77 AM |
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(). | |
5df842b3 | 171 | * |
a52fde77 AM |
172 | * @param t |
173 | * The target timestamp of the query. | |
174 | * @param attributeQuark | |
175 | * The single attribute for which you want the state interval | |
ed48dc75 PT |
176 | * @return The state interval matching this timestamp/attribute pair, or |
177 | * null if it was not found | |
a52fde77 AM |
178 | * @throws TimeRangeException |
179 | * If the timestamp was invalid | |
3b7f5abe AM |
180 | * @throws StateSystemDisposedException |
181 | * If the state system is disposed while a request is ongoing. | |
a52fde77 | 182 | */ |
57a2a5ca | 183 | ITmfStateInterval doSingularQuery(long t, int attributeQuark) |
ed48dc75 | 184 | throws TimeRangeException, StateSystemDisposedException; |
5df842b3 | 185 | |
5d279031 LPD |
186 | /** |
187 | * Generalized 2D iterable query method. Iterates over intervals that match | |
188 | * the conditions on quarks and times with no guaranteed order. | |
189 | * | |
190 | * @param quarkCondition | |
191 | * Condition on the quarks for returned intervals. | |
192 | * @param timeCondition | |
193 | * Condition on the times for returned intervals | |
194 | * @return An un-ordered iterable over the queried intervals | |
195 | * @throws TimeRangeException | |
196 | * if the time bounds are outside the range of the HistoryTree | |
42e8fef7 | 197 | * @since 3.0 |
5d279031 LPD |
198 | */ |
199 | default Iterable<@NonNull ITmfStateInterval> query2D(IntegerRangeCondition quarkCondition, TimeRangeCondition timeCondition) | |
200 | throws TimeRangeException { | |
201 | throw new UnsupportedOperationException("This backend does not support 2D queries"); //$NON-NLS-1$ | |
202 | } | |
a52fde77 | 203 | } |