/*******************************************************************************
- * Copyright (c) 2012, 2015 Ericsson and others.
+ * Copyright (c) 2012, 2016 Ericsson and others.
*
* All rights reserved. This program and the accompanying materials are
* made available under the terms of the Eclipse Public License v1.0 which
*/
public interface ITmfStateSystem {
+ /** Root attribute quark
+ * @since 2.0*/
+ int ROOT_ATTRIBUTE = -1;
+ /** Invalid attribute quark
+ * @since 2.0*/
+ int INVALID_ATTRIBUTE = -2;
+
/**
* Get the ID of this state system.
*
/**
* Basic quark-retrieving method. Pass an attribute in parameter as an array
* of strings, the matching quark will be returned.
- *
+ * <p>
* This version will NOT create any new attributes. If an invalid attribute
* is requested, an exception will be thrown.
+ * <p>
+ * If it is expected that the requested attribute might be absent, it is
+ * recommended to use {@link #optQuarkAbsolute(String...)} instead.
*
* @param attribute
* Attribute given as its full path in the Attribute Tree
int getQuarkAbsolute(String... attribute)
throws AttributeNotFoundException;
+ /**
+ * Quark-retrieving method for an optional attribute that may or may not be
+ * present. Pass an attribute in parameter as an array of strings, if it
+ * exists, the matching quark will be returned.
+ * <p>
+ * This version will NOT create any new attributes. If an attribute that
+ * does not exist is requested, {@link #INVALID_ATTRIBUTE} will be returned.
+ *
+ * @param attribute
+ * Attribute given as its full path in the Attribute Tree
+ * @return The quark of the requested attribute, or
+ * {@link #INVALID_ATTRIBUTE} if it does not exist.
+ * @since 2.0
+ */
+ int optQuarkAbsolute(String... attribute);
+
/**
* "Relative path" quark-getting method. Instead of specifying a full path,
* if you know the path is relative to another attribute for which you
* already have the quark, use this for better performance.
- *
+ * <p>
* This is useful for cases where a lot of modifications or queries will
* originate from the same branch of the attribute tree : the common part of
* the path won't have to be re-hashed for every access.
- *
+ * <p>
* This version will NOT create any new attributes. If an invalid attribute
* is requested, an exception will be thrown.
+ * <p>
+ * If it is expected that the requested sub-attribute might be absent, it is
+ * recommended to use {@link #optQuarkRelative(int, String...)} instead.
*
* @param startingNodeQuark
* The quark of the attribute from which 'subPath' originates.
int getQuarkRelative(int startingNodeQuark, String... subPath)
throws AttributeNotFoundException;
+ /**
+ * "Relative path" quark-getting method for an optional attribute that may
+ * or may not be present. Instead of specifying a full path, if you know the
+ * path is relative to another attribute for which you already have the
+ * quark, use this for better performance.
+ * <p>
+ * This is useful for cases where a lot of modifications or queries will
+ * originate from the same branch of the attribute tree : the common part of
+ * the path won't have to be re-hashed for every access.
+ * <p>
+ * This version will NOT create any new attributes. If a sub-attribute that
+ * does not exist is requested, {@link #INVALID_ATTRIBUTE} will be returned.
+ *
+ * @param startingNodeQuark
+ * The quark of the attribute from which 'subPath' originates.
+ * @param subPath
+ * "Rest" of the path to get to the final attribute
+ * @return The quark of the requested sub-attribute, or
+ * {@link #INVALID_ATTRIBUTE} if it does not exist.
+ * @throws IndexOutOfBoundsException
+ * If the starting node quark is out of range
+ * @since 2.0
+ */
+ int optQuarkRelative(int startingNodeQuark, String... subPath);
+
/**
* Return the sub-attributes of the target attribute, as a List of quarks.
*
* @param quark
* The attribute of which you want to sub-attributes. You can use
- * "-1" here to specify the root node.
+ * {@link #ROOT_ATTRIBUTE} here to specify the root node.
* @param recursive
* True if you want all recursive sub-attributes, false if you
* only want the first level.
* @return A List of integers, matching the quarks of the sub-attributes.
- * @throws AttributeNotFoundException
- * If the quark was not existing or invalid.
+ * @throws IndexOutOfBoundsException
+ * If the quark is out of range
*/
- @NonNull List<Integer> getSubAttributes(int quark, boolean recursive)
- throws AttributeNotFoundException;
+ @NonNull List<@NonNull Integer> getSubAttributes(int quark, boolean recursive);
/**
* Return the sub-attributes of the target attribute, as a List of quarks,
*
* @param quark
* The attribute of which you want to sub-attributes. You can use
- * "-1" here to specify the root node.
+ * {@link #ROOT_ATTRIBUTE} here to specify the root node.
* @param recursive
* True if you want all recursive sub-attributes, false if you
* only want the first level. Note that the returned value will
* @return A List of integers, matching the quarks of the sub-attributes
* that match the regex. An empty list is returned if there is no
* matching attribute.
- * @throws AttributeNotFoundException
- * If the 'quark' was not existing or invalid.
+ * @throws IndexOutOfBoundsException
+ * If the quark is out of range
*/
- List<Integer> getSubAttributes(int quark, boolean recursive, String pattern)
- throws AttributeNotFoundException;
+ @NonNull List<@NonNull Integer> getSubAttributes(int quark, boolean recursive, String pattern);
/**
* Batch quark-retrieving method. This method allows you to specify a path
- * pattern which includes a wildcard "*" somewhere. It will check all the
- * existing attributes in the attribute tree and return those who match the
- * pattern.
- *
+ * pattern which can include wildcard "*" or parent ".." elements. It will
+ * check all the existing attributes in the attribute tree and return those
+ * who match the pattern.
+ * <p>
* For example, passing ("Threads", "*", "Exec_mode") will return the list
* of quarks for attributes "Threads/1000/Exec_mode",
* "Threads/1500/Exec_mode", and so on, depending on what exists at this
* time in the attribute tree.
- *
- * If no wildcard is specified, the behavior is the same as
- * getQuarkAbsolute() (except it will return a List with one entry). This
+ * <p>
+ * If no wildcard or parent element is specified, the behavior is the same
+ * as getQuarkAbsolute() (except it will return a List with one entry, or an
+ * empty list if there is no match instead of throwing an exception). This
* method will never create new attributes.
*
- * Only one wildcard "*" is supported at this time.
+ * @param pattern
+ * The array of strings representing the pattern to look for.
+ * @return A List of unique attribute quarks, representing attributes that
+ * matched the pattern. If no attribute matched, the list will be
+ * empty (but not null). If the pattern is empty,
+ * {@link #ROOT_ATTRIBUTE} is returned in the list.
+ */
+ @NonNull List<@NonNull Integer> getQuarks(String... pattern);
+
+ /**
+ * Relative batch quark-retrieving method. This method allows you to specify
+ * a path pattern which can include wildcard "*" or parent ".." elements. It
+ * will check all the existing attributes in the attribute tree and return
+ * those who match the pattern.
+ * <p>
+ * For example, passing (5, "Threads", "*", "Exec_mode") will return the
+ * list of quarks for attributes "<path of quark 5>/Threads/1000/Exec_mode",
+ * "<path of quark 5>/Threads/1500/Exec_mode", and so on, depending on what
+ * exists at this time in the attribute tree.
+ * <p>
+ * If no wildcard or parent element is specified, the behavior is the same
+ * as getQuarkRelative() (except it will return a List with one entry, or an
+ * empty list if there is no match instead of throwing an exception). This
+ * method will never create new attributes.
*
+ * @param startingNodeQuark
+ * The quark of the attribute from which 'pattern' originates.
* @param pattern
- * The array of strings representing the pattern to look for. It
- * should ideally contain one entry that is only a "*".
- * @return A List of attribute quarks, representing attributes that matched
- * the pattern. If no attribute matched, the list will be empty (but
- * not null).
+ * The array of strings representing the pattern to look for.
+ * @return A List of unique attribute quarks, representing attributes that
+ * matched the pattern. If no attribute matched, the list will be
+ * empty (but not null). If the pattern is empty, the starting node
+ * quark is returned in the list.
+ * @throws IndexOutOfBoundsException
+ * If the starting node quark is out of range
+ * @since 2.0
*/
- List<Integer> getQuarks(String... pattern);
+ @NonNull List<@NonNull Integer> getQuarks(int startingNodeQuark, String... pattern);
/**
* Return the name assigned to this quark. This returns only the "basename",
*
* @param attributeQuark
* The quark of the attribute
- * @return Quark of the parent attribute or <code>-1</code> if root quark or
- * no parent.
+ * @return Quark of the parent attribute or {@link #ROOT_ATTRIBUTE} if root
+ * quark or no parent.
* @throws IndexOutOfBoundsException
* If the attribute quark is out of range
*/
* @param attributeQuark
* For which attribute we want the current state
* @return The State value that's "current" for this attribute
- * @throws AttributeNotFoundException
- * If the requested attribute is invalid
+ * @throws IndexOutOfBoundsException
+ * If the attribute quark is out of range
*/
- ITmfStateValue queryOngoingState(int attributeQuark)
- throws AttributeNotFoundException;
+ @NonNull ITmfStateValue queryOngoingState(int attributeQuark);
/**
* Get the start time of the current ongoing state, for the specified
* attribute.
*
- * @param attribute
+ * @param attributeQuark
* Quark of the attribute
* @return The current start time of the ongoing state
- * @throws AttributeNotFoundException
- * If the attribute is invalid
+ * @throws IndexOutOfBoundsException
+ * If the attribute quark is out of range
*/
- long getOngoingStartTime(int attribute)
- throws AttributeNotFoundException;
+ long getOngoingStartTime(int attributeQuark);
/**
* Load the complete state information at time 't' into the returned List.
* @throws StateSystemDisposedException
* If the query is sent after the state system has been disposed
*/
- @NonNull List<ITmfStateInterval> queryFullState(long t)
+ @NonNull List<@NonNull ITmfStateInterval> queryFullState(long t)
throws StateSystemDisposedException;
/**
* @return The StateInterval representing the state
* @throws TimeRangeException
* If 't' is invalid
- * @throws AttributeNotFoundException
- * If the requested quark does not exist in the model
+ * @throws IndexOutOfBoundsException
+ * If the attribute quark is out of range
* @throws StateSystemDisposedException
* If the query is sent after the state system has been disposed
*/
@NonNull ITmfStateInterval querySingleState(long t, int attributeQuark)
- throws AttributeNotFoundException, StateSystemDisposedException;
+ throws StateSystemDisposedException;
}
\ No newline at end of file
projects / deliverable / tracecompass.git / blobdiff