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

   1 /*******************************************************************************
   2  * Copyright (c) 2012 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     public 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     public 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     public 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     public void modifyAttribute(long t, ITmfStateValue value, int attributeQuark)
 123             throws TimeRangeException, AttributeNotFoundException,
 124             StateValueTypeException;
 125
 126     /**
 127      * Increment attribute method. Reads the current value of a given integer
 128      * attribute (this value is right now in the Transient State), and increment
 129      * it by 1. Useful for statistics.
 130      *
 131      * @param t
 132      *            Timestamp of the state change
 133      * @param attributeQuark
 134      *            Attribute to increment. If it doesn't exist it will be added,
 135      *            with a new value of 1.
 136      * @throws StateValueTypeException
 137      *             If the attribute already exists but is not of type Integer
 138      * @throws TimeRangeException
 139      *             If the given timestamp is invalid
 140      * @throws AttributeNotFoundException
 141      *             If the quark is invalid
 142      */
 143     public void incrementAttribute(long t, int attributeQuark)
 144             throws StateValueTypeException, TimeRangeException,
 145             AttributeNotFoundException;
 146
 147     /**
 148      * "Push" helper method. This uses the given integer attribute as a stack:
 149      * The value of that attribute will represent the stack depth (always >= 1).
 150      * Sub-attributes will be created, their base-name will be the position in
 151      * the stack (1, 2, etc.) and their value will be the state value 'value'
 152      * that was pushed to this position.
 153      *
 154      * @param t
 155      *            Timestamp of the state change
 156      * @param value
 157      *            State value to assign to this stack position.
 158      * @param attributeQuark
 159      *            The base attribute to use as a stack. If it does not exist if
 160      *            will be created (with depth = 1)
 161      * @throws TimeRangeException
 162      *             If the requested timestamp is invalid
 163      * @throws AttributeNotFoundException
 164      *             If the attribute is invalid
 165      * @throws StateValueTypeException
 166      *             If the attribute 'attributeQuark' already exists, but is not
 167      *             of integer type.
 168      */
 169     public void pushAttribute(long t, ITmfStateValue value, int attributeQuark)
 170             throws TimeRangeException, AttributeNotFoundException,
 171             StateValueTypeException;
 172
 173     /**
 174      * Antagonist of the pushAttribute(), pops the top-most attribute on the
 175      * stack-attribute. If this brings it back to depth = 0, the attribute is
 176      * kept with depth = 0. If the value is already 0, or if the attribute
 177      * doesn't exist, nothing is done.
 178      *
 179      * @param t
 180      *            Timestamp of the state change
 181      * @param attributeQuark
 182      *            Quark of the stack-attribute to pop
 183      * @return The state value that was popped, or 'null' if nothing was
 184      *         actually removed from the stack.
 185      * @throws AttributeNotFoundException
 186      *             If the attribute is invalid
 187      * @throws TimeRangeException
 188      *             If the timestamp is invalid
 189      * @throws StateValueTypeException
 190      *             If the target attribute already exists, but its state value
 191      *             type is invalid (not an integer)
 192      * @since 2.0
 193      */
 194     public ITmfStateValue popAttribute(long t, int attributeQuark)
 195             throws AttributeNotFoundException, TimeRangeException,
 196             StateValueTypeException;
 197
 198     /**
 199      * Remove attribute method. Similar to the above modify- methods, with value
 200      * = 0 / null, except we will also "nullify" all the sub-contents of the
 201      * requested path (a bit like "rm -rf")
 202      *
 203      * @param t
 204      *            Timestamp of the state change
 205      * @param attributeQuark
 206      *            Attribute to remove
 207      * @throws TimeRangeException
 208      *             If the timestamp is invalid
 209      * @throws AttributeNotFoundException
 210      *             If the quark is invalid
 211      */
 212     public void removeAttribute(long t, int attributeQuark)
 213             throws TimeRangeException, AttributeNotFoundException;
 214
 215     /**
 216      * Method to close off the History Provider. This happens for example when
 217      * we are done reading an off-line trace. First we close the TransientState,
 218      * commit it to the Provider, mark it as inactive, then we write the
 219      * Attribute Tree somewhere so we can reopen it later.
 220      *
 221      * @param endTime
 222      *            The requested End Time of the history, since it could be
 223      *            bigger than the timestamp of the last event or state change we
 224      *            have seen. All "ongoing" states will be extended until this
 225      *            'endTime'.
 226      * @throws TimeRangeException
 227      *             If the passed endTime doesn't make sense (for example, if
 228      *             it's earlier than the latest time) and the backend doesn't
 229      *             know how to handle it.
 230      */
 231     public void closeHistory(long endTime) throws TimeRangeException;
 232 }