org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/statesystem/ITmfStateSystemBuilder.java

   1 /*******************************************************************************
   2  * Copyright (c) 2012, 2014 Ericsson
   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  * Contributors:
  10  *   Alexandre Montplaisir - Initial API
  11  ******************************************************************************/
  12
  13 package org.eclipse.linuxtools.tmf.core.statesystem;
  14
  15 import org.eclipse.linuxtools.tmf.core.exceptions.AttributeNotFoundException;
  16 import org.eclipse.linuxtools.tmf.core.exceptions.StateValueTypeException;
  17 import org.eclipse.linuxtools.tmf.core.exceptions.TimeRangeException;
  18 import org.eclipse.linuxtools.tmf.core.statevalue.ITmfStateValue;
  19
  20 /**
  21  * This is the external interface to build or modify an existing state history.
  22  *
  23  * It extends ITmfStateSystem, so you can still use it for reading the history,
  24  * but it also provides write-access to it with the quark-creating and
  25  * state-change insertion methods.
  26  *
  27  * This should only be used by classes that need to build or modify the state
  28  * history. Views, etc. (who will only be reading from it) should use the
  29  * ITmfStateSystem interface instead.
  30  *
  31  * @author Alexandre Montplaisir
  32  * @version 2.0
  33  * @since 2.0
  34  */
  35 public interface ITmfStateSystemBuilder extends ITmfStateSystem {
  36
  37     /**
  38      * @name Read/write quark-getting methods
  39      */
  40
  41     /**
  42      * Basic quark-retrieving method. Pass an attribute in parameter as an array
  43      * of strings, the matching quark will be returned.
  44      *
  45      * This version WILL create new attributes: if the attribute passed in
  46      * parameter is new in the system, it will be added and its new quark will
  47      * be returned.
  48      *
  49      * @param attribute
  50      *            Attribute given as its full path in the Attribute Tree
  51      * @return The quark of the attribute (which either existed or just got
  52      *         created)
  53      */
  54     int getQuarkAbsoluteAndAdd(String... attribute);
  55
  56     /**
  57      * "Relative path" quark-getting method. Instead of specifying a full path,
  58      * if you know the path is relative to another attribute for which you
  59      * already have the quark, use this for better performance.
  60      *
  61      * This is useful for cases where a lot of modifications or queries will
  62      * originate from the same branch of the attribute tree : the common part of
  63      * the path won't have to be re-hashed for every access.
  64      *
  65      * This version WILL create new attributes: if the attribute passed in
  66      * parameter is new in the system, it will be added and its new quark will
  67      * be returned.
  68      *
  69      * @param startingNodeQuark
  70      *            The quark of the attribute from which 'subPath' originates.
  71      * @param subPath
  72      *            "Rest" of the path to get to the final attribute
  73      * @return The matching quark, either if it's new of just got created.
  74      */
  75     int getQuarkRelativeAndAdd(int startingNodeQuark, String... subPath);
  76
  77     /**
  78      * @name State-changing methods
  79      */
  80
  81     /**
  82      * Modify a current "ongoing" state (instead of inserting a state change,
  83      * like modifyAttribute() and others).
  84      *
  85      * This can be used to update the value of a previous state change, for
  86      * example when we get information at the end of the state and not at the
  87      * beginning. (return values of system calls, etc.)
  88      *
  89      * Note that past states can only be modified while they are still in
  90      * memory, so only the "current state" can be updated. Once they get
  91      * committed to disk (by inserting a new state change) it becomes too late.
  92      *
  93      * @param newValue
  94      *            The new value that will overwrite the "current" one.
  95      * @param attributeQuark
  96      *            For which attribute in the system
  97      * @throws AttributeNotFoundException
  98      *             If the requested attribute is invalid
  99      */
 100     void updateOngoingState(ITmfStateValue newValue, int attributeQuark)
 101             throws AttributeNotFoundException;
 102
 103     /**
 104      * Basic attribute modification method, we simply specify a new value, for a
 105      * given attribute, effective at the given timestamp.
 106      *
 107      * @param t
 108      *            Timestamp of the state change
 109      * @param value
 110      *            The State Value we want to assign to the attribute
 111      * @param attributeQuark
 112      *            Integer value of the quark corresponding to the attribute we
 113      *            want to modify
 114      * @throws TimeRangeException
 115      *             If the requested time is outside of the trace's range
 116      * @throws AttributeNotFoundException
 117      *             If the requested attribute quark is invalid
 118      * @throws StateValueTypeException
 119      *             If the inserted state value's type does not match what is
 120      *             already assigned to this attribute.
 121      */
 122     void modifyAttribute(long t, ITmfStateValue value, int attributeQuark)
 123             throws AttributeNotFoundException, StateValueTypeException;
 124
 125     /**
 126      * Increment attribute method. Reads the current value of a given integer
 127      * attribute (this value is right now in the Transient State), and increment
 128      * it by 1. Useful for statistics.
 129      *
 130      * @param t
 131      *            Timestamp of the state change
 132      * @param attributeQuark
 133      *            Attribute to increment. If it doesn't exist it will be added,
 134      *            with a new value of 1.
 135      * @throws StateValueTypeException
 136      *             If the attribute already exists but is not of type Integer
 137      * @throws TimeRangeException
 138      *             If the given timestamp is invalid
 139      * @throws AttributeNotFoundException
 140      *             If the quark is invalid
 141      */
 142     void incrementAttribute(long t, int attributeQuark)
 143             throws AttributeNotFoundException, StateValueTypeException;
 144
 145     /**
 146      * "Push" helper method. This uses the given integer attribute as a stack:
 147      * The value of that attribute will represent the stack depth (always >= 1).
 148      * Sub-attributes will be created, their base-name will be the position in
 149      * the stack (1, 2, etc.) and their value will be the state value 'value'
 150      * that was pushed to this position.
 151      *
 152      * @param t
 153      *            Timestamp of the state change
 154      * @param value
 155      *            State value to assign to this stack position.
 156      * @param attributeQuark
 157      *            The base attribute to use as a stack. If it does not exist if
 158      *            will be created (with depth = 1)
 159      * @throws TimeRangeException
 160      *             If the requested timestamp is invalid
 161      * @throws AttributeNotFoundException
 162      *             If the attribute is invalid
 163      * @throws StateValueTypeException
 164      *             If the attribute 'attributeQuark' already exists, but is not
 165      *             of integer type.
 166      */
 167     void pushAttribute(long t, ITmfStateValue value, int attributeQuark)
 168             throws AttributeNotFoundException, StateValueTypeException;
 169
 170     /**
 171      * Antagonist of the pushAttribute(), pops the top-most attribute on the
 172      * stack-attribute. If this brings it back to depth = 0, the attribute is
 173      * kept with depth = 0. If the value is already 0, or if the attribute
 174      * doesn't exist, nothing is done.
 175      *
 176      * @param t
 177      *            Timestamp of the state change
 178      * @param attributeQuark
 179      *            Quark of the stack-attribute to pop
 180      * @return The state value that was popped, or 'null' if nothing was
 181      *         actually removed from the stack.
 182      * @throws AttributeNotFoundException
 183      *             If the attribute is invalid
 184      * @throws TimeRangeException
 185      *             If the timestamp is invalid
 186      * @throws StateValueTypeException
 187      *             If the target attribute already exists, but its state value
 188      *             type is invalid (not an integer)
 189      * @since 2.0
 190      */
 191     ITmfStateValue popAttribute(long t, int attributeQuark)
 192             throws AttributeNotFoundException, StateValueTypeException;
 193
 194     /**
 195      * Remove attribute method. Similar to the above modify- methods, with value
 196      * = 0 / null, except we will also "nullify" all the sub-contents of the
 197      * requested path (a bit like "rm -rf")
 198      *
 199      * @param t
 200      *            Timestamp of the state change
 201      * @param attributeQuark
 202      *            Attribute to remove
 203      * @throws TimeRangeException
 204      *             If the timestamp is invalid
 205      * @throws AttributeNotFoundException
 206      *             If the quark is invalid
 207      */
 208     void removeAttribute(long t, int attributeQuark)
 209             throws AttributeNotFoundException;
 210
 211     /**
 212      * Method to close off the History Provider. This happens for example when
 213      * we are done reading an off-line trace. First we close the TransientState,
 214      * commit it to the Provider, mark it as inactive, then we write the
 215      * Attribute Tree somewhere so we can reopen it later.
 216      *
 217      * @param endTime
 218      *            The requested End Time of the history, since it could be
 219      *            bigger than the timestamp of the last event or state change we
 220      *            have seen. All "ongoing" states will be extended until this
 221      *            'endTime'.
 222      * @throws TimeRangeException
 223      *             If the passed endTime doesn't make sense (for example, if
 224      *             it's earlier than the latest time) and the backend doesn't
 225      *             know how to handle it.
 226      */
 227     void closeHistory(long endTime);
 228 }