statesystem/org.eclipse.tracecompass.statesystem.core/src/org/eclipse/tracecompass/internal/statesystem/core/AttributeTree.java

   1 /*******************************************************************************
   2  * Copyright (c) 2012, 2016 Ericsson
   3  * Copyright (c) 2010, 2011 École Polytechnique de Montréal
   4  * Copyright (c) 2010, 2011 Alexandre Montplaisir <alexandre.montplaisir@gmail.com>
   5  *
   6  * All rights reserved. This program and the accompanying materials are
   7  * made available under the terms of the Eclipse Public License v1.0 which
   8  * accompanies this distribution, and is available at
   9  * http://www.eclipse.org/legal/epl-v10.html
  10  *
  11  * Contributors:
  12  *   Alexandre Montplaisir - Initial API and implementation
  13  *   Patrick Tasse - Add message to exceptions
  14  *******************************************************************************/
  15
  16 package org.eclipse.tracecompass.internal.statesystem.core;
  17
  18 import static org.eclipse.tracecompass.common.core.NonNullUtils.checkNotNull;
  19 import static org.eclipse.tracecompass.statesystem.core.ITmfStateSystem.INVALID_ATTRIBUTE;
  20 import static org.eclipse.tracecompass.statesystem.core.ITmfStateSystem.ROOT_ATTRIBUTE;
  21
  22 import java.io.BufferedInputStream;
  23 import java.io.File;
  24 import java.io.FileInputStream;
  25 import java.io.FileOutputStream;
  26 import java.io.IOException;
  27 import java.io.ObjectInputStream;
  28 import java.io.ObjectOutputStream;
  29 import java.io.PrintWriter;
  30 import java.nio.channels.FileChannel;
  31 import java.util.ArrayList;
  32 import java.util.List;
  33
  34 import org.eclipse.jdt.annotation.NonNull;
  35 import org.eclipse.tracecompass.statesystem.core.ITmfStateSystem;
  36
  37 /**
  38  * The Attribute Tree is the /proc-like filesystem used to organize attributes.
  39  * Each node of this tree is both like a file and a directory in the
  40  * "file system".
  41  *
  42  * @author alexmont
  43  *
  44  */
  45 public final class AttributeTree {
  46
  47     /* "Magic number" for attribute tree files or file sections */
  48     private static final int ATTRIB_TREE_MAGIC_NUMBER = 0x06EC3671;
  49
  50     private final StateSystem ss;
  51     private final List<Attribute> attributeList;
  52     private final Attribute attributeTreeRoot;
  53
  54     /**
  55      * Standard constructor, create a new empty Attribute Tree
  56      *
  57      * @param ss
  58      *            The StateSystem to which this AT is attached
  59      */
  60     public AttributeTree(StateSystem ss) {
  61         this.ss = ss;
  62         this.attributeList = new ArrayList<>();
  63         this.attributeTreeRoot = new Attribute(null, "root", ROOT_ATTRIBUTE); //$NON-NLS-1$
  64     }
  65
  66     /**
  67      * "Existing file" constructor. Builds an attribute tree from a
  68      * "mapping file" or mapping section previously saved somewhere.
  69      *
  70      * @param ss
  71      *            StateSystem to which this AT is attached
  72      * @param fis
  73      *            File stream where to read the AT information. Make sure it's
  74      *            sought at the right place!
  75      * @throws IOException
  76      *             If there is a problem reading from the file stream
  77      */
  78     public AttributeTree(StateSystem ss, FileInputStream fis) throws IOException {
  79         this(ss);
  80         ObjectInputStream ois = new ObjectInputStream(new BufferedInputStream(fis));
  81
  82         /* Read the header of the Attribute Tree file (or file section) */
  83         int res = ois.readInt(); /* Magic number */
  84         if (res != ATTRIB_TREE_MAGIC_NUMBER) {
  85             throw new IOException("The attribute tree file section is either invalid or corrupted."); //$NON-NLS-1$
  86         }
  87
  88
  89         ArrayList<String[]> attribList;
  90         try {
  91             @SuppressWarnings("unchecked")
  92             ArrayList<String[]> list = (ArrayList<String[]>) ois.readObject();
  93             attribList = list;
  94         } catch (ClassNotFoundException e) {
  95             throw new IOException("Unrecognizable attribute list"); //$NON-NLS-1$
  96         }
  97
  98         /*
  99          * Now we have 'list', the ArrayList of String arrays representing all
 100          * the attributes. Simply create attributes the normal way from them.
 101          */
 102         for (String[] attrib : attribList) {
 103             this.getQuarkAndAdd(ROOT_ATTRIBUTE, attrib);
 104         }
 105     }
 106
 107     /**
 108      * Tell the Attribute Tree to write itself somewhere in a file.
 109      *
 110      * @param file
 111      *            The file to write to
 112      * @param pos
 113      *            The position (in bytes) in the file where to write
 114      */
 115     public synchronized void writeSelf(File file, long pos) {
 116         try (FileOutputStream fos = new FileOutputStream(file, true);
 117                 FileChannel fc = fos.getChannel();) {
 118             fc.position(pos);
 119             try (ObjectOutputStream oos = new ObjectOutputStream(fos)) {
 120
 121                 /* Write the almost-magic number */
 122                 oos.writeInt(ATTRIB_TREE_MAGIC_NUMBER);
 123
 124                 /* Compute the serialized list of attributes and write it */
 125                 List<String[]> list = new ArrayList<>(attributeList.size());
 126                 for (Attribute entry : this.attributeList) {
 127                     list.add(entry.getFullAttribute());
 128                 }
 129                 oos.writeObject(list);
 130             }
 131         } catch (IOException e) {
 132             e.printStackTrace();
 133         }
 134
 135     }
 136
 137     /**
 138      * Return the number of attributes this system as seen so far. Note that
 139      * this also equals the integer value (quark) the next added attribute will
 140      * have.
 141      *
 142      * @return The current number of attributes in the tree
 143      */
 144     public synchronized int getNbAttributes() {
 145         return attributeList.size();
 146     }
 147
 148     /**
 149      * Get the quark for a given attribute path. No new attribute will be
 150      * created : if the specified path does not exist, return
 151      * {@link ITmfStateSystem#INVALID_ATTRIBUTE}.
 152      *
 153      * @param startingNodeQuark
 154      *            The quark of the attribute from which relative queries will
 155      *            start. Use {@link ITmfStateSystem#ROOT_ATTRIBUTE} to start at
 156      *            the root node.
 157      * @param subPath
 158      *            The path to the attribute, relative to the starting node.
 159      * @return The quark of the specified attribute, or
 160      *         {@link ITmfStateSystem#INVALID_ATTRIBUTE} if that attribute does
 161      *         not exist.
 162      * @throws IndexOutOfBoundsException
 163      *             If the starting node quark is out of range
 164      */
 165     public synchronized int getQuarkDontAdd(int startingNodeQuark, String... subPath) {
 166         Attribute prevNode;
 167
 168         /* If subPath is empty, simply return the starting quark */
 169         if (subPath == null || subPath.length == 0) {
 170             return startingNodeQuark;
 171         }
 172
 173         /* Get the "starting node" */
 174         if (startingNodeQuark == ROOT_ATTRIBUTE) {
 175             prevNode = attributeTreeRoot;
 176         } else {
 177             prevNode = attributeList.get(startingNodeQuark);
 178         }
 179
 180         return prevNode.getSubAttributeQuark(subPath);
 181     }
 182
 183     /**
 184      * Get the quark of a given attribute path. If that specified path does not
 185      * exist, it will be created (and the quark that was just created will be
 186      * returned).
 187      *
 188      * @param startingNodeQuark
 189      *            The quark of the attribute from which relative queries will
 190      *            start. Use {@link ITmfStateSystem#ROOT_ATTRIBUTE} to start at
 191      *            the root node.
 192      * @param subPath
 193      *            The path to the attribute, relative to the starting node.
 194      * @return The quark of the attribute represented by the path
 195      * @throws IndexOutOfBoundsException
 196      *             If the starting node quark is out of range
 197      */
 198     public synchronized int getQuarkAndAdd(int startingNodeQuark, String... subPath) {
 199         // FIXME synchronized here is probably quite costly... maybe only locking
 200         // the "for" would be enough?
 201
 202         Attribute nextNode = null;
 203         Attribute prevNode;
 204
 205         /* Get the "starting node" */
 206         if (startingNodeQuark == ROOT_ATTRIBUTE) {
 207             prevNode = attributeTreeRoot;
 208         } else {
 209             prevNode = attributeList.get(startingNodeQuark);
 210         }
 211
 212         int knownQuark = prevNode.getSubAttributeQuark(subPath);
 213         if (knownQuark == INVALID_ATTRIBUTE) {
 214             /*
 215              * The attribute was not in the table previously, and we want to add
 216              * it
 217              */
 218             for (String curDirectory : subPath) {
 219                 nextNode = prevNode.getSubAttributeNode(curDirectory);
 220                 if (nextNode == null) {
 221                     /* This is where we need to start adding */
 222                     nextNode = new Attribute(prevNode, checkNotNull(curDirectory), attributeList.size());
 223                     prevNode.addSubAttribute(nextNode);
 224                     attributeList.add(nextNode);
 225                     ss.addEmptyAttribute();
 226                 }
 227                 prevNode = nextNode;
 228             }
 229             return attributeList.size() - 1;
 230         }
 231         /*
 232          * The attribute was already existing, return the quark of that
 233          * attribute
 234          */
 235         return knownQuark;
 236     }
 237
 238     /**
 239      * Returns the sub-attributes of the quark passed in parameter
 240      *
 241      * @param attributeQuark
 242      *            The quark of the attribute to print the sub-attributes of.
 243      * @param recursive
 244      *            Should the query be recursive or not? If false, only children
 245      *            one level deep will be returned. If true, all descendants will
 246      *            be returned (depth-first search)
 247      * @return The list of quarks representing the children attributes
 248      * @throws IndexOutOfBoundsException
 249      *             If the attribute quark is out of range
 250      */
 251     public synchronized @NonNull List<@NonNull Integer> getSubAttributes(int attributeQuark, boolean recursive) {
 252         List<@NonNull Integer> listOfChildren = new ArrayList<>();
 253         Attribute startingAttribute;
 254
 255         /* Set up the node from which we'll start the search */
 256         if (attributeQuark == ROOT_ATTRIBUTE) {
 257             startingAttribute = attributeTreeRoot;
 258         } else {
 259             startingAttribute = attributeList.get(attributeQuark);
 260         }
 261
 262         /* Iterate through the sub-attributes and add them to the list */
 263         addSubAttributes(listOfChildren, startingAttribute, recursive);
 264
 265         return listOfChildren;
 266     }
 267
 268     /**
 269      * Returns the parent quark of the attribute. The root attribute has no
 270      * parent and will return {@link ITmfStateSystem#ROOT_ATTRIBUTE}.
 271      *
 272      * @param quark
 273      *            The quark of the attribute
 274      * @return Quark of the parent attribute or
 275      *         {@link ITmfStateSystem#ROOT_ATTRIBUTE} for the root attribute
 276      * @throws IndexOutOfBoundsException
 277      *             If the quark is out of range
 278      */
 279     public synchronized int getParentAttributeQuark(int quark) {
 280         if (quark == ROOT_ATTRIBUTE) {
 281             return quark;
 282         }
 283         return attributeList.get(quark).getParentAttributeQuark();
 284     }
 285
 286     private void addSubAttributes(List<Integer> list, Attribute curAttribute,
 287             boolean recursive) {
 288         for (Attribute childNode : curAttribute.getSubAttributes()) {
 289             list.add(childNode.getQuark());
 290             if (recursive) {
 291                 addSubAttributes(list, childNode, true);
 292             }
 293         }
 294     }
 295
 296     /**
 297      * Get then base name of an attribute specified by a quark.
 298      *
 299      * @param quark
 300      *            The quark of the attribute
 301      * @return The (base) name of the attribute
 302      * @throws IndexOutOfBoundsException
 303      *             If the quark is out of range
 304      */
 305     public synchronized @NonNull String getAttributeName(int quark) {
 306         return attributeList.get(quark).getName();
 307     }
 308
 309     /**
 310      * Get the full path name of an attribute specified by a quark.
 311      *
 312      * @param quark
 313      *            The quark of the attribute
 314      * @return The full path name of the attribute
 315      * @throws IndexOutOfBoundsException
 316      *             If the quark is out of range
 317      */
 318     public synchronized @NonNull String getFullAttributeName(int quark) {
 319         return attributeList.get(quark).getFullAttributeName();
 320     }
 321
 322     /**
 323      * Get the full path name (as an array of path elements) of an attribute
 324      * specified by a quark.
 325      *
 326      * @param quark
 327      *            The quark of the attribute
 328      * @return The path elements of the full path
 329      * @throws IndexOutOfBoundsException
 330      *             If the quark is out of range
 331      */
 332     public synchronized String @NonNull [] getFullAttributePathArray(int quark) {
 333         return attributeList.get(quark).getFullAttribute();
 334     }
 335
 336     /**
 337      * Debug-print all the attributes in the tree.
 338      *
 339      * @param writer
 340      *            The writer where to print the output
 341      */
 342     public synchronized void debugPrint(PrintWriter writer) {
 343         attributeTreeRoot.debugPrint(writer);
 344     }
 345
 346 }