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