ss: Improve getQuarks() functionality
[deliverable/tracecompass.git] / statesystem / org.eclipse.tracecompass.statesystem.core / src / org / eclipse / tracecompass / statesystem / core / ITmfStateSystem.java
CommitLineData
d26f90fd 1/*******************************************************************************
c44f0a0c 2 * Copyright (c) 2012, 2016 Ericsson and others.
d26f90fd
AM
3 *
4 * All rights reserved. This program and the accompanying materials are
5 * made available under the terms of the Eclipse Public License v1.0 which
6 * accompanies this distribution, and is available at
7 * http://www.eclipse.org/legal/epl-v10.html
8 *
9 * Contributors:
10 * Alexandre Montplaisir - Initial API
11 ******************************************************************************/
12
e894a508 13package org.eclipse.tracecompass.statesystem.core;
d26f90fd
AM
14
15import java.util.List;
16
e62a23a9 17import org.eclipse.jdt.annotation.NonNull;
e894a508
AM
18import org.eclipse.tracecompass.statesystem.core.exceptions.AttributeNotFoundException;
19import org.eclipse.tracecompass.statesystem.core.exceptions.StateSystemDisposedException;
e894a508
AM
20import org.eclipse.tracecompass.statesystem.core.exceptions.TimeRangeException;
21import org.eclipse.tracecompass.statesystem.core.interval.ITmfStateInterval;
22import org.eclipse.tracecompass.statesystem.core.statevalue.ITmfStateValue;
d26f90fd 23
1dd75589 24
d26f90fd
AM
25/**
26 * This is the read-only interface to the generic state system. It contains all
27 * the read-only quark-getting methods, as well as the history-querying ones.
5df842b3 28 *
2cb26548 29 * @author Alexandre Montplaisir
1dd75589
AM
30 * @noimplement Only the internal StateSystem class should implement this
31 * interface.
d26f90fd 32 */
f1f86dfb 33public interface ITmfStateSystem {
d26f90fd 34
c44f0a0c
PT
35 /** Root attribute quark
36 * @since 2.0*/
37 int ROOT_ATTRIBUTE = -1;
38 /** Invalid attribute quark
39 * @since 2.0*/
40 int INVALID_ATTRIBUTE = -2;
41
84a9548a
AM
42 /**
43 * Get the ID of this state system.
44 *
45 * @return The state system's ID
84a9548a
AM
46 */
47 String getSSID();
48
d26f90fd
AM
49 /**
50 * Return the start time of this history. It usually matches the start time
51 * of the original trace.
5df842b3 52 *
d26f90fd
AM
53 * @return The history's registered start time
54 */
57a2a5ca 55 long getStartTime();
d26f90fd
AM
56
57 /**
58 * Return the current end time of the history.
5df842b3
AM
59 *
60 * @return The current end time of this state history
d26f90fd 61 */
57a2a5ca 62 long getCurrentEndTime();
d26f90fd 63
2002c638
AM
64 /**
65 * Check if the construction of this state system was cancelled or not. If
66 * false is returned, it can mean that the building was finished
67 * successfully, or that it is still ongoing. You can check independently
68 * with {@link #waitUntilBuilt()} if it is finished or not.
69 *
70 * @return If the construction was cancelled or not. In true is returned, no
71 * queries should be run afterwards.
2002c638
AM
72 */
73 boolean isCancelled();
74
16576a7e
AM
75 /**
76 * While it's possible to query a state history that is being built,
77 * sometimes we might want to wait until the construction is finished before
78 * we start doing queries.
79 *
80 * This method blocks the calling thread until the history back-end is done
81 * building. If it's already built (ie, opening a pre-existing file) this
e45de797 82 * should return immediately.
1a4205d9 83 *
2002c638
AM
84 * You should always check with {@link #isCancelled()} if it is safe to
85 * query this state system before doing queries.
1a4205d9 86 */
2002c638 87 void waitUntilBuilt();
1a4205d9 88
9287b6a2
AM
89 /**
90 * Wait until the state system construction is finished. Similar to
91 * {@link #waitUntilBuilt()}, but we also specify a timeout. If the timeout
92 * elapses before the construction is finished, the method will return.
93 *
94 * The return value determines if the return was due to the construction
95 * finishing (true), or the timeout elapsing (false).
96 *
97 * This can be useful, for example, for a component doing queries
98 * periodically to the system while it is being built.
99 *
100 * @param timeout
101 * Timeout value in milliseconds
102 * @return True if the return was due to the construction finishing, false
103 * if it was because the timeout elapsed. Same logic as
104 * {@link java.util.concurrent.CountDownLatch#await(long, java.util.concurrent.TimeUnit)}
9287b6a2
AM
105 */
106 boolean waitUntilBuilt(long timeout);
107
1a4205d9
AM
108 /**
109 * Notify the state system that the trace is being closed, so it should
110 * clean up, close its files, etc.
16576a7e 111 */
57a2a5ca 112 void dispose();
16576a7e 113
34638411
AM
114 // ------------------------------------------------------------------------
115 // Read-only quark-getting methods
116 // ------------------------------------------------------------------------
117
4623f57f 118 /**
f5295294
AM
119 * Return the current total amount of attributes in the system. This is also
120 * equal to the quark that will be assigned to the next attribute that's
121 * created.
5df842b3
AM
122 *
123 * @return The current number of attributes in the system
4623f57f 124 */
57a2a5ca 125 int getNbAttributes();
4623f57f 126
d26f90fd
AM
127 /**
128 * Basic quark-retrieving method. Pass an attribute in parameter as an array
129 * of strings, the matching quark will be returned.
c44f0a0c 130 * <p>
d26f90fd
AM
131 * This version will NOT create any new attributes. If an invalid attribute
132 * is requested, an exception will be thrown.
c44f0a0c
PT
133 * <p>
134 * If it is expected that the requested attribute might be absent, it is
135 * recommended to use {@link #optQuarkAbsolute(String...)} instead.
5df842b3 136 *
d26f90fd
AM
137 * @param attribute
138 * Attribute given as its full path in the Attribute Tree
139 * @return The quark of the requested attribute, if it existed.
140 * @throws AttributeNotFoundException
141 * This exception is thrown if the requested attribute simply
142 * did not exist in the system.
143 */
57a2a5ca 144 int getQuarkAbsolute(String... attribute)
d26f90fd
AM
145 throws AttributeNotFoundException;
146
c44f0a0c
PT
147 /**
148 * Quark-retrieving method for an optional attribute that may or may not be
149 * present. Pass an attribute in parameter as an array of strings, if it
150 * exists, the matching quark will be returned.
151 * <p>
152 * This version will NOT create any new attributes. If an attribute that
153 * does not exist is requested, {@link #INVALID_ATTRIBUTE} will be returned.
154 *
155 * @param attribute
156 * Attribute given as its full path in the Attribute Tree
157 * @return The quark of the requested attribute, or
158 * {@link #INVALID_ATTRIBUTE} if it does not exist.
159 * @since 2.0
160 */
161 int optQuarkAbsolute(String... attribute);
162
d26f90fd
AM
163 /**
164 * "Relative path" quark-getting method. Instead of specifying a full path,
165 * if you know the path is relative to another attribute for which you
166 * already have the quark, use this for better performance.
c44f0a0c 167 * <p>
d26f90fd
AM
168 * This is useful for cases where a lot of modifications or queries will
169 * originate from the same branch of the attribute tree : the common part of
170 * the path won't have to be re-hashed for every access.
c44f0a0c 171 * <p>
d26f90fd
AM
172 * This version will NOT create any new attributes. If an invalid attribute
173 * is requested, an exception will be thrown.
c44f0a0c
PT
174 * <p>
175 * If it is expected that the requested sub-attribute might be absent, it is
176 * recommended to use {@link #optQuarkRelative(int, String...)} instead.
5df842b3 177 *
d26f90fd
AM
178 * @param startingNodeQuark
179 * The quark of the attribute from which 'subPath' originates.
180 * @param subPath
181 * "Rest" of the path to get to the final attribute
182 * @return The matching quark, if it existed
04927a83
AM
183 * @throws IndexOutOfBoundsException
184 * If the starting node quark is out of range
d26f90fd 185 * @throws AttributeNotFoundException
04927a83 186 * If the sub-attribute does not exist
d26f90fd 187 */
57a2a5ca 188 int getQuarkRelative(int startingNodeQuark, String... subPath)
d26f90fd
AM
189 throws AttributeNotFoundException;
190
c44f0a0c
PT
191 /**
192 * "Relative path" quark-getting method for an optional attribute that may
193 * or may not be present. Instead of specifying a full path, if you know the
194 * path is relative to another attribute for which you already have the
195 * quark, use this for better performance.
196 * <p>
197 * This is useful for cases where a lot of modifications or queries will
198 * originate from the same branch of the attribute tree : the common part of
199 * the path won't have to be re-hashed for every access.
200 * <p>
201 * This version will NOT create any new attributes. If a sub-attribute that
202 * does not exist is requested, {@link #INVALID_ATTRIBUTE} will be returned.
203 *
204 * @param startingNodeQuark
205 * The quark of the attribute from which 'subPath' originates.
206 * @param subPath
207 * "Rest" of the path to get to the final attribute
208 * @return The quark of the requested sub-attribute, or
209 * {@link #INVALID_ATTRIBUTE} if it does not exist.
210 * @throws IndexOutOfBoundsException
211 * If the starting node quark is out of range
212 * @since 2.0
213 */
214 int optQuarkRelative(int startingNodeQuark, String... subPath);
215
d26f90fd
AM
216 /**
217 * Return the sub-attributes of the target attribute, as a List of quarks.
5df842b3 218 *
d26f90fd
AM
219 * @param quark
220 * The attribute of which you want to sub-attributes. You can use
c44f0a0c 221 * {@link #ROOT_ATTRIBUTE} here to specify the root node.
d26f90fd
AM
222 * @param recursive
223 * True if you want all recursive sub-attributes, false if you
224 * only want the first level.
225 * @return A List of integers, matching the quarks of the sub-attributes.
226 * @throws AttributeNotFoundException
227 * If the quark was not existing or invalid.
228 */
df2597e0 229 @NonNull List<@NonNull Integer> getSubAttributes(int quark, boolean recursive)
d26f90fd
AM
230 throws AttributeNotFoundException;
231
5206c858
AM
232 /**
233 * Return the sub-attributes of the target attribute, as a List of quarks,
234 * similarly to {@link #getSubAttributes(int, boolean)}, but with an added
235 * regex pattern to filter on the return attributes.
236 *
237 * @param quark
238 * The attribute of which you want to sub-attributes. You can use
c44f0a0c 239 * {@link #ROOT_ATTRIBUTE} here to specify the root node.
5206c858
AM
240 * @param recursive
241 * True if you want all recursive sub-attributes, false if you
242 * only want the first level. Note that the returned value will
243 * be flattened.
244 * @param pattern
245 * The regular expression to match the attribute base name.
246 * @return A List of integers, matching the quarks of the sub-attributes
247 * that match the regex. An empty list is returned if there is no
248 * matching attribute.
249 * @throws AttributeNotFoundException
250 * If the 'quark' was not existing or invalid.
5206c858 251 */
df2597e0 252 @NonNull List<@NonNull Integer> getSubAttributes(int quark, boolean recursive, String pattern)
5206c858
AM
253 throws AttributeNotFoundException;
254
d26f90fd
AM
255 /**
256 * Batch quark-retrieving method. This method allows you to specify a path
aa315d8b
PT
257 * pattern which can include wildcard "*" or parent ".." elements. It will
258 * check all the existing attributes in the attribute tree and return those
259 * who match the pattern.
260 * <p>
d26f90fd
AM
261 * For example, passing ("Threads", "*", "Exec_mode") will return the list
262 * of quarks for attributes "Threads/1000/Exec_mode",
263 * "Threads/1500/Exec_mode", and so on, depending on what exists at this
264 * time in the attribute tree.
aa315d8b
PT
265 * <p>
266 * If no wildcard or parent element is specified, the behavior is the same
267 * as getQuarkAbsolute() (except it will return a List with one entry, or an
268 * empty list if there is no match instead of throwing an exception). This
d26f90fd 269 * method will never create new attributes.
5df842b3 270 *
d26f90fd 271 * @param pattern
aa315d8b
PT
272 * The array of strings representing the pattern to look for.
273 * @return A List of unique attribute quarks, representing attributes that
274 * matched the pattern. If no attribute matched, the list will be
275 * empty (but not null). If the pattern is empty,
276 * {@link #ROOT_ATTRIBUTE} is returned in the list.
d26f90fd 277 */
df2597e0 278 @NonNull List<@NonNull Integer> getQuarks(String... pattern);
d26f90fd 279
aa315d8b
PT
280 /**
281 * Relative batch quark-retrieving method. This method allows you to specify
282 * a path pattern which can include wildcard "*" or parent ".." elements. It
283 * will check all the existing attributes in the attribute tree and return
284 * those who match the pattern.
285 * <p>
286 * For example, passing (5, "Threads", "*", "Exec_mode") will return the
287 * list of quarks for attributes "<path of quark 5>/Threads/1000/Exec_mode",
288 * "<path of quark 5>/Threads/1500/Exec_mode", and so on, depending on what
289 * exists at this time in the attribute tree.
290 * <p>
291 * If no wildcard or parent element is specified, the behavior is the same
292 * as getQuarkRelative() (except it will return a List with one entry, or an
293 * empty list if there is no match instead of throwing an exception). This
294 * method will never create new attributes.
295 *
296 * @param startingNodeQuark
297 * The quark of the attribute from which 'pattern' originates.
298 * @param pattern
299 * The array of strings representing the pattern to look for.
300 * @return A List of unique attribute quarks, representing attributes that
301 * matched the pattern. If no attribute matched, the list will be
302 * empty (but not null). If the pattern is empty, the starting node
303 * quark is returned in the list.
304 * @throws IndexOutOfBoundsException
305 * If the starting node quark is out of range
306 * @since 2.0
307 */
308 @NonNull List<@NonNull Integer> getQuarks(int startingNodeQuark, String... pattern);
309
d26f90fd
AM
310 /**
311 * Return the name assigned to this quark. This returns only the "basename",
312 * not the complete path to this attribute.
5df842b3 313 *
d26f90fd
AM
314 * @param attributeQuark
315 * The quark for which we want the name
316 * @return The name of the quark
04927a83
AM
317 * @throws IndexOutOfBoundsException
318 * If the attribute quark is out of range
d26f90fd 319 */
04927a83 320 @NonNull String getAttributeName(int attributeQuark);
d26f90fd
AM
321
322 /**
323 * This returns the slash-separated path of an attribute by providing its
324 * quark
5df842b3 325 *
d26f90fd
AM
326 * @param attributeQuark
327 * The quark of the attribute we want
328 * @return One single string separated with '/', like a filesystem path
04927a83
AM
329 * @throws IndexOutOfBoundsException
330 * If the attribute quark is out of range
d26f90fd 331 */
04927a83 332 @NonNull String getFullAttributePath(int attributeQuark);
d26f90fd 333
34638411
AM
334 /**
335 * Return the full attribute path, as an array of strings representing each
336 * element.
337 *
338 * @param attributeQuark
339 * The quark of the attribute we want.
340 * @return The array of path elements
341 * @throws IndexOutOfBoundsException
342 * If the attribute quark is out of range
343 * @since 1.0
344 */
4c4e2816 345 String @NonNull [] getFullAttributePathArray(int attributeQuark);
34638411 346
0fdd2c45
FG
347 /**
348 * Returns the parent quark of the attribute.
349 *
350 * @param attributeQuark
351 * The quark of the attribute
c44f0a0c
PT
352 * @return Quark of the parent attribute or {@link #ROOT_ATTRIBUTE} if root
353 * quark or no parent.
04927a83
AM
354 * @throws IndexOutOfBoundsException
355 * If the attribute quark is out of range
0fdd2c45
FG
356 */
357 int getParentAttributeQuark(int attributeQuark);
358
34638411
AM
359 // ------------------------------------------------------------------------
360 // Query methods
361 // ------------------------------------------------------------------------
d26f90fd
AM
362
363 /**
364 * Returns the current state value we have (in the Transient State) for the
365 * given attribute.
5df842b3 366 *
d26f90fd
AM
367 * This is useful even for a StateHistorySystem, as we are guaranteed it
368 * will only do a memory access and not go look on disk (and we don't even
369 * have to provide a timestamp!)
5df842b3 370 *
d26f90fd
AM
371 * @param attributeQuark
372 * For which attribute we want the current state
373 * @return The State value that's "current" for this attribute
374 * @throws AttributeNotFoundException
375 * If the requested attribute is invalid
376 */
6d0db5b1 377 @NonNull ITmfStateValue queryOngoingState(int attributeQuark)
d26f90fd
AM
378 throws AttributeNotFoundException;
379
602c0697
AM
380 /**
381 * Get the start time of the current ongoing state, for the specified
382 * attribute.
383 *
384 * @param attribute
385 * Quark of the attribute
386 * @return The current start time of the ongoing state
387 * @throws AttributeNotFoundException
388 * If the attribute is invalid
389 */
57a2a5ca 390 long getOngoingStartTime(int attribute)
602c0697
AM
391 throws AttributeNotFoundException;
392
d26f90fd
AM
393 /**
394 * Load the complete state information at time 't' into the returned List.
395 * You can then get the intervals for single attributes by using
396 * List.get(n), where 'n' is the quark of the attribute.
5df842b3 397 *
d26f90fd
AM
398 * On average if you need around 10 or more queries for the same timestamps,
399 * use this method. If you need less than 10 (for example, running many
400 * queries for the same attributes but at different timestamps), you might
401 * be better using the querySingleState() methods instead.
5df842b3 402 *
d26f90fd
AM
403 * @param t
404 * We will recreate the state information to what it was at time
405 * t.
5df842b3 406 * @return The List of intervals, where the offset = the quark
d26f90fd
AM
407 * @throws TimeRangeException
408 * If the 't' parameter is outside of the range of the state
409 * history.
96345c5a
AM
410 * @throws StateSystemDisposedException
411 * If the query is sent after the state system has been disposed
d26f90fd 412 */
df2597e0 413 @NonNull List<@NonNull ITmfStateInterval> queryFullState(long t)
6dd46830 414 throws StateSystemDisposedException;
d26f90fd
AM
415
416 /**
417 * Singular query method. This one does not update the whole stateInfo
2fc8ca37 418 * vector, like queryFullState() does. It only searches for one specific
d26f90fd 419 * entry in the state history.
5df842b3 420 *
d26f90fd
AM
421 * It should be used when you only want very few entries, instead of the
422 * whole state (or many entries, but all at different timestamps). If you do
423 * request many entries all at the same time, you should use the
2fc8ca37 424 * conventional queryFullState() + List.get() method.
5df842b3 425 *
d26f90fd
AM
426 * @param t
427 * The timestamp at which we want the state
428 * @param attributeQuark
429 * Which attribute we want to get the state of
430 * @return The StateInterval representing the state
431 * @throws TimeRangeException
432 * If 't' is invalid
433 * @throws AttributeNotFoundException
434 * If the requested quark does not exist in the model
96345c5a
AM
435 * @throws StateSystemDisposedException
436 * If the query is sent after the state system has been disposed
d26f90fd 437 */
e62a23a9 438 @NonNull ITmfStateInterval querySingleState(long t, int attributeQuark)
6dd46830 439 throws AttributeNotFoundException, StateSystemDisposedException;
1dd75589 440}
This page took 0.114204 seconds and 5 git commands to generate.