tmf: Add proper API to statesystem.backends.historytree
authorAlexandre Montplaisir <alexmonthy@voxpopuli.im>
Mon, 16 Dec 2013 23:04:25 +0000 (18:04 -0500)
committerAlexandre Montplaisir <alexmonthy@voxpopuli.im>
Tue, 14 Jan 2014 20:02:02 +0000 (15:02 -0500)
Change-Id: If860d2ba73cb001eb72dedb95c3982604b4c1b8e
Signed-off-by: Alexandre Montplaisir <alexmonthy@voxpopuli.im>
Reviewed-on: https://git.eclipse.org/r/19885
Tested-by: Hudson CI
org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/statesystem/backends/historytree/CoreNode.java
org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/statesystem/backends/historytree/HTConfig.java
org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/statesystem/backends/historytree/HTInterval.java
org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/statesystem/backends/historytree/HTNode.java
org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/statesystem/backends/historytree/HT_IO.java
org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/statesystem/backends/historytree/HistoryTree.java
org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/statesystem/backends/historytree/HistoryTreeBackend.java

index 59f9aff29d8dd96cf2d3193324cecfd814f259e0..10f4b442f0aa13b12bf14fefb851e1a02c40a50f 100644 (file)
@@ -22,7 +22,7 @@ import java.nio.ByteBuffer;
  * @author Alexandre Montplaisir
  *
  */
-class CoreNode extends HTNode {
+public class CoreNode extends HTNode {
 
     /** Number of bytes in a int */
     private static final int SIZE_INT = 4;
@@ -40,7 +40,7 @@ class CoreNode extends HTNode {
     private long[] childStart;
 
     /** Seq number of this node's extension. -1 if none */
-    private int extension;
+    private int extension = -1;
 
     /**
      * Initial constructor. Use this to initialize a new EMPTY node.
@@ -54,7 +54,7 @@ class CoreNode extends HTNode {
      * @param start
      *            The earliest timestamp stored in this node
      */
-    CoreNode(HTConfig config, int seqNumber, int parentSeqNumber,
+    protected CoreNode(HTConfig config, int seqNumber, int parentSeqNumber,
             long start) {
         super(config, seqNumber, parentSeqNumber, start);
         this.nbChildren = 0;
@@ -71,7 +71,7 @@ class CoreNode extends HTNode {
     }
 
     @Override
-    protected void readSpecificHeader(ByteBuffer buffer) {
+    public void readSpecificHeader(ByteBuffer buffer) {
         int size = getConfig().getMaxChildren();
 
         extension = buffer.getInt();
@@ -95,7 +95,7 @@ class CoreNode extends HTNode {
     }
 
     @Override
-    protected void writeSpecificHeader(ByteBuffer buffer) {
+    public void writeSpecificHeader(ByteBuffer buffer) {
         int size = getConfig().getMaxChildren();
 
         buffer.putInt(extension);
@@ -118,27 +118,61 @@ class CoreNode extends HTNode {
         }
     }
 
-    int getNbChildren() {
+    /**
+     * Return the number of child nodes this node has.
+     *
+     * @return The number of child nodes
+     */
+    public int getNbChildren() {
         return nbChildren;
     }
 
-    int getChild(int index) {
+    /**
+     * Get the child node corresponding to the specified index
+     *
+     * @param index The index of the child to lookup
+     * @return The child node
+     */
+    public int getChild(int index) {
         return children[index];
     }
 
-    int getLatestChild() {
+    /**
+     * Get the latest (right-most) child node of this node.
+     *
+     * @return The latest child node
+     */
+    public int getLatestChild() {
         return children[nbChildren - 1];
     }
 
-    long getChildStart(int index) {
+    /**
+     * Get the start time of the specified child node.
+     *
+     * @param index
+     *            The index of the child node
+     * @return The start time of the that child node.
+     */
+    public long getChildStart(int index) {
         return childStart[index];
     }
 
-    long getLatestChildStart() {
+    /**
+     * Get the start time of the latest (right-most) child node.
+     *
+     * @return The start time of the latest child
+     */
+    public long getLatestChildStart() {
         return childStart[nbChildren - 1];
     }
 
-    int getExtensionSequenceNumber() {
+    /**
+     * Get the sequence number of the extension to this node (if there is one).
+     *
+     * @return The sequence number of the extended node. '-1' is returned if
+     *         there is no extension node.
+     */
+    public int getExtensionSequenceNumber() {
         return extension;
     }
 
@@ -148,7 +182,7 @@ class CoreNode extends HTNode {
      * @param childNode
      *            The SHTNode object of the new child
      */
-    void linkNewChild(CoreNode childNode) {
+    public void linkNewChild(CoreNode childNode) {
         assert (this.nbChildren < getConfig().getMaxChildren());
 
         this.children[nbChildren] = childNode.getSequenceNumber();
@@ -157,12 +191,12 @@ class CoreNode extends HTNode {
     }
 
     @Override
-    protected byte getNodeType() {
+    public byte getNodeType() {
         return 1;
     }
 
     @Override
-    protected int getTotalHeaderSize() {
+    public int getTotalHeaderSize() {
         int maxChildren = getConfig().getMaxChildren();
         int specificSize =
                   SIZE_INT /* 1x int (extension node) */
@@ -178,7 +212,7 @@ class CoreNode extends HTNode {
     }
 
     @Override
-    protected String toStringSpecific() {
+    public String toStringSpecific() {
         /* Only used for debugging, shouldn't be externalized */
         return "Core Node, " + nbChildren + " children, "; //$NON-NLS-1$ //$NON-NLS-2$
     }
index 28eb45f4bd0b537076eda881781c11aef29caaf6..31539c53596e6e25119cdf74fc8b9f8de84b8755 100644 (file)
@@ -15,11 +15,11 @@ package org.eclipse.linuxtools.internal.tmf.core.statesystem.backends.historytre
 import java.io.File;
 
 /**
- * Configuration object for a StateHistoryTree.
+ * Configuration object for the {@link HistoryTree}.
  *
- * @author alexmont
+ * @author Alexandre Montplaisir
  */
-final class HTConfig {
+public final class HTConfig {
 
     private static final int DEFAULT_BLOCKSIZE = 64 * 1024;
     private static final int DEFAULT_MAXCHILDREN = 50;
@@ -30,7 +30,25 @@ final class HTConfig {
     private final int providerVersion;
     private final long treeStart;
 
-    HTConfig(File newStateFile, int blockSize, int maxChildren,
+    /**
+     * Full constructor.
+     *
+     * @param newStateFile
+     *            The name of the history file
+     * @param blockSize
+     *            The size of each "block" on disk. One node will always fit in
+     *            one block.
+     * @param maxChildren
+     *            The maximum number of children allowed per core (non-leaf)
+     *            node.
+     * @param providerVersion
+     *            The version of the state provider. If a file already exists,
+     *            and their versions match, the history file will not be rebuilt
+     *            uselessly.
+     * @param startTime
+     *            The start time of the history
+     */
+    public HTConfig(File newStateFile, int blockSize, int maxChildren,
             int providerVersion, long startTime) {
         this.stateFile = newStateFile;
         this.blockSize = blockSize;
@@ -40,12 +58,19 @@ final class HTConfig {
     }
 
     /**
-     * Version using default values for blocksize and maxchildren
+     * Version of the constructor using default values for 'blockSize' and
+     * 'maxChildren'.
      *
-     * @param stateFileName
+     * @param newStateFile
+     *            The name of the history file
+     * @param providerVersion
+     *            The version of the state provider. If a file already exists,
+     *            and their versions match, the history file will not be rebuilt
+     *            uselessly.
      * @param startTime
+     *            The start time of the history
      */
-    HTConfig(File newStateFile, int providerVersion, long startTime) {
+    public HTConfig(File newStateFile, int providerVersion, long startTime) {
         this(newStateFile, DEFAULT_BLOCKSIZE, DEFAULT_MAXCHILDREN, providerVersion, startTime);
     }
 
@@ -53,22 +78,47 @@ final class HTConfig {
     // Getters
     // ------------------------------------------------------------------------
 
+    /**
+     * Get the history file.
+     *
+     * @return The history file
+     */
     public File getStateFile() {
         return stateFile;
     }
 
+    /**
+     * Get the configure block size.
+     *
+     * @return The block size
+     */
     public int getBlockSize() {
         return blockSize;
     }
 
+    /**
+     * Get the maximum amount of children allowed.
+     *
+     * @return The maximum amount of children
+     */
     public int getMaxChildren() {
         return maxChildren;
     }
 
+    /**
+     * Get the state provider's version.
+     *
+     * @return The state provider's version
+     */
     public int getProviderVersion() {
         return providerVersion;
     }
 
+    /**
+     * Get the start time of the history
+     *
+     * @return The start time
+     */
     public long getTreeStart() {
         return treeStart;
     }
index 9b4bdb36f0db9517e2e9e373190fe9da113d334c..c9d38ce0ab66f494d0361e36a108ed554b13b2a1 100644 (file)
@@ -25,10 +25,9 @@ import org.eclipse.linuxtools.tmf.core.statevalue.TmfStateValue;
  * The interval component, which will be contained in a node of the History
  * Tree.
  *
- * @author alexmont
- *
+ * @author Alexandre Montplaisir
  */
-final class HTInterval implements ITmfStateInterval, Comparable<HTInterval> {
+public final class HTInterval implements ITmfStateInterval, Comparable<HTInterval> {
 
     private static final String errMsg = "Invalid interval data. Maybe your file is corrupt?"; //$NON-NLS-1$
 
@@ -59,12 +58,18 @@ final class HTInterval implements ITmfStateInterval, Comparable<HTInterval> {
      * Standard constructor
      *
      * @param intervalStart
+     *            Start time of the interval
      * @param intervalEnd
+     *            End time of the interval
      * @param attribute
+     *            Attribute (quark) to which the state represented by this
+     *            interval belongs
      * @param value
+     *            State value represented by this interval
      * @throws TimeRangeException
+     *             If the start time or end time are invalid
      */
-    HTInterval(long intervalStart, long intervalEnd, int attribute,
+    public HTInterval(long intervalStart, long intervalEnd, int attribute,
             TmfStateValue value) throws TimeRangeException {
         if (intervalStart > intervalEnd) {
             throw new TimeRangeException();
@@ -82,13 +87,6 @@ final class HTInterval implements ITmfStateInterval, Comparable<HTInterval> {
      * reading it from disk (with {@link #readFrom}), we already know the size
      * of the strings entry, so there is no need to call
      * {@link #computeStringsEntrySize()} and do an extra copy.
-     *
-     * @param intervalStart
-     * @param intervalEnd
-     * @param attribute
-     * @param value
-     * @param size
-     * @throws TimeRangeException
      */
     private HTInterval(long intervalStart, long intervalEnd, int attribute,
             TmfStateValue value, int size) throws TimeRangeException {
@@ -104,14 +102,16 @@ final class HTInterval implements ITmfStateInterval, Comparable<HTInterval> {
     }
 
     /**
-     * Reader constructor. Builds the interval using an already-allocated
+     * Reader factory method. Builds the interval using an already-allocated
      * ByteBuffer, which normally comes from a NIO FileChannel.
      *
      * @param buffer
      *            The ByteBuffer from which to read the information
+     * @return The interval object
      * @throws IOException
+     *             If there was an error reading from the buffer
      */
-    final static HTInterval readFrom(ByteBuffer buffer) throws IOException {
+    public static final HTInterval readFrom(ByteBuffer buffer) throws IOException {
         HTInterval interval;
         long intervalStart, intervalEnd;
         int attribute;
@@ -227,7 +227,7 @@ final class HTInterval implements ITmfStateInterval, Comparable<HTInterval> {
      *            StateValues.
      * @return The size of the Strings Entry that was written, if any.
      */
-    int writeInterval(ByteBuffer buffer, int endPosOfStringEntry) {
+    public int writeInterval(ByteBuffer buffer, int endPosOfStringEntry) {
         buffer.putLong(start);
         buffer.putLong(end);
         buffer.putInt(attribute);
@@ -365,9 +365,9 @@ final class HTInterval implements ITmfStateInterval, Comparable<HTInterval> {
     /**
      * Total serialized size of this interval
      *
-     * @return
+     * @return The interval size
      */
-    int getIntervalSize() {
+    public int getIntervalSize() {
         return stringsEntrySize + HTNode.DATA_ENTRY_SIZE;
     }
 
index d2eca6af6af918bb1bc882bf9410c8ad9ef9e723..8f14ae81e0102a681422ca7fe43b3b4254d9ef09 100644 (file)
@@ -30,7 +30,7 @@ import org.eclipse.linuxtools.tmf.core.statevalue.TmfStateValue;
  *
  * @author Alexandre Montplaisir
  */
-abstract class HTNode {
+public abstract class HTNode {
 
     /**
      * Size of an entry in the data section.
@@ -62,7 +62,19 @@ abstract class HTNode {
     /* Vector containing all the intervals contained in this node */
     private final List<HTInterval> intervals;
 
-    HTNode(HTConfig config, int seqNumber, int parentSeqNumber, long start) {
+    /**
+     * Constructor
+     *
+     * @param config
+     *            Configuration of the History Tree
+     * @param seqNumber
+     *            The (unique) sequence number assigned to this particular node
+     * @param parentSeqNumber
+     *            The sequence number of this node's parent node
+     * @param start
+     *            The earliest timestamp stored in this node
+     */
+    protected HTNode(HTConfig config, int seqNumber, int parentSeqNumber, long start) {
         this.config = config;
         this.nodeStart = start;
         this.sequenceNumber = seqNumber;
@@ -74,17 +86,19 @@ abstract class HTNode {
     }
 
     /**
-     * Reader factory constructor. Build a Node object (of the right type) by
-     * reading a block in the file.
+     * Reader factory method. Build a Node object (of the right type) by reading
+     * a block in the file.
      *
      * @param config
      *            Configuration of the History Tree
      * @param fc
      *            FileChannel to the history file, ALREADY SEEKED at the start
      *            of the node.
+     * @return The node object
      * @throws IOException
+     *             If there was an error reading from the file channel
      */
-    static final HTNode readNode(HTConfig config, FileChannel fc)
+    public static final HTNode readNode(HTConfig config, FileChannel fc)
             throws IOException {
         HTNode newNode = null;
         int res, i;
@@ -145,7 +159,16 @@ abstract class HTNode {
         return newNode;
     }
 
-    final void writeSelf(FileChannel fc) throws IOException {
+    /**
+     * Write this node to the given file channel.
+     *
+     * @param fc
+     *            The file channel to write to (should be sought to be correct
+     *            position)
+     * @throws IOException
+     *             If there was an error writing
+     */
+    public final void writeSelf(FileChannel fc) throws IOException {
         final int blockSize = config.getBlockSize();
         int curStringsEntryEndPos = blockSize;
 
@@ -201,38 +224,71 @@ abstract class HTNode {
     // Accessors
     // ------------------------------------------------------------------------
 
-    HTConfig getConfig() {
+    /**
+     * Retrieve the history tree configuration used for this node.
+     *
+     * @return The history tree config
+     */
+    protected HTConfig getConfig() {
         return config;
     }
 
-    long getNodeStart() {
+    /**
+     * Get the start time of this node.
+     *
+     * @return The start time of this node
+     */
+    public long getNodeStart() {
         return nodeStart;
     }
 
-    long getNodeEnd() {
+    /**
+     * Get the end time of this node.
+     *
+     * @return The end time  of this node
+     */
+    public long getNodeEnd() {
         if (this.isDone) {
             return nodeEnd;
         }
         return 0;
     }
 
-    int getSequenceNumber() {
+    /**
+     * Get the sequence number of this node.
+     *
+     * @return The sequence number of this node
+     */
+    public int getSequenceNumber() {
         return sequenceNumber;
     }
 
-    int getParentSequenceNumber() {
+    /**
+     * Get the sequence number of this node's parent.
+     *
+     * @return The parent sequence number
+     */
+    public int getParentSequenceNumber() {
         return parentSequenceNumber;
     }
 
     /**
      * Change this node's parent. Used when we create a new root node for
      * example.
+     *
+     * @param newParent
+     *            The sequence number of the node that is the new parent
      */
-    void setParentSequenceNumber(int newParent) {
+    public void setParentSequenceNumber(int newParent) {
         parentSequenceNumber = newParent;
     }
 
-    boolean isDone() {
+    /**
+     * Return if this node is "done" (full and written to disk).
+     *
+     * @return If this node is done or not
+     */
+    public boolean isDone() {
         return isDone;
     }
 
@@ -240,8 +296,9 @@ abstract class HTNode {
      * Add an interval to this node
      *
      * @param newInterval
+     *            Interval to add to this node
      */
-    void addInterval(HTInterval newInterval) {
+    public void addInterval(HTInterval newInterval) {
         /* Just in case, but should be checked before even calling this function */
         assert (newInterval.getIntervalSize() <= this.getNodeFreeSpace());
 
@@ -257,9 +314,8 @@ abstract class HTNode {
      *
      * @param endtime
      *            The nodeEnd time that the node will have
-     * @throws TimeRangeException
      */
-    void closeThisNode(long endtime) {
+    public void closeThisNode(long endtime) {
         assert (endtime >= this.nodeStart);
 
         if (intervals.size() > 0) {
@@ -293,8 +349,9 @@ abstract class HTNode {
      *            The timestamp for which the query is for. Only return
      *            intervals that intersect t.
      * @throws TimeRangeException
+     *             If 't' is invalid
      */
-    void writeInfoFromNode(List<ITmfStateInterval> stateInfo, long t)
+    public void writeInfoFromNode(List<ITmfStateInterval> stateInfo, long t)
             throws TimeRangeException {
         assert (this.isDone); // not sure this will always be the case...
         int startIndex;
@@ -321,12 +378,14 @@ abstract class HTNode {
      * key/timestamp pair cannot be found, we return null.
      *
      * @param key
+     *            The attribute quark to look for
      * @param t
+     *            The timestamp
      * @return The Interval containing the information we want, or null if it
      *         wasn't found
-     * @throws TimeRangeException
+     * @throws TimeRangeException If 't' is invalid
      */
-    HTInterval getRelevantInterval(int key, long t) throws TimeRangeException {
+    public HTInterval getRelevantInterval(int key, long t) throws TimeRangeException {
         assert (this.isDone);
         int startIndex;
         HTInterval curInterval;
@@ -403,16 +462,21 @@ abstract class HTNode {
     /**
      * Returns the free space in the node, which is simply put, the
      * stringSectionOffset - dataSectionOffset
+     *
+     * @return The amount of free space in the node (in bytes)
      */
-    int getNodeFreeSpace() {
+    public int getNodeFreeSpace() {
         return stringSectionOffset - this.getDataSectionEndOffset();
     }
 
     /**
-     * Returns the current space utilisation of this node, as a percentage.
+     * Returns the current space utilization of this node, as a percentage.
      * (used space / total usable space, which excludes the header)
+     *
+     * @return The percentage (value between 0 and 100) of space utilization in
+     *         in this node.
      */
-    long getNodeUsagePRC() {
+    public long getNodeUsagePercent() {
         final int blockSize = config.getBlockSize();
         float freePercent = (float) this.getNodeFreeSpace()
                 / (float) (blockSize - this.getTotalHeaderSize())
@@ -420,6 +484,13 @@ abstract class HTNode {
         return (long) (100L - freePercent);
     }
 
+    /**
+     * Convert from a boolean to a byte primitive.
+     *
+     * @param thebool
+     *            The boolean to convert
+     * @return A byte worth 0 (false) or 1 (true)
+     */
     protected static final byte boolToByte(boolean thebool) {
         if (thebool) {
             return (byte) 1;
@@ -427,7 +498,14 @@ abstract class HTNode {
         return (byte) 0;
     }
 
-    static final boolean byteToBool(byte thebyte) {
+    /**
+     * Convert from a byte primitive (0 or 1) to a boolean.
+     *
+     * @param thebyte
+     *            The byte to convert
+     * @return True if 'thebyte' is 1, false otherwise
+     */
+    protected static final boolean byteToBool(byte thebyte) {
         return (thebyte == (byte) 1);
     }
 
@@ -441,7 +519,7 @@ abstract class HTNode {
         /* Only used for debugging, shouldn't be externalized */
         StringBuffer buf = new StringBuffer("Node #" + sequenceNumber + ", ");
         buf.append(this.toStringSpecific());
-        buf.append(intervals.size() + " intervals (" + this.getNodeUsagePRC()
+        buf.append(intervals.size() + " intervals (" + this.getNodeUsagePercent()
                 + "% used), ");
 
         buf.append("[" + this.nodeStart + " - ");
@@ -460,7 +538,7 @@ abstract class HTNode {
      *            PrintWriter in which we will print the debug output
      */
     @SuppressWarnings("nls")
-    void debugPrintIntervals(PrintWriter writer) {
+    public void debugPrintIntervals(PrintWriter writer) {
         /* Only used for debugging, shouldn't be externalized */
         writer.println("Node #" + sequenceNumber + ":");
 
@@ -502,13 +580,42 @@ abstract class HTNode {
     // Abstract methods
     // ------------------------------------------------------------------------
 
-    protected abstract byte getNodeType();
+    /**
+     * Get the byte value representing the node type.
+     *
+     * @return The node type
+     */
+    public abstract byte getNodeType();
 
-    protected abstract int getTotalHeaderSize();
+    /**
+     * Return the total header size of this node type.
+     *
+     * @return The total header size
+     */
+    public abstract int getTotalHeaderSize();
 
-    protected abstract void readSpecificHeader(ByteBuffer buffer);
+    /**
+     * Read the type-specific part of the node header from a byte buffer.
+     *
+     * @param buffer
+     *            The byte buffer to read from. It should be already positioned
+     *            correctly.
+     */
+    public abstract void readSpecificHeader(ByteBuffer buffer);
 
-    protected abstract void writeSpecificHeader(ByteBuffer buffer);
+    /**
+     * Write the type-specific part of the header in a byte buffer.
+     *
+     * @param buffer
+     *            The buffer to write to. It should already be at the correct
+     *            position.
+     */
+    public abstract void writeSpecificHeader(ByteBuffer buffer);
 
-    protected abstract String toStringSpecific();
+    /**
+     * Node-type-specific toString method. Used for debugging.
+     *
+     * @return A string representing the node
+     */
+    public abstract String toStringSpecific();
 }
index 6bb9fd8cbcc09b42df41d02c0d55ce73980de7f5..1c0257a3aa019935cf67a6bba95fdb1a502cdd79 100644 (file)
@@ -56,7 +56,7 @@ class HT_IO {
      * @throws IOException
      *             An exception can be thrown when file cannot be accessed
      */
-    HT_IO(HTConfig config, boolean newFile) throws IOException {
+    public HT_IO(HTConfig config, boolean newFile) throws IOException {
         fConfig = config;
 
         File historyTreeFile = config.getStateFile();
@@ -87,16 +87,17 @@ class HT_IO {
     }
 
     /**
-     * This method here isn't private, if we know for sure the node cannot be in
-     * memory it's a bit faster to use this directly (when opening a file from
-     * disk for example)
+     * Read a node from the file on disk.
      *
+     * @param seqNumber
+     *            The sequence number of the node to read.
+     * @return The object representing the node
      * @throws ClosedChannelException
      *             Usually happens because the file was closed while we were
      *             reading. Instead of using a big reader-writer lock, we'll
      *             just catch this exception.
      */
-    synchronized HTNode readNode(int seqNumber) throws ClosedChannelException {
+    public synchronized HTNode readNode(int seqNumber) throws ClosedChannelException {
         /* Do a cache lookup */
         int offset = seqNumber & (CACHE_SIZE - 1);
         HTNode readNode = fNodeCache[offset];
@@ -121,7 +122,7 @@ class HT_IO {
         }
     }
 
-    void writeNode(HTNode node) {
+    public void writeNode(HTNode node) {
         try {
             /* Insert the node into the cache. */
             int seqNumber = node.getSequenceNumber();
@@ -137,11 +138,11 @@ class HT_IO {
         }
     }
 
-    FileChannel getFcOut() {
+    public  FileChannel getFcOut() {
         return this.fcOut;
     }
 
-    FileInputStream supplyATReader(int nodeOffset) {
+    public FileInputStream supplyATReader(int nodeOffset) {
         try {
             /*
              * Position ourselves at the start of the Mapping section in the
@@ -154,7 +155,7 @@ class HT_IO {
         return fis;
     }
 
-    synchronized void closeFile() {
+    public synchronized void closeFile() {
         try {
             fis.close();
             fos.close();
@@ -163,7 +164,7 @@ class HT_IO {
         }
     }
 
-    synchronized void deleteFile() {
+    public synchronized void deleteFile() {
         closeFile();
 
         File historyTreeFile = fConfig.getStateFile();
index 576a2d4e7b989998114e0442e96c102ad62bf785..7f00e248775a344f99e3b8da8e5ebef4113cccaa 100644 (file)
@@ -32,9 +32,8 @@ import org.eclipse.linuxtools.tmf.core.statesystem.ITmfStateProvider;
  * high-level data relevant to the tree.
  *
  * @author Alexandre Montplaisir
- *
  */
-class HistoryTree {
+public class HistoryTree {
 
     /**
      * Size of the "tree header" in the tree-file The nodes will use this offset
@@ -76,10 +75,16 @@ class HistoryTree {
     // ------------------------------------------------------------------------
 
     /**
-     * Create a new State History from scratch, using a SHTConfig object for
-     * configuration
+     * Create a new State History from scratch, using a {@link HTConfig} object
+     * for configuration.
+     *
+     * @param conf
+     *            The config to use for this History Tree.
+     * @throws IOException
+     *             If an error happens trying to open/write to the file
+     *             specified in the config
      */
-    HistoryTree(HTConfig conf) throws IOException {
+    public HistoryTree(HTConfig conf) throws IOException {
         /*
          * Simple check to make sure we have enough place in the 0th block
          * for the tree configuration
@@ -105,13 +110,14 @@ class HistoryTree {
      * "Reader" constructor : instantiate a SHTree from an existing tree file on
      * disk
      *
-     * @param existingFileName
+     * @param existingStateFile
      *            Path/filename of the history-file we are to open
      * @param expProviderVersion
      *            The expected version of the state provider
      * @throws IOException
+     *             If an error happens reading the file
      */
-    HistoryTree(File existingStateFile, int expProviderVersion) throws IOException {
+    public HistoryTree(File existingStateFile, int expProviderVersion) throws IOException {
         /*
          * Open the file ourselves, get the tree header information we need,
          * then pass on the descriptor to the TreeIO object.
@@ -204,7 +210,7 @@ class HistoryTree {
      * @param requestedEndTime
      *            The greatest timestamp present in the history tree
      */
-    void closeTree(long requestedEndTime) {
+    public void closeTree(long requestedEndTime) {
         ByteBuffer buffer;
         int i, res;
 
@@ -267,23 +273,39 @@ class HistoryTree {
     // Accessors
     // ------------------------------------------------------------------------
 
-    HTConfig getConfig() {
-        return config;
-    }
-
-    long getTreeStart() {
+    /**
+     * Get the start time of this tree.
+     *
+     * @return The start time
+     */
+    public long getTreeStart() {
         return config.getTreeStart();
     }
 
-    long getTreeEnd() {
+    /**
+     * Get the current end time of this tree.
+     *
+     * @return The end time
+     */
+    public long getTreeEnd() {
         return treeEnd;
     }
 
-    int getNodeCount() {
+    /**
+     * Get the number of nodes in this tree.
+     *
+     * @return The number of nodes
+     */
+    public int getNodeCount() {
         return nodeCount;
     }
 
-    List<CoreNode> getLatestBranch() {
+    /**
+     * Return the latest (right-most) branch of nodes.
+     *
+     * @return The latest branch
+     */
+    public List<CoreNode> getLatestBranch() {
         return Collections.unmodifiableList(latestBranch);
     }
 
@@ -291,20 +313,47 @@ class HistoryTree {
     // HT_IO interface
     // ------------------------------------------------------------------------
 
-    File supplyATWriterFile() {
-        return config.getStateFile();
+    /**
+     * Return the FileInputStream reader with which we will read an attribute
+     * tree (it will be sought to the correct position).
+     *
+     * @return The FileInputStream indicating the file and position from which
+     *         the attribute tree can be read.
+     */
+    public FileInputStream supplyATReader() {
+        return treeIO.supplyATReader(getNodeCount());
     }
 
-    FileInputStream supplyATReader() {
-        return treeIO.supplyATReader(getNodeCount());
+    /**
+     * Return the file to which we will write the attribute tree.
+     *
+     * @return The file to which we will write the attribute tree
+     */
+    public File supplyATWriterFile() {
+        return config.getStateFile();
     }
 
-    long supplyATWriterFilePos() {
+    /**
+     * Return the position in the file (given by {@link #supplyATWriterFile})
+     * where to start writing the attribute tree.
+     *
+     * @return The position in the file where to start writing
+     */
+    public long supplyATWriterFilePos() {
         return HistoryTree.TREE_HEADER_SIZE
                 + ((long) getNodeCount() * config.getBlockSize());
     }
 
-    HTNode readNode(int seqNumber) throws ClosedChannelException {
+    /**
+     * Read a node from the tree.
+     *
+     * @param seqNumber
+     *            The sequence number of the node to read
+     * @return The node
+     * @throws ClosedChannelException
+     *             If the tree IO is unavailable
+     */
+    public HTNode readNode(int seqNumber) throws ClosedChannelException {
         /* Try to read the node from memory */
         for (HTNode node : getLatestBranch()) {
             if (node.getSequenceNumber() == seqNumber) {
@@ -316,15 +365,27 @@ class HistoryTree {
         return treeIO.readNode(seqNumber);
     }
 
-    void writeNode(HTNode node) {
+    /**
+     * Write a node object to the history file.
+     *
+     * @param node
+     *            The node to write to disk
+     */
+    public void writeNode(HTNode node) {
         treeIO.writeNode(node);
     }
 
-    void closeFile() {
+    /**
+     * Close the history file.
+     */
+    public void closeFile() {
         treeIO.closeFile();
     }
 
-    void deleteFile() {
+    /**
+     * Delete the history file.
+     */
+    public void deleteFile() {
         treeIO.deleteFile();
     }
 
@@ -356,12 +417,14 @@ class HistoryTree {
     }
 
     /**
-     * Insert an interval in the tree
+     * Insert an interval in the tree.
      *
      * @param interval
      *            The interval to be inserted
+     * @throws TimeRangeException
+     *             If the start of end time of the interval are invalid
      */
-    void insertInterval(HTInterval interval) throws TimeRangeException {
+    public void insertInterval(HTInterval interval) throws TimeRangeException {
         if (interval.getStartTime() < config.getTreeStart()) {
             throw new TimeRangeException();
         }
@@ -523,7 +586,7 @@ class HistoryTree {
      * @throws ClosedChannelException
      *             If the file channel was closed while we were reading the tree
      */
-    HTNode selectNextChild(CoreNode currentNode, long t) throws ClosedChannelException {
+    public HTNode selectNextChild(CoreNode currentNode, long t) throws ClosedChannelException {
         assert (currentNode.getNbChildren() > 0);
         int potentialNextSeqNb = currentNode.getSequenceNumber();
 
@@ -552,7 +615,12 @@ class HistoryTree {
         return treeIO.readNode(potentialNextSeqNb);
     }
 
-    long getFileSize() {
+    /**
+     * Get the current size of the history file.
+     *
+     * @return The history file size
+     */
+    public long getFileSize() {
         return config.getStateFile().length();
     }
 
@@ -560,10 +628,19 @@ class HistoryTree {
     // Test/debugging methods
     // ------------------------------------------------------------------------
 
-    /* Only used for debugging, shouldn't be externalized */
+    /**
+     * Debugging method to make sure all intervals contained in the given node
+     * have valid start and end times.
+     *
+     * @param zenode
+     *            The node to check
+     * @return True if everything is fine, false if there is at least one
+     *         invalid timestamp (end time < start time, time outside of the
+     *         range of the node, etc.)
+     */
     @SuppressWarnings("nls")
-    boolean checkNodeIntegrity(HTNode zenode) {
-
+    public boolean checkNodeIntegrity(HTNode zenode) {
+        /* Only used for debugging, shouldn't be externalized */
         HTNode otherNode;
         CoreNode node;
         StringBuffer buf = new StringBuffer();
@@ -631,7 +708,11 @@ class HistoryTree {
         return ret;
     }
 
-    void checkIntegrity() {
+    /**
+     * Check the integrity of all the nodes in the tree. Calls
+     * {@link #checkNodeIntegrity} for every node in the tree.
+     */
+    public void checkIntegrity() {
         try {
             for (int i = 0; i < nodeCount; i++) {
                 checkNodeIntegrity(treeIO.readNode(i));
@@ -694,7 +775,7 @@ class HistoryTree {
      * @param printIntervals
      *            Flag to enable full output of the interval information
      */
-    void debugPrintFullTree(PrintWriter writer, boolean printIntervals) {
+    public void debugPrintFullTree(PrintWriter writer, boolean printIntervals) {
         /* Only used for debugging, shouldn't be externalized */
 
         this.preOrderPrint(writer, false, latestBranch.get(0), 0);
index a1723c9e6f65ae7711f9241e1e7ed982650818cd..0ebd140be099448b016826aa148b19f6b2b3d212 100644 (file)
@@ -277,7 +277,7 @@ public class HistoryTreeBackend implements IStateHistoryBackend {
         try {
             for (int seq = 0; seq < sht.getNodeCount(); seq++) {
                 node = sht.readNode(seq);
-                total += node.getNodeUsagePRC();
+                total += node.getNodeUsagePercent();
             }
         } catch (ClosedChannelException e) {
             e.printStackTrace();
This page took 0.038906 seconds and 5 git commands to generate.