/*******************************************************************************
- * Copyright (c) 2012 Ericsson
+ * Copyright (c) 2012, 2013 Ericsson
*
* All rights reserved. This program and the accompanying materials are
* made available under the terms of the Eclipse Public License v1.0 which
import org.eclipse.core.runtime.IProgressMonitor;
import org.eclipse.linuxtools.tmf.core.exceptions.AttributeNotFoundException;
+import org.eclipse.linuxtools.tmf.core.exceptions.StateSystemDisposedException;
import org.eclipse.linuxtools.tmf.core.exceptions.StateValueTypeException;
import org.eclipse.linuxtools.tmf.core.exceptions.TimeRangeException;
import org.eclipse.linuxtools.tmf.core.interval.ITmfStateInterval;
*
* @return The history's registered start time
*/
- public long getStartTime();
+ long getStartTime();
/**
* Return the current end time of the history.
*
* @return The current end time of this state history
*/
- public long getCurrentEndTime();
+ long getCurrentEndTime();
/**
- * Return the current total amount of attributes in the system. This is also
- * equal to the quark that will be assigned to the next attribute that's
- * created.
+ * While it's possible to query a state history that is being built,
+ * sometimes we might want to wait until the construction is finished before
+ * we start doing queries.
*
- * @return The current number of attributes in the system
+ * This method blocks the calling thread until the history back-end is done
+ * building. If it's already built (ie, opening a pre-existing file) this
+ * should return immediately.
+ *
+ * @return If the build was successful. If false is returned, this either
+ * means there was a problem during the build, or it got cancelled
+ * before it could finished. In that case, no queries should be run
+ * afterwards.
*/
- public int getNbAttributes();
+ boolean waitUntilBuilt();
/**
- * Check if a given quark is the last attribute that was added to the
- * system.
- *
- * This is a common case, and it's a bit clearer than
- * " x == getNbAttributes - 1"
+ * Notify the state system that the trace is being closed, so it should
+ * clean up, close its files, etc.
+ */
+ void dispose();
+
+ /**
+ * Return the current total amount of attributes in the system. This is also
+ * equal to the quark that will be assigned to the next attribute that's
+ * created.
*
- * @param quark
- * The quark to check for
- * @return True if this is the last quark that was added to the system,
- * false if not
- * @since 2.0
+ * @return The current number of attributes in the system
*/
- public boolean isLastAttribute(int quark);
+ int getNbAttributes();
/**
* @name Read-only quark-getting methods
* This exception is thrown if the requested attribute simply
* did not exist in the system.
*/
- public int getQuarkAbsolute(String... attribute)
+ int getQuarkAbsolute(String... attribute)
throws AttributeNotFoundException;
/**
* @throws AttributeNotFoundException
* If the quark is invalid
*/
- public int getQuarkRelative(int startingNodeQuark, String... subPath)
+ int getQuarkRelative(int startingNodeQuark, String... subPath)
throws AttributeNotFoundException;
/**
* @throws AttributeNotFoundException
* If the quark was not existing or invalid.
*/
- public List<Integer> getSubAttributes(int quark, boolean recursive)
+ List<Integer> getSubAttributes(int quark, boolean recursive)
throws AttributeNotFoundException;
/**
* the pattern. If no attribute matched, the list will be empty (but
* not null).
*/
- public List<Integer> getQuarks(String... pattern);
+ List<Integer> getQuarks(String... pattern);
/**
* Return the name assigned to this quark. This returns only the "basename",
* The quark for which we want the name
* @return The name of the quark
*/
- public String getAttributeName(int attributeQuark);
+ String getAttributeName(int attributeQuark);
/**
* This returns the slash-separated path of an attribute by providing its
* The quark of the attribute we want
* @return One single string separated with '/', like a filesystem path
*/
- public String getFullAttributePath(int attributeQuark);
+ String getFullAttributePath(int attributeQuark);
/**
* @name Query methods
* @throws AttributeNotFoundException
* If the requested attribute is invalid
*/
- public ITmfStateValue queryOngoingState(int attributeQuark)
+ ITmfStateValue queryOngoingState(int attributeQuark)
+ throws AttributeNotFoundException;
+
+ /**
+ * Get the start time of the current ongoing state, for the specified
+ * attribute.
+ *
+ * @param attribute
+ * Quark of the attribute
+ * @return The current start time of the ongoing state
+ * @throws AttributeNotFoundException
+ * If the attribute is invalid
+ */
+ long getOngoingStartTime(int attribute)
throws AttributeNotFoundException;
/**
* @throws TimeRangeException
* If the 't' parameter is outside of the range of the state
* history.
+ * @throws StateSystemDisposedException
+ * If the query is sent after the state system has been disposed
*/
- public List<ITmfStateInterval> queryFullState(long t)
- throws TimeRangeException;
+ List<ITmfStateInterval> queryFullState(long t)
+ throws TimeRangeException, StateSystemDisposedException;
/**
* Singular query method. This one does not update the whole stateInfo
* If 't' is invalid
* @throws AttributeNotFoundException
* If the requested quark does not exist in the model
+ * @throws StateSystemDisposedException
+ * If the query is sent after the state system has been disposed
*/
- public ITmfStateInterval querySingleState(long t, int attributeQuark)
- throws AttributeNotFoundException, TimeRangeException;
+ ITmfStateInterval querySingleState(long t, int attributeQuark)
+ throws AttributeNotFoundException, TimeRangeException,
+ StateSystemDisposedException;
/**
* Convenience method to query attribute stacks (created with
* If the attribute was simply not found
* @throws TimeRangeException
* If the given timestamp is invalid
+ * @throws StateSystemDisposedException
+ * If the query is sent after the state system has been disposed
* @since 2.0
*/
- public ITmfStateInterval querySingleStackTop(long t, int stackAttributeQuark)
+ ITmfStateInterval querySingleStackTop(long t, int stackAttributeQuark)
throws StateValueTypeException, AttributeNotFoundException,
- TimeRangeException;
+ TimeRangeException, StateSystemDisposedException;
/**
* Return a list of state intervals, containing the "history" of a given
* If t1 is invalid, or if t2 <= t1
* @throws AttributeNotFoundException
* If the requested quark does not exist in the model.
+ * @throws StateSystemDisposedException
+ * If the query is sent after the state system has been disposed
*/
- public List<ITmfStateInterval> queryHistoryRange(int attributeQuark,
+ List<ITmfStateInterval> queryHistoryRange(int attributeQuark,
long t1, long t2) throws TimeRangeException,
- AttributeNotFoundException;
+ AttributeNotFoundException, StateSystemDisposedException;
/**
* Return the state history of a given attribute, but with at most one
* greater than zero.
* @throws AttributeNotFoundException
* If the attribute doesn't exist
+ * @throws StateSystemDisposedException
+ * If the query is sent after the state system has been disposed
* @since 2.0
*/
- public List<ITmfStateInterval> queryHistoryRange(int attributeQuark,
+ List<ITmfStateInterval> queryHistoryRange(int attributeQuark,
long t1, long t2, long resolution, IProgressMonitor monitor)
- throws TimeRangeException, AttributeNotFoundException;
+ throws TimeRangeException, AttributeNotFoundException,
+ StateSystemDisposedException;
}
projects / deliverable / tracecompass.git / blobdiff