From 5df842b3f70670aeb95e2a560caddc5055dd6c8a Mon Sep 17 00:00:00 2001 From: Alexandre Montplaisir Date: Wed, 6 Jun 2012 18:26:32 -0400 Subject: [PATCH] tmf: Update the Javadoc for everything GSS-related Signed-off-by: Alexandre Montplaisir --- .../tmf/core/statesystem/HistoryBuilder.java | 12 +++- .../statesystem/IStateHistoryBackend.java | 52 +++++++++++------ .../core/statesystem/StateHistorySystem.java | 17 +++--- .../tmf/core/statesystem/StateSystem.java | 15 ++--- .../historytree/HistoryTreeBackend.java | 28 ++++----- .../tmf/core/interval/TmfStateInterval.java | 16 +++-- .../core/statesystem/IStateChangeInput.java | 26 +++++---- .../core/statesystem/IStateSystemQuerier.java | 58 ++++++++++--------- .../core/statesystem/StateSystemManager.java | 2 + .../tmf/core/statevalue/ITmfStateValue.java | 21 ++++--- .../tmf/core/statevalue/TmfStateValue.java | 26 +++++---- 11 files changed, 158 insertions(+), 115 deletions(-) diff --git a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/statesystem/HistoryBuilder.java b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/statesystem/HistoryBuilder.java index 51a4564db3..b819e3cb48 100644 --- a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/statesystem/HistoryBuilder.java +++ b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/statesystem/HistoryBuilder.java @@ -55,8 +55,13 @@ public class HistoryBuilder extends TmfComponent { * @param stateChangeInput * The input plugin to use. This is required. * @param backend - * The backend storage to use. Use "null" here if you want a - * state system with no history. + * The backend storage to use. + * @param buildManually + * Should we build this history in-band or not. True means we + * will start the building ourselves and block the caller until + * construction is done. False (out-of-band) means we will + * start listening for the signal and return immediately. Another + * signal will be sent when finished. * @throws IOException * Is thrown if anything went wrong (usually with the storage * backend) @@ -146,6 +151,9 @@ public class HistoryBuilder extends TmfComponent { * construction. * * @param signal + * The "experiment range updated" signal. Listening to this + * signal will coalesce this request with the one from the + * indexer and histogram. */ @SuppressWarnings("unchecked") @TmfSignalHandler diff --git a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/statesystem/IStateHistoryBackend.java b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/statesystem/IStateHistoryBackend.java index f795a36d23..60de334a50 100644 --- a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/statesystem/IStateHistoryBackend.java +++ b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/statesystem/IStateHistoryBackend.java @@ -2,12 +2,12 @@ * Copyright (c) 2012 Ericsson * Copyright (c) 2010, 2011 École Polytechnique de Montréal * Copyright (c) 2010, 2011 Alexandre Montplaisir - * + * * All rights reserved. This program and the accompanying materials are * made available under the terms of the Eclipse Public License v1.0 which * accompanies this distribution, and is available at * http://www.eclipse.org/legal/epl-v10.html - * + * *******************************************************************************/ package org.eclipse.linuxtools.internal.tmf.core.statesystem; @@ -27,21 +27,21 @@ import org.eclipse.linuxtools.tmf.core.statevalue.ITmfStateValue; * allows 'seeking' back in time to reload a Current State at a previous time. * "How to go back in time" is defined by the implementation of the * HistoryBackend. - * + * * A StateHistorySystem contains one and only one HistoryBackend. If you want to * use a paradigm with more than one provider (eg. more or less precision * depending on what's asked by the user), implement one wrapper HistoryBackend * which can then contain your 2-3 other backends underneath. - * + * * @author alexmont - * + * */ public interface IStateHistoryBackend { /** * Get the start time of this state history. This is usually the same as the * start time of the originating trace. - * + * * @return The start time */ public long getStartTime(); @@ -49,14 +49,14 @@ public interface IStateHistoryBackend { /** * Get the current end time of the state history. It will change as the * history is being built. - * + * * @return The end time */ public long getEndTime(); /** * Main method to insert state intervals into the history. - * + * * @param stateStartTime * The start time of the interval * @param stateEndTime @@ -75,7 +75,7 @@ public interface IStateHistoryBackend { /** * Indicate to the provider that we are done building the history (so it can * close off, stop threads, etc.) - * + * * @param endTime * The end time to assign to this state history. It could be * farther in time than the last state inserted, for example. @@ -88,25 +88,37 @@ public interface IStateHistoryBackend { * It is the responsibility of the backend to define where to save the * Attribute Tree (since it's only useful to "reopen" an Attribute Tree if * we have the matching History). - * + * * This method defines where to read for the attribute tree when opening an * already-existing history. Refer to the file format documentation. - * + * * @return A FileInputStream object pointing to the correct file/location in * the file where to read the attribute tree information. */ public FileInputStream supplyAttributeTreeReader(); // FIXME change to FOS too? + /** + * Supply the File object to which we will write the attribute tree. The + * position in this file is supplied by -TreeWriterFilePosition. + * + * @return The target File + */ public File supplyAttributeTreeWriterFile(); + /** + * Supply the position in the file where we should write the attribute tree + * when asked to. + * + * @return The file position (we will seek() to it) + */ public long supplyAttributeTreeWriterFilePosition(); /** * Delete any generated files or anything that might have been created by * the history backend (either temporary or save files). By calling this, we * return to the state as it was before ever building the history. - * + * * You might not want to call automatically if, for example, you want an * index file to persist on disk. This could be limited to actions * originating from the user. @@ -122,11 +134,13 @@ public interface IStateHistoryBackend { * an "out" parameter, that is, write to it the needed information and * return. DO NOT 'new' currentStateInfo, it will be lost and nothing will * be returned! - * + * * @param currentStateInfo * List of StateValues (index == quark) to fill up * @param t * Target timestamp of the query + * @throws TimeRangeException + * If the timestamp is outside of the history/trace */ public void doQuery(List currentStateInfo, long t) throws TimeRangeException; @@ -136,7 +150,7 @@ public interface IStateHistoryBackend { * single StateValue instead of updating the whole list. If the method to * use is the same, then feel free to just implement this as a wrapper using * doQuery(). - * + * * @param t * The target timestamp of the query. * @param attributeQuark @@ -149,13 +163,13 @@ public interface IStateHistoryBackend { */ public ITmfStateInterval doSingularQuery(long t, int attributeQuark) throws TimeRangeException, AttributeNotFoundException; - + /** * Simple check to make sure the requested timestamps are within the borders - * of this state history. This is used internally, but could also be used - * by the request sender (to check before sending in a lot of requests for + * of this state history. This is used internally, but could also be used by + * the request sender (to check before sending in a lot of requests for * example). - * + * * @param t * The queried timestamp * @return True if the timestamp is within range, false if not. @@ -164,7 +178,7 @@ public interface IStateHistoryBackend { /** * Debug method to print the contents of the history backend. - * + * * @param writer * The PrintWriter where to write the output */ diff --git a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/statesystem/StateHistorySystem.java b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/statesystem/StateHistorySystem.java index 3c5802f917..4ee5cdcde7 100644 --- a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/statesystem/StateHistorySystem.java +++ b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/statesystem/StateHistorySystem.java @@ -2,12 +2,12 @@ * Copyright (c) 2012 Ericsson * Copyright (c) 2010, 2011 École Polytechnique de Montréal * Copyright (c) 2010, 2011 Alexandre Montplaisir - * + * * All rights reserved. This program and the accompanying materials are * made available under the terms of the Eclipse Public License v1.0 which * accompanies this distribution, and is available at * http://www.eclipse.org/legal/epl-v10.html - * + * *******************************************************************************/ package org.eclipse.linuxtools.internal.tmf.core.statesystem; @@ -30,15 +30,15 @@ import org.eclipse.linuxtools.tmf.core.statevalue.TmfStateValue; * This is the extension of the StateSystem, which will save the state intervals * that are created from the transient state (instead of discarding them, like a * simple StateSystem would do). - * + * * This allows the user to then run queries at past timestamps. - * + * * DON'T FORGET to call .closeHistory() when you are done inserting intervals, * or the storage backend will have no way of knowing it can close and write * itself to disk, and its thread will keep running. - * + * * @author alexmont - * + * */ public class StateHistorySystem extends StateSystem implements IStateSystemBuilder { @@ -51,13 +51,14 @@ public class StateHistorySystem extends StateSystem implements /** * General constructor - * + * * @param backend * The "state history storage" backend to use. * @param newFile * Put true if this is a new history started from scratch. It is * used to tell the state system where to get its attribute tree. * @throws IOException + * If there was a problem creating the new history file */ public StateHistorySystem(IStateHistoryBackend backend, boolean newFile) throws IOException { @@ -251,7 +252,7 @@ public class StateHistorySystem extends StateSystem implements if (currentInterval.getEndTime() < tEnd) { currentInterval = querySingleState(tEnd, attributeQuark); intervals.add(currentInterval); - } + } return intervals; } diff --git a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/statesystem/StateSystem.java b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/statesystem/StateSystem.java index a1ebbe1417..d13dc3be26 100644 --- a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/statesystem/StateSystem.java +++ b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/statesystem/StateSystem.java @@ -2,12 +2,12 @@ * Copyright (c) 2012 Ericsson * Copyright (c) 2010, 2011 École Polytechnique de Montréal * Copyright (c) 2010, 2011 Alexandre Montplaisir - * + * * All rights reserved. This program and the accompanying materials are * made available under the terms of the Eclipse Public License v1.0 which * accompanies this distribution, and is available at * http://www.eclipse.org/legal/epl-v10.html - * + * *******************************************************************************/ package org.eclipse.linuxtools.internal.tmf.core.statesystem; @@ -25,16 +25,17 @@ import org.eclipse.linuxtools.tmf.core.statevalue.TmfStateValue; /** * This is the base class for the StateHistorySystem. It contains all the * current-state-updating methods. - * + * * It's not abstract, as it can be used by itself: in this case, no History tree * will be built underneath (no information will be saved to disk) and it will * only be able to respond to queries to the current, latest time. - * + * * (See IStateSystemQuerier and IStateSystemBuilder for the Javadoc.) - * + * * @author alexmont - * + * */ +@SuppressWarnings("javadoc") // the javadoc is in the IStateSystem* interfaces public class StateSystem { /* References to the inner structures */ @@ -325,7 +326,7 @@ public class StateSystem { /** * Print out the contents of the inner structures. - * + * * @param writer * The PrintWriter in which to print the output */ diff --git a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/statesystem/historytree/HistoryTreeBackend.java b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/statesystem/historytree/HistoryTreeBackend.java index 5fb90e7caf..0e119a95c7 100644 --- a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/statesystem/historytree/HistoryTreeBackend.java +++ b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/statesystem/historytree/HistoryTreeBackend.java @@ -2,12 +2,12 @@ * Copyright (c) 2012 Ericsson * Copyright (c) 2010, 2011 École Polytechnique de Montréal * Copyright (c) 2010, 2011 Alexandre Montplaisir - * + * * All rights reserved. This program and the accompanying materials are * made available under the terms of the Eclipse Public License v1.0 which * accompanies this distribution, and is available at * http://www.eclipse.org/legal/epl-v10.html - * + * *******************************************************************************/ package org.eclipse.linuxtools.internal.tmf.core.statesystem.historytree; @@ -27,9 +27,9 @@ import org.eclipse.linuxtools.tmf.core.statevalue.TmfStateValue; /** * History Tree backend for storing a state history. This is the basic version * that runs in the same thread as the class creating it. - * + * * @author alexmont - * + * */ public class HistoryTreeBackend implements IStateHistoryBackend { @@ -39,7 +39,7 @@ public class HistoryTreeBackend implements IStateHistoryBackend { /** * Construtor for new history files. Use this when creating a new history * from scratch. - * + * * @param newStateFile * The filename/location where to store the state history (Should * end in .ht) @@ -63,7 +63,7 @@ public class HistoryTreeBackend implements IStateHistoryBackend { * Construtor for new history files. Use this when creating a new history * from scratch. This version supplies sane defaults for the configuration * parameters. - * + * * @param newStateFile * The filename/location where to store the state history (Should * end in .ht) @@ -79,7 +79,7 @@ public class HistoryTreeBackend implements IStateHistoryBackend { /** * Existing history constructor. Use this to open an existing state-file. - * + * * @param existingStateFile * Filename/location of the history we want to load * @throws IOException @@ -177,7 +177,7 @@ public class HistoryTreeBackend implements IStateHistoryBackend { /** * Inner method to find the interval in the tree containing the requested * key/timestamp pair, wherever in which node it is. - * + * * @param t * @param key * @return The node containing the information we want @@ -207,7 +207,7 @@ public class HistoryTreeBackend implements IStateHistoryBackend { /** * Return the size of the tree history file - * + * * @return The current size of the history file in bytes */ public long getFileSize() { @@ -216,7 +216,7 @@ public class HistoryTreeBackend implements IStateHistoryBackend { /** * Return the current depth of the tree, ie the number of node levels. - * + * * @return The tree depth */ public int getTreeDepth() { @@ -225,7 +225,7 @@ public class HistoryTreeBackend implements IStateHistoryBackend { /** * Return the average node usage as a percentage (between 0 and 100) - * + * * @return Average node usage % */ public int getAverageNodeUsage() { @@ -252,11 +252,13 @@ public class HistoryTreeBackend implements IStateHistoryBackend { /** * The basic debugPrint method will print the tree structure, but not their * contents. - * + * * This method here print the contents (the intervals) as well. - * + * * @param writer + * The PrintWriter to which the debug info will be written * @param printIntervals + * Should we also print every contained interval individually? */ public void debugPrint(PrintWriter writer, boolean printIntervals) { /* Only used for debugging, shouldn't be externalized */ diff --git a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/interval/TmfStateInterval.java b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/interval/TmfStateInterval.java index 0dd1d18501..0fa22b0734 100644 --- a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/interval/TmfStateInterval.java +++ b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/interval/TmfStateInterval.java @@ -2,12 +2,12 @@ * Copyright (c) 2012 Ericsson * Copyright (c) 2010, 2011 École Polytechnique de Montréal * Copyright (c) 2010, 2011 Alexandre Montplaisir - * + * * All rights reserved. This program and the accompanying materials are * made available under the terms of the Eclipse Public License v1.0 which * accompanies this distribution, and is available at * http://www.eclipse.org/legal/epl-v10.html - * + * *******************************************************************************/ package org.eclipse.linuxtools.tmf.core.interval; @@ -18,11 +18,11 @@ import org.eclipse.linuxtools.tmf.core.statevalue.ITmfStateValue; * The StateInterval represents the "state" a particular attribute was in, at a * given time. It is the main object being returned from queries to the state * system. - * + * - * + * * @author alexmont - * + * */ public final class TmfStateInterval implements ITmfStateInterval { @@ -33,11 +33,15 @@ public final class TmfStateInterval implements ITmfStateInterval { /** * Construct an interval from its given parameters - * + * * @param start + * Start time * @param end + * End time * @param attribute + * Attribute linked to this interval * @param sv + * State value this interval will contain */ public TmfStateInterval(long start, long end, int attribute, ITmfStateValue sv) { diff --git a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/statesystem/IStateChangeInput.java b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/statesystem/IStateChangeInput.java index 6c1e7e8b3d..5ed62e8347 100644 --- a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/statesystem/IStateChangeInput.java +++ b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/statesystem/IStateChangeInput.java @@ -2,12 +2,12 @@ * Copyright (c) 2012 Ericsson * Copyright (c) 2010, 2011 École Polytechnique de Montréal * Copyright (c) 2010, 2011 Alexandre Montplaisir - * + * * All rights reserved. This program and the accompanying materials are * made available under the terms of the Eclipse Public License v1.0 which * accompanies this distribution, and is available at * http://www.eclipse.org/legal/epl-v10.html - * + * *******************************************************************************/ package org.eclipse.linuxtools.tmf.core.statesystem; @@ -18,28 +18,28 @@ import org.eclipse.linuxtools.tmf.core.trace.ITmfTrace; /** * This is the interface used to define the "state change input", which is the * main type of input that goes in the state system. - * + * * Usually a state change input, also called "state provider" is the piece of * the pipeline which converts trace events to state changes. - * + * * @author alexmont - * + * */ public interface IStateChangeInput { /** * Get the trace with which this state input plugin is associated. - * + * * @return The associated trace */ @SuppressWarnings("rawtypes") public ITmfTrace getTrace(); - + /** * Return the start time of this "state change input", which is normally the * start time of the originating trace (or it can be the time of the first * state-changing event). - * + * * @return The start time */ public long getStartTime(); @@ -48,7 +48,7 @@ public interface IStateChangeInput { * Method for the input plugin to specify which type of events it expects. * This will guarantee that all events it receives via processEvent() are * indeed of the given type, so it should be safe to cast to that type. - * + * * @return An example event of the expected class, which implements * ITmfEvent. The contents of that event doesn't matter, only the * class will be checked. @@ -59,10 +59,12 @@ public interface IStateChangeInput { * Assign the target state system where this SCI will insert its state * changes. Because of dependencies issues, this can normally not be done at * the constructor. - * + * * This needs to be called before .run()! - * + * * @param ssb + * Target state system for the state changes generated by this + * input plugin */ public void assignTargetStateSystem(IStateSystemBuilder ssb); @@ -70,7 +72,7 @@ public interface IStateChangeInput { * Send an event to this input plugin for processing. The implementation * should check the contents, and call the state-modifying methods of its * IStateSystemBuilder object accordingly. - * + * * @param event * The event (which should be safe to cast to the * expectedEventType) that has to be processed. diff --git a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/statesystem/IStateSystemQuerier.java b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/statesystem/IStateSystemQuerier.java index 12610444b8..e533698e92 100644 --- a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/statesystem/IStateSystemQuerier.java +++ b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/statesystem/IStateSystemQuerier.java @@ -22,31 +22,31 @@ import org.eclipse.linuxtools.tmf.core.statevalue.ITmfStateValue; /** * This is the read-only interface to the generic state system. It contains all * the read-only quark-getting methods, as well as the history-querying ones. - * + * * @author alexmont - * + * */ public interface IStateSystemQuerier { /** * Return the start time of this history. It usually matches the start time * of the original trace. - * + * * @return The history's registered start time */ public long getStartTime(); /** * Return the current end time of the history. - * - * @return + * + * @return The current end time of this state history */ public long getCurrentEndTime(); /** * Return the current total amount of attributes in the system. - * - * @return + * + * @return The current number of attributes in the system */ public int getNbAttributes(); @@ -57,10 +57,10 @@ public interface IStateSystemQuerier { /** * Basic quark-retrieving method. Pass an attribute in parameter as an array * of strings, the matching quark will be returned. - * + * * This version will NOT create any new attributes. If an invalid attribute * is requested, an exception will be thrown. - * + * * @param attribute * Attribute given as its full path in the Attribute Tree * @return The quark of the requested attribute, if it existed. @@ -75,27 +75,28 @@ public interface IStateSystemQuerier { * "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. - * + * * 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. - * + * * This version will NOT create any new attributes. If an invalid attribute * is requested, an exception will be thrown. - * + * * @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 matching quark, if it existed * @throws AttributeNotFoundException + * If the quark is invalid */ public int getQuarkRelative(int startingNodeQuark, String... subPath) throws AttributeNotFoundException; /** * 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. @@ -114,18 +115,18 @@ public interface IStateSystemQuerier { * pattern which includes a wildcard "*" somewhere. It will check all the * existing attributes in the attribute tree and return those who match the * pattern. - * + * * 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 * 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. It * should ideally contain one entry that is only a "*". @@ -138,7 +139,7 @@ public interface IStateSystemQuerier { /** * Return the name assigned to this quark. This returns only the "basename", * not the complete path to this attribute. - * + * * @param attributeQuark * The quark for which we want the name * @return The name of the quark @@ -148,7 +149,7 @@ public interface IStateSystemQuerier { /** * This returns the slash-separated path of an attribute by providing its * quark - * + * * @param attributeQuark * The quark of the attribute we want * @return One single string separated with '/', like a filesystem path @@ -162,11 +163,11 @@ public interface IStateSystemQuerier { /** * Returns the current state value we have (in the Transient State) for the * given attribute. - * + * * This is useful even for a StateHistorySystem, as we are guaranteed it * will only do a memory access and not go look on disk (and we don't even * have to provide a timestamp!) - * + * * @param attributeQuark * For which attribute we want the current state * @return The State value that's "current" for this attribute @@ -180,15 +181,16 @@ public interface IStateSystemQuerier { * Load the complete state information at time 't' into the returned List. * You can then get the intervals for single attributes by using * List.get(n), where 'n' is the quark of the attribute. - * + * * On average if you need around 10 or more queries for the same timestamps, * use this method. If you need less than 10 (for example, running many * queries for the same attributes but at different timestamps), you might * be better using the querySingleState() methods instead. - * + * * @param t * We will recreate the state information to what it was at time * t. + * @return The List of intervals, where the offset = the quark * @throws TimeRangeException * If the 't' parameter is outside of the range of the state * history. @@ -200,12 +202,12 @@ public interface IStateSystemQuerier { * Singular query method. This one does not update the whole stateInfo * vector, like queryFullState() does. It only searches for one specific * entry in the state history. - * + * * It should be used when you only want very few entries, instead of the * whole state (or many entries, but all at different timestamps). If you do * request many entries all at the same time, you should use the * conventional queryFullState() + List.get() method. - * + * * @param t * The timestamp at which we want the state * @param attributeQuark @@ -223,11 +225,11 @@ public interface IStateSystemQuerier { * Return a list of state intervals, containing the "history" of a given * attribute between timestamps t1 and t2. The list will be ordered by * ascending time. - * + * * Note that contrary to queryFullState(), the returned list here is in the * "direction" of time (and not in the direction of attributes, as is the * case with queryFullState()). - * + * * @param attributeQuark * Which attribute this query is interested in * @param t1 @@ -250,7 +252,7 @@ public interface IStateSystemQuerier { * Return the state history of a given attribute, but with at most one * update per "resolution". This can be useful for populating views (where * it's useless to have more than one query per pixel, for example). - * + * * @param attributeQuark * Which attribute this query is interested in * @param t1 diff --git a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/statesystem/StateSystemManager.java b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/statesystem/StateSystemManager.java index 7a61a2e1bf..1529dd5df7 100644 --- a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/statesystem/StateSystemManager.java +++ b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/statesystem/StateSystemManager.java @@ -55,6 +55,8 @@ public abstract class StateSystemManager extends TmfComponent { * @return A IStateSystemQuerier handler to the state system, with which you * can then run queries on the history. * @throws TmfTraceException + * If there was a problem reading or writing one of the files. + * See the contents of this exception for more info. */ public static IStateSystemQuerier loadStateHistory(File htFile, IStateChangeInput htInput, boolean buildManually) diff --git a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/statevalue/ITmfStateValue.java b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/statevalue/ITmfStateValue.java index 2f4a205896..5c7b716ad8 100644 --- a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/statevalue/ITmfStateValue.java +++ b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/statevalue/ITmfStateValue.java @@ -1,11 +1,11 @@ /******************************************************************************* * Copyright (c) 2012 Ericsson - * + * * All rights reserved. This program and the accompanying materials are * made available under the terms of the Eclipse Public License v1.0 which * accompanies this distribution, and is available at * http://www.eclipse.org/legal/epl-v10.html - * + * * Contributors: * Alexandre Montplaisir - Initial API ******************************************************************************/ @@ -17,27 +17,32 @@ import org.eclipse.linuxtools.tmf.core.exceptions.StateValueTypeException; /** * This is the interface for using state values and reading their contents. - * + * * @author alexmont - * + * */ public interface ITmfStateValue { + /** The 'byte' value associated to null state values (-1) */ public static final byte TYPE_NULL = -1; + + /** The 'byte' value associated to integer state values (0) */ public static final byte TYPE_INTEGER = 0; + + /** The 'byte' value associated to null state values (1) */ public static final byte TYPE_STRING = 1; /** * Each implementation has to supply a "type" number. This will get written * as-is in the History file to recognize the type, so it needs to be unique - * + * * @return The unique "int8" assigned to this state value type */ public byte getType(); /** * Only "null values" should return true here - * + * * @return True if this type of SV is considered "null", false if it * contains a real value. */ @@ -45,7 +50,7 @@ public interface ITmfStateValue { /** * Read the contained value as an 'int' primitive - * + * * @return The integer contained in the state value * @throws StateValueTypeException * If the contained value cannot be read as an integer @@ -54,7 +59,7 @@ public interface ITmfStateValue { /** * Read the contained value as a String - * + * * @return The String contained in the state value * @throws StateValueTypeException * If the contained value cannot be read as a String diff --git a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/statevalue/TmfStateValue.java b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/statevalue/TmfStateValue.java index 65d1f12ab4..8ca6f35246 100644 --- a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/statevalue/TmfStateValue.java +++ b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/statevalue/TmfStateValue.java @@ -2,12 +2,12 @@ * Copyright (c) 2012 Ericsson * Copyright (c) 2010, 2011 École Polytechnique de Montréal * Copyright (c) 2010, 2011 Alexandre Montplaisir - * + * * All rights reserved. This program and the accompanying materials are * made available under the terms of the Eclipse Public License v1.0 which * accompanies this distribution, and is available at * http://www.eclipse.org/legal/epl-v10.html - * + * ******************************************************************************/ package org.eclipse.linuxtools.tmf.core.statevalue; @@ -18,27 +18,27 @@ import org.eclipse.linuxtools.tmf.core.exceptions.StateValueTypeException; /** * This is the wrapper class that exposes the different types of 'state values' * available to use in the State System. - * + * * This also defines how these values are to be stored in the History Tree. For * example, we can save numerical values as integers instead of arrays of * 1-digit characters. - * + * * For now the two available types are either int or String. - * + * * @author alexmont - * + * */ public abstract class TmfStateValue implements ITmfStateValue { /** * Retrieve directly the value object contained within. Implementing * subclasses may limit the return type here. - * + * * It's protected, since we do not want to expose this directly in the * public API (and require all its users to manually cast to the right * types). All accesses to the values should go through the "unbox-" * methods. - * + * * @return The underneath object assigned to this state value. */ protected abstract Object getValue(); @@ -48,6 +48,8 @@ public abstract class TmfStateValue implements ITmfStateValue { * Alternatively you can return "null" here if you do not need a byte-array * indirection (the getValue will get written as-in instead of the offset in * the file block) + * + * @return The state value in byte array form */ public abstract byte[] toByteArray(); @@ -88,7 +90,7 @@ public abstract class TmfStateValue implements ITmfStateValue { /** * Return the max size that a variable-length state value can have when * serialized. - * + * * @return The maximum size in bytes */ public static int getStateValueMaxSize() { @@ -103,7 +105,7 @@ public abstract class TmfStateValue implements ITmfStateValue { /** * Return an instance of a "null" value. Only one copy exists in memory. - * + * * @return A null value */ public final static TmfStateValue nullValue() { @@ -112,7 +114,7 @@ public abstract class TmfStateValue implements ITmfStateValue { /** * Factory constructor for Integer state values - * + * * @param intValue The integer value to contain * @return The newly-created TmfStateValue object */ @@ -125,7 +127,7 @@ public abstract class TmfStateValue implements ITmfStateValue { /** * Factory constructor for String state values - * + * * @param strValue The string value to contain * @return The newly-create TmfStateValue object */ -- 2.34.1