org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/internal/tmf/core/statesystem/Attribute.java

   1 /*******************************************************************************
   2  * Copyright (c) 2012, 2014 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  *******************************************************************************/
  12
  13 package org.eclipse.linuxtools.internal.tmf.core.statesystem;
  14
  15 import java.io.PrintWriter;
  16 import java.util.ArrayList;
  17 import java.util.Collections;
  18 import java.util.HashMap;
  19 import java.util.LinkedList;
  20 import java.util.List;
  21 import java.util.Map;
  22
  23 /**
  24  * An Attribute is a "node" in the Attribute Tree. It represents a smallest
  25  * unit of the model which can be in a particular state at a given time.
  26  *
  27  * It is abstract, as different implementations can provide different ways to
  28  * access sub-attributes
  29  *
  30  * @author alexmont
  31  *
  32  */
  33 public abstract class Attribute {
  34
  35     private final Attribute parent;
  36     private final String name;
  37     private final int quark;
  38
  39     /** The list of sub-attributes */
  40     protected final List<Attribute> subAttributes;
  41
  42     /**
  43      * Constructor
  44      *
  45      * @param parent
  46      *            The parent attribute of this one. Can be 'null' to represent
  47      *            this attribute is the root node of the tree.
  48      * @param name
  49      *            Base name of this attribute
  50      * @param quark
  51      *            The integer representation of this attribute
  52      */
  53     public Attribute(Attribute parent, String name, int quark) {
  54         this.parent = parent;
  55         this.quark = quark;
  56         this.name = name;
  57         this.subAttributes = new ArrayList<>();
  58     }
  59
  60     // ------------------------------------------------------------------------
  61     // Accessors
  62     // ------------------------------------------------------------------------
  63
  64     /**
  65      * Get the quark (integer representation) of this attribute.
  66      *
  67      * @return The quark of this attribute
  68      */
  69     public int getQuark() {
  70         return quark;
  71     }
  72
  73     /**
  74      * Get the name of this attribute.
  75      *
  76      * @return The name of this attribute
  77      */
  78     public String getName() {
  79         return name;
  80     }
  81
  82     /**
  83      * Get the list of child attributes below this one. This is a read-only
  84      * view.
  85      *
  86      * @return The list of child attributes.
  87      */
  88     public List<Attribute> getSubAttributes() {
  89         return Collections.unmodifiableList(subAttributes);
  90     }
  91
  92     /**
  93      * Get the matching quark for a given path-of-strings
  94      *
  95      * @param path
  96      *            The path we are looking for, *relative to this node*.
  97      * @return The matching quark, or -1 if that attribute does not exist.
  98      */
  99     public int getSubAttributeQuark(String... path) {
 100         return this.getSubAttributeQuark(path, 0);
 101     }
 102
 103     /**
 104      * Other method to search through the attribute tree, but instead of
 105      * returning the matching quark we return the AttributeTreeNode object
 106      * itself. It can then be used as new "root node" for faster queries on the
 107      * tree.
 108      *
 109      * @param path
 110      *            The target path, *relative to this node*
 111      * @return The Node object matching the last element in the path, or "null"
 112      *         if that attribute does not exist.
 113      */
 114     public Attribute getSubAttributeNode(String... path) {
 115         return this.getSubAttributeNode(path, 0);
 116     }
 117
 118     /**
 119      * "Inner" part of the previous public method, which is used recursively. To
 120      * avoid having to copy sub-arrays to pass down, we just track where we are
 121      * at with the index parameter. It uses getSubAttributeNode(), whose
 122      * implementation is left to the derived classes.
 123      */
 124     private int getSubAttributeQuark(String[] path, int index) {
 125         Attribute targetNode = this.getSubAttributeNode(path, index);
 126         if (targetNode == null) {
 127             return -1;
 128         }
 129         return targetNode.getQuark();
 130     }
 131
 132     /**
 133      * Get the parent attribute of this attribute
 134      *
 135      * @return The parent attribute
 136      */
 137     public Attribute getParentAttribute() {
 138         return this.parent;
 139     }
 140
 141     /**
 142      * Get the parent quark of this attribute
 143      *
 144      * @return The quark of the parent attribute
 145      */
 146     public int getParentAttributeQuark() {
 147         return this.parent.getQuark();
 148     }
 149
 150     /* The methods how to access children are left to derived classes */
 151
 152     /**
 153      * Add a sub-attribute to this attribute
 154      *
 155      * @param newSubAttribute The new attribute to add
 156      */
 157     protected abstract void addSubAttribute(Attribute newSubAttribute);
 158
 159     /**
 160      * Get a sub-attribute from this node's sub-attributes
 161      *
 162      * @param path
 163      *            The *full* path to the attribute
 164      * @param index
 165      *            The index in 'path' where this attribute is located
 166      *            (indicating where to start searching).
 167      * @return The requested attribute
 168      */
 169     protected abstract Attribute getSubAttributeNode(String[] path, int index);
 170
 171     /**
 172      * Return a String array composed of the full (absolute) path representing
 173      * this attribute
 174      *
 175      * @return
 176      */
 177     private String[] getFullAttribute() {
 178         LinkedList<String> list = new LinkedList<>();
 179         Attribute curNode = this;
 180
 181         /* Add recursive parents to the list, but stop at the root node */
 182         while (curNode.parent != null) {
 183             list.addFirst(curNode.getName());
 184             curNode = curNode.parent;
 185         }
 186
 187         return list.toArray(new String[0]);
 188     }
 189
 190     /**
 191      * Return the absolute path of this attribute, as a single slash-separated
 192      * String.
 193      *
 194      * @return The full name of this attribute
 195      */
 196     public String getFullAttributeName() {
 197         String[] array = this.getFullAttribute();
 198         StringBuffer buf = new StringBuffer();
 199
 200         for (int i = 0; i < array.length - 1; i++) {
 201             buf.append(array[i]);
 202             buf.append('/');
 203         }
 204         buf.append(array[array.length - 1]);
 205         return buf.toString();
 206     }
 207
 208     @Override
 209     public String toString() {
 210         return getFullAttributeName() + " (" + quark + ')'; //$NON-NLS-1$
 211     }
 212
 213     private int curDepth;
 214
 215     private void attributeNodeToString(PrintWriter writer, Attribute currentNode) {
 216         int j;
 217
 218         writer.println(currentNode.getName() + " (" + currentNode.quark + ')'); //$NON-NLS-1$
 219         curDepth++;
 220
 221         for (Attribute nextNode : currentNode.getSubAttributes()) {
 222             /* Skip printing 'null' entries */
 223             if (nextNode == null) {
 224                 continue;
 225             }
 226             for (j = 0; j < curDepth - 1; j++) {
 227                 writer.print("  "); //$NON-NLS-1$
 228             }
 229             writer.print("  "); //$NON-NLS-1$
 230             attributeNodeToString(writer, nextNode);
 231         }
 232         curDepth--;
 233         return;
 234     }
 235
 236     /**
 237      * Debugging method to print the contents of this attribute
 238      *
 239      * @param writer
 240      *            PrintWriter where to write the information
 241      */
 242     public void debugPrint(PrintWriter writer) {
 243         /* Only used for debugging, shouldn't be externalized */
 244         writer.println("------------------------------"); //$NON-NLS-1$
 245         writer.println("Attribute tree: (quark)\n"); //$NON-NLS-1$
 246         curDepth = 0;
 247         attributeNodeToString(writer, this);
 248         writer.print('\n');
 249     }
 250 }
 251
 252 /**
 253  * This is the basic implementation, where sub-attributes names can be composed
 254  * of any alphanumeric characters, and are stored as Strings. A HashMap is used
 255  * to access them.
 256  *
 257  * @author alexmont
 258  *
 259  */
 260 final class AlphaNumAttribute extends Attribute {
 261
 262     private final Map<String, Integer> subAttributesMap;
 263
 264     public AlphaNumAttribute(Attribute parent, String name, int quark) {
 265         super(parent, name, quark);
 266         this.subAttributesMap = new HashMap<>();
 267     }
 268
 269     @Override
 270     protected synchronized void addSubAttribute(Attribute newSubAttribute) {
 271         assert (newSubAttribute != null);
 272         assert (newSubAttribute.getName() != null);
 273         /* This should catch buggy state changing statements */
 274         assert (!newSubAttribute.getName().equals(this.getName()));
 275
 276         subAttributesMap.put(newSubAttribute.getName(), subAttributes.size());
 277         subAttributes.add(newSubAttribute);
 278     }
 279
 280     @Override
 281     protected synchronized Attribute getSubAttributeNode(String[] path,
 282             int index) {
 283         Integer indexOfNextNode = subAttributesMap.get(path[index]);
 284         Attribute nextNode;
 285
 286         if (indexOfNextNode == null) {
 287             /* We don't have the expected child => the attribute does not exist */
 288             return null;
 289         }
 290         if (index == path.length - 1) {
 291             /* It's our job to process this request */
 292             return subAttributes.get(indexOfNextNode);
 293         }
 294
 295         nextNode = subAttributes.get(indexOfNextNode);
 296         return nextNode.getSubAttributeNode(path, index + 1);
 297     }
 298 }