statesystem/org.eclipse.tracecompass.datastore.core/src/org/eclipse/tracecompass/internal/provisional/datastore/core/historytree/IHTNode.java

   1 /*******************************************************************************
   2  * Copyright (c) 2017 École Polytechnique de Montréal
   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.provisional.datastore.core.historytree;
  11
  12 import java.io.IOException;
  13 import java.nio.channels.FileChannel;
  14 import java.util.Collection;
  15 import java.util.Collections;
  16 import java.util.function.Predicate;
  17
  18 import org.eclipse.jdt.annotation.Nullable;
  19 import org.eclipse.tracecompass.internal.provisional.datastore.core.condition.TimeRangeCondition;
  20 import org.eclipse.tracecompass.internal.provisional.datastore.core.exceptions.RangeException;
  21 import org.eclipse.tracecompass.internal.provisional.datastore.core.interval.IHTInterval;
  22
  23 /**
  24  * Interface for history tree nodes
  25  *
  26  * @author Geneviève Bastien
  27  * @param <E>
  28  *            The type of objects that will be saved in the tree
  29  */
  30 public interface IHTNode<E extends IHTInterval> {
  31
  32     /**
  33      * The type of node
  34      */
  35     public enum NodeType {
  36         /**
  37          * Core node, which is a "front" node, at any level of the tree except
  38          * the bottom-most one. It has children, and may have extensions.
  39          */
  40         CORE((byte) 1),
  41         /**
  42          * Leaf node, which is a node at the last bottom level of the tree. It
  43          * cannot have any children or extensions.
  44          */
  45         LEAF((byte) 2);
  46
  47         private final byte fByte;
  48
  49         NodeType(byte rep) {
  50             fByte = rep;
  51         }
  52
  53         /**
  54          * Determine a node type by reading a serialized byte.
  55          *
  56          * @param rep
  57          *            The byte representation of the node type
  58          * @return The corresponding NodeType
  59          */
  60         public static NodeType fromByte(byte rep) {
  61             switch (rep) {
  62             case 1:
  63                 return CORE;
  64             case 2:
  65                 return LEAF;
  66             default:
  67                 throw new IllegalArgumentException("The NodeType byte " + rep + " is not a valid type"); //$NON-NLS-1$ //$NON-NLS-2$
  68             }
  69         }
  70
  71         /**
  72          * Get the byte representation of this node type. It can then be read
  73          * with {@link #fromByte}.
  74          *
  75          * @return The byte matching this node type
  76          */
  77         public byte toByte() {
  78             return fByte;
  79         }
  80     }
  81
  82     /**
  83      * Write this node to the given file channel.
  84      *
  85      * @param fc
  86      *            The file channel to write to (should be sought to be correct
  87      *            position)
  88      * @throws IOException
  89      *             If there was an error writing
  90      */
  91     void writeSelf(FileChannel fc) throws IOException;
  92
  93     /**
  94      * Get the start time of this node.
  95      *
  96      * @return The start time of this node
  97      */
  98     long getNodeStart();
  99
 100     /**
 101      * Get the end time of this node. Will return {@link Long#MAX_VALUE} if the
 102      * node is not yet written to disk, as the real end time is not yet known.
 103      *
 104      * @return The end time of this node.
 105      */
 106     long getNodeEnd();
 107
 108     /**
 109      * Get the sequence number of this node.
 110      *
 111      * @return The sequence number of this node
 112      */
 113     int getSequenceNumber();
 114
 115     /**
 116      * Get the sequence number of this node's parent.
 117      *
 118      * @return The parent sequence number
 119      */
 120     int getParentSequenceNumber();
 121
 122     /**
 123      * Change this node's parent. Used when we create a new root node for
 124      * example.
 125      *
 126      * @param newParent
 127      *            The sequence number of the node that is the new parent
 128      */
 129     void setParentSequenceNumber(int newParent);
 130
 131     /**
 132      * Return if this node is "done" (full and written to disk).
 133      *
 134      * @return If this node is done or not
 135      */
 136     boolean isOnDisk();
 137
 138     /**
 139      * Add an interval to this node. The caller of this method must make sure that
 140      * there is enough space on this node to add this object. Also, it is the
 141      * responsibility of the caller to make sure that the element to add is
 142      * within the boundary of this node. No check on start and end is expected
 143      * to be done in this method.
 144      *
 145      * @param newInterval
 146      *            Interval to add to this node
 147      */
 148     void add(E newInterval);
 149
 150     /**
 151      * We've received word from the containerTree that newest nodes now exist to
 152      * our right. (Puts isDone = true and sets the endtime)
 153      *
 154      * @param endtime
 155      *            The nodeEnd time that the node will have
 156      */
 157     void closeThisNode(long endtime);
 158
 159     /**
 160      * Retrieve the intervals inside this node that match the given conditions.
 161      *
 162      * @param timeCondition
 163      *            The time-based RangeCondition
 164      * @param extraPredicate
 165      *            Extra predicate to run on the elements. Only those also
 166      *            matching this predicate will be returned.
 167      * @return Iterable of the elements in this node matching the condtions
 168      */
 169     Iterable<E> getMatchingIntervals(TimeRangeCondition timeCondition,
 170             Predicate<E> extraPredicate);
 171
 172     /**
 173      * Retrieve an interval inside this node that matches the given conditions.
 174      *
 175      * @param timeCondition
 176      *            The time-based RangeCondition
 177      * @param extraPredicate
 178      *            Extra predicate to run on the elements. Only intervals also
 179      *            matching this predicate will be returned.
 180      * @return An interval matching the conditions or <code>null</code> if no
 181      *         interval was found
 182      */
 183     @Nullable E getMatchingInterval(TimeRangeCondition timeCondition,
 184             Predicate<E> extraPredicate);
 185
 186     /**
 187      * Return the total header size of this node (will depend on the node type).
 188      *
 189      * @return The total header size
 190      */
 191     int getTotalHeaderSize();
 192
 193     /**
 194      * Returns the free space left in the node to write objects
 195      *
 196      * @return The amount of free space in the node (in bytes)
 197      */
 198     int getNodeFreeSpace();
 199
 200     /**
 201      * Returns the current space utilization of this node, as a percentage.
 202      * (used space / total usable space, which excludes the header)
 203      *
 204      * @return The percentage (value between 0 and 100) of space utilization in
 205      *         this node.
 206      */
 207     long getNodeUsagePercent();
 208
 209     /**
 210      * Get the type of this node
 211      *
 212      * @return The node type
 213      */
 214     NodeType getNodeType();
 215
 216     /**
 217      * Return whether this node has elements in it or is empty
 218      *
 219      * @return <code>true</code> if the node is empty
 220      */
 221     boolean isEmpty();
 222
 223     // ---------------------------------------
 224     // Methods for nodes with children. Leaf nodes can use these default methods
 225     // ---------------------------------------
 226
 227     /**
 228      * Return the number of child nodes this node has.
 229      *
 230      * @return The number of child nodes
 231      */
 232     default int getNbChildren() {
 233         return 0;
 234     }
 235
 236     /**
 237      * Get the child node corresponding to the specified index. It will throw an
 238      * {@link IndexOutOfBoundsException} if there is no children at this index.
 239      *
 240      * @param index
 241      *            The index of the child to lookup
 242      * @return The child node
 243      */
 244     default int getChild(int index) {
 245         throw new IndexOutOfBoundsException("This node does not have any children"); //$NON-NLS-1$
 246     }
 247
 248     /**
 249      * Get the latest (right-most) child node of this node. This applies only if
 250      * the node is allowed to have children, ie is a {@link NodeType#CORE} node,
 251      * otherwise this method is not supported.
 252      *
 253      * @return The latest child node
 254      */
 255     default int getLatestChild() {
 256         throw new UnsupportedOperationException("This node does not support children"); //$NON-NLS-1$
 257     }
 258
 259     /**
 260      * Tell this node that it has a new child. This applies only if the node is
 261      * allowed to have children, ie is a {@link NodeType#CORE} node, otherwise
 262      * this method is not supported.
 263      *
 264      * @param childNode
 265      *            The new child node to add to this one
 266      */
 267     default void linkNewChild(IHTNode<E> childNode) {
 268         throw new UnsupportedOperationException("This node does not support children"); //$NON-NLS-1$
 269     }
 270
 271     /**
 272      * Method to select the sequence numbers for the children of the current
 273      * node that intersect the given timestamp. Useful when navigating the tree.
 274      *
 275      * @param timeCondition
 276      *            The time-based range condition to choose which child is the
 277      *            next one
 278      * @return Collection of sequence numbers of the child nodes that intersect
 279      *         the time condition, non-null empty collection if this is a Leaf
 280      *         Node
 281      * @throws RangeException
 282      *             If t is out of the node's range
 283      */
 284     default Collection<Integer> selectNextChildren(TimeRangeCondition timeCondition) {
 285         return Collections.emptyList();
 286     }
 287
 288 }