statesystem/org.eclipse.tracecompass.statesystem.core/src/org/eclipse/tracecompass/internal/statesystem/core/backend/historytree/IHistoryTree.java

   1 /*******************************************************************************
   2  * Copyright (c) 2010, 2016 Ericsson, École Polytechnique de Montréal, and others
   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
  10 package org.eclipse.tracecompass.internal.statesystem.core.backend.historytree;
  11
  12 import java.io.File;
  13 import java.io.FileInputStream;
  14 import java.nio.channels.ClosedChannelException;
  15 import java.util.Collection;
  16
  17 import org.eclipse.tracecompass.statesystem.core.exceptions.TimeRangeException;
  18
  19 /**
  20  * Meta-container for the History Tree. This structure contains all the
  21  * high-level data relevant to the tree.
  22  *
  23  * @author Alexandre Montplaisir
  24  */
  25 public interface IHistoryTree {
  26
  27     /**
  28      * Size of the "tree header" in the tree-file The nodes will use this offset
  29      * to know where they should be in the file. This should always be a
  30      * multiple of 4K.
  31      */
  32     int TREE_HEADER_SIZE = 4096;
  33
  34     /**
  35      * "Save" the tree to disk. This method will cause the treeIO object to
  36      * commit all nodes to disk and then return the RandomAccessFile descriptor
  37      * so the Tree object can save its configuration into the header of the
  38      * file.
  39      *
  40      * @param requestedEndTime
  41      *            The greatest timestamp present in the history tree
  42      */
  43     void closeTree(long requestedEndTime);
  44
  45     // ------------------------------------------------------------------------
  46     // Accessors
  47     // ------------------------------------------------------------------------
  48
  49     /**
  50      * Get the start time of this tree.
  51      *
  52      * @return The start time
  53      */
  54     long getTreeStart();
  55
  56     /**
  57      * Get the current end time of this tree.
  58      *
  59      * @return The end time
  60      */
  61     long getTreeEnd();
  62
  63     /**
  64      * Get the number of nodes in this tree.
  65      *
  66      * @return The number of nodes
  67      */
  68     int getNodeCount();
  69
  70     /**
  71      * Get the current root node of this tree
  72      *
  73      * @return The root node
  74      */
  75     HTNode getRootNode();
  76
  77     // ------------------------------------------------------------------------
  78     // HT_IO interface
  79     // ------------------------------------------------------------------------
  80
  81     /**
  82      * Return the FileInputStream reader with which we will read an attribute
  83      * tree (it will be sought to the correct position).
  84      *
  85      * @return The FileInputStream indicating the file and position from which
  86      *         the attribute tree can be read.
  87      */
  88     FileInputStream supplyATReader();
  89
  90     /**
  91      * Return the file to which we will write the attribute tree.
  92      *
  93      * @return The file to which we will write the attribute tree
  94      */
  95     File supplyATWriterFile();
  96
  97     /**
  98      * Return the position in the file (given by {@link #supplyATWriterFile})
  99      * where to start writing the attribute tree.
 100      *
 101      * @return The position in the file where to start writing
 102      */
 103     long supplyATWriterFilePos();
 104
 105     /**
 106      * Read a node from the tree.
 107      *
 108      * @param seqNumber
 109      *            The sequence number of the node to read
 110      * @return The node
 111      * @throws ClosedChannelException
 112      *             If the tree IO is unavailable
 113      */
 114     HTNode readNode(int seqNumber) throws ClosedChannelException;
 115
 116     /**
 117      * Write a node object to the history file.
 118      *
 119      * @param node
 120      *            The node to write to disk
 121      */
 122     void writeNode(HTNode node);
 123
 124     /**
 125      * Close the history file.
 126      */
 127     void closeFile();
 128
 129     /**
 130      * Delete the history file.
 131      */
 132     void deleteFile();
 133
 134     // ------------------------------------------------------------------------
 135     // Operations
 136     // ------------------------------------------------------------------------
 137
 138     /**
 139      * Insert an interval in the tree.
 140      *
 141      * @param interval
 142      *            The interval to be inserted
 143      * @throws TimeRangeException
 144      *             If the start of end time of the interval are invalid
 145      */
 146     void insertInterval(HTInterval interval) throws TimeRangeException;
 147
 148     /**
 149      * Inner method to select the next children of the current node intersecting
 150      * the given timestamp. Useful for moving down the tree following one
 151      * branch.
 152      *
 153      * @param currentNode
 154      *            The node on which the request is made
 155      * @param t
 156      *            The timestamp to choose which child is the next one
 157      * @return The child nodes intersecting t
 158      * @throws ClosedChannelException
 159      *             If the file channel was closed while we were reading the tree
 160      */
 161     Collection<HTNode> selectNextChildren(CoreNode currentNode, long t) throws ClosedChannelException;
 162
 163     /**
 164      * Get the current size of the history file.
 165      *
 166      * @return The history file size
 167      */
 168     long getFileSize();
 169
 170 }