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