Commit | Line | Data |
---|---|---|
a52fde77 AM |
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> | |
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 | ||
2ab9afbc | 13 | package org.eclipse.linuxtools.internal.tmf.core.statesystem; |
a52fde77 AM |
14 | |
15 | import java.io.File; | |
16 | import java.io.FileInputStream; | |
17 | import java.io.PrintWriter; | |
18 | import java.util.List; | |
19 | ||
6d08acca | 20 | import org.eclipse.linuxtools.tmf.core.exceptions.AttributeNotFoundException; |
3b7f5abe | 21 | import org.eclipse.linuxtools.tmf.core.exceptions.StateSystemDisposedException; |
6d08acca | 22 | import org.eclipse.linuxtools.tmf.core.exceptions.TimeRangeException; |
a52fde77 | 23 | import org.eclipse.linuxtools.tmf.core.interval.ITmfStateInterval; |
a52fde77 AM |
24 | import org.eclipse.linuxtools.tmf.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. | |
5df842b3 | 31 | * |
a52fde77 AM |
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. | |
5df842b3 | 36 | * |
a52fde77 | 37 | * @author alexmont |
5df842b3 | 38 | * |
a52fde77 AM |
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. | |
5df842b3 | 45 | * |
a52fde77 AM |
46 | * @return The start time |
47 | */ | |
48 | public long getStartTime(); | |
49 | ||
50 | /** | |
51 | * Get the current end time of the state history. It will change as the | |
52 | * history is being built. | |
5df842b3 | 53 | * |
a52fde77 AM |
54 | * @return The end time |
55 | */ | |
56 | public long getEndTime(); | |
57 | ||
58 | /** | |
59 | * Main method to insert state intervals into the history. | |
5df842b3 | 60 | * |
a52fde77 AM |
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 | public 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.) | |
5df842b3 | 79 | * |
a52fde77 AM |
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 | public 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). | |
5df842b3 | 92 | * |
a52fde77 AM |
93 | * This method defines where to read for the attribute tree when opening an |
94 | * already-existing history. Refer to the file format documentation. | |
5df842b3 | 95 | * |
a52fde77 AM |
96 | * @return A FileInputStream object pointing to the correct file/location in |
97 | * the file where to read the attribute tree information. | |
98 | */ | |
99 | public FileInputStream supplyAttributeTreeReader(); | |
100 | ||
101 | // FIXME change to FOS too? | |
5df842b3 AM |
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 | */ | |
a52fde77 AM |
108 | public File supplyAttributeTreeWriterFile(); |
109 | ||
5df842b3 AM |
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 | */ | |
a52fde77 AM |
116 | public long supplyAttributeTreeWriterFilePosition(); |
117 | ||
36bf82a2 AM |
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. | |
5df842b3 | 122 | * |
36bf82a2 AM |
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 | public void removeFiles(); | |
128 | ||
1a4205d9 AM |
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 | public void dispose(); | |
134 | ||
3b7f5abe AM |
135 | // ------------------------------------------------------------------------ |
136 | // Query methods | |
137 | // ------------------------------------------------------------------------ | |
a52fde77 AM |
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! | |
5df842b3 | 144 | * |
a52fde77 AM |
145 | * @param currentStateInfo |
146 | * List of StateValues (index == quark) to fill up | |
147 | * @param t | |
148 | * Target timestamp of the query | |
5df842b3 AM |
149 | * @throws TimeRangeException |
150 | * If the timestamp is outside of the history/trace | |
3b7f5abe AM |
151 | * @throws StateSystemDisposedException |
152 | * If the state system is disposed while a request is ongoing. | |
a52fde77 AM |
153 | */ |
154 | public void doQuery(List<ITmfStateInterval> currentStateInfo, long t) | |
3b7f5abe | 155 | throws TimeRangeException, StateSystemDisposedException; |
a52fde77 AM |
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(). | |
5df842b3 | 162 | * |
a52fde77 AM |
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 | |
3b7f5abe AM |
172 | * @throws StateSystemDisposedException |
173 | * If the state system is disposed while a request is ongoing. | |
a52fde77 AM |
174 | */ |
175 | public ITmfStateInterval doSingularQuery(long t, int attributeQuark) | |
3b7f5abe AM |
176 | throws TimeRangeException, AttributeNotFoundException, |
177 | StateSystemDisposedException; | |
5df842b3 | 178 | |
b255ae4b AM |
179 | /** |
180 | * Simple check to make sure the requested timestamps are within the borders | |
5df842b3 AM |
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 | |
b255ae4b | 183 | * example). |
5df842b3 | 184 | * |
b255ae4b AM |
185 | * @param t |
186 | * The queried timestamp | |
187 | * @return True if the timestamp is within range, false if not. | |
188 | */ | |
189 | public boolean checkValidTime(long t); | |
a52fde77 AM |
190 | |
191 | /** | |
192 | * Debug method to print the contents of the history backend. | |
5df842b3 | 193 | * |
a52fde77 AM |
194 | * @param writer |
195 | * The PrintWriter where to write the output | |
196 | */ | |
197 | public void debugPrint(PrintWriter writer); | |
198 | } |