statesystem/org.eclipse.tracecompass.statesystem.core/src/org/eclipse/tracecompass/statesystem/core/ITmfStateSystemBuilder.java

   1 /*******************************************************************************
   2  * Copyright (c) 2012, 2016 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.StateValueTypeException;
  17 import org.eclipse.tracecompass.statesystem.core.exceptions.TimeRangeException;
  18 import org.eclipse.tracecompass.statesystem.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  * @noimplement Only the internal StateSystem class should implement this
  33  *              interface.
  34  */
  35 public interface ITmfStateSystemBuilder extends ITmfStateSystem {
  36
  37     /**
  38      * Special state provider version number that will tell the backend to
  39      * ignore the version check and open an existing file even if the versions
  40      * don't match.
  41      */
  42     int IGNORE_PROVIDER_VERSION = -42;
  43
  44     /**
  45      * @name Read/write quark-getting methods
  46      */
  47
  48     /**
  49      * Basic quark-retrieving method. Pass an attribute in parameter as an array
  50      * of strings, the matching quark will be returned.
  51      *
  52      * This version WILL create new attributes: if the attribute passed in
  53      * parameter is new in the system, it will be added and its new quark will
  54      * be returned.
  55      *
  56      * @param attribute
  57      *            Attribute given as its full path in the Attribute Tree
  58      * @return The quark of the attribute (which either existed or just got
  59      *         created)
  60      */
  61     int getQuarkAbsoluteAndAdd(String... attribute);
  62
  63     /**
  64      * "Relative path" quark-getting method. Instead of specifying a full path,
  65      * if you know the path is relative to another attribute for which you
  66      * already have the quark, use this for better performance.
  67      *
  68      * This is useful for cases where a lot of modifications or queries will
  69      * originate from the same branch of the attribute tree : the common part of
  70      * the path won't have to be re-hashed for every access.
  71      *
  72      * This version WILL create new attributes: if the attribute passed in
  73      * parameter is new in the system, it will be added and its new quark will
  74      * be returned.
  75      *
  76      * @param startingNodeQuark
  77      *            The quark of the attribute from which 'subPath' originates.
  78      * @param subPath
  79      *            "Rest" of the path to get to the final attribute
  80      * @return The matching quark, either if it's new of just got created.
  81      * @throws IndexOutOfBoundsException
  82      *             If the starting node quark is out of range
  83      */
  84     int getQuarkRelativeAndAdd(int startingNodeQuark, String... subPath);
  85
  86     /**
  87      * @name State-changing methods
  88      */
  89
  90     /**
  91      * Modify a current "ongoing" state (instead of inserting a state change,
  92      * like modifyAttribute() and others).
  93      *
  94      * This can be used to update the value of a previous state change, for
  95      * example when we get information at the end of the state and not at the
  96      * beginning. (return values of system calls, etc.)
  97      *
  98      * Note that past states can only be modified while they are still in
  99      * memory, so only the "current state" can be updated. Once they get
 100      * committed to disk (by inserting a new state change) it becomes too late.
 101      *
 102      * @param newValue
 103      *            The new value that will overwrite the "current" one.
 104      * @param attributeQuark
 105      *            For which attribute in the system
 106      * @throws IndexOutOfBoundsException
 107      *             If the attribute quark is out of range
 108      */
 109     void updateOngoingState(@NonNull ITmfStateValue newValue, int attributeQuark);
 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 IndexOutOfBoundsException
 125      *             If the attribute quark is out of range
 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, @NonNull ITmfStateValue value, int attributeQuark)
 131             throws 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 IndexOutOfBoundsException
 148      *             If the attribute quark is out of range
 149      * @deprecated Use
 150      *             {@link StateSystemBuilderUtils#incrementAttributeInt(ITmfStateSystemBuilder, long, int, int)}
 151      *             instead
 152      */
 153     @Deprecated
 154     void incrementAttribute(long t, int attributeQuark)
 155             throws StateValueTypeException;
 156
 157     /**
 158      * "Push" helper method. This uses the given integer attribute as a stack:
 159      * The value of that attribute will represent the stack depth (always >= 1).
 160      * Sub-attributes will be created, their base-name will be the position in
 161      * the stack (1, 2, etc.) and their value will be the state value 'value'
 162      * that was pushed to this position.
 163      *
 164      * @param t
 165      *            Timestamp of the state change
 166      * @param value
 167      *            State value to assign to this stack position.
 168      * @param attributeQuark
 169      *            The base attribute to use as a stack. If it does not exist if
 170      *            will be created (with depth = 1)
 171      * @throws TimeRangeException
 172      *             If the requested timestamp is invalid
 173      * @throws IndexOutOfBoundsException
 174      *             If the attribute quark is out of range
 175      * @throws StateValueTypeException
 176      *             If the attribute 'attributeQuark' already exists, but is not
 177      *             of integer type.
 178      */
 179     void pushAttribute(long t, @NonNull ITmfStateValue value, int attributeQuark)
 180             throws StateValueTypeException;
 181
 182     /**
 183      * Antagonist of the pushAttribute(), pops the top-most attribute on the
 184      * stack-attribute. If this brings it back to depth = 0, the attribute is
 185      * kept with depth = 0. If the value is already 0, or if the attribute
 186      * doesn't exist, nothing is done.
 187      *
 188      * @param t
 189      *            Timestamp of the state change
 190      * @param attributeQuark
 191      *            Quark of the stack-attribute to pop
 192      * @return The state value that was popped, or 'null' if nothing was
 193      *         actually removed from the stack.
 194      * @throws IndexOutOfBoundsException
 195      *             If the attribute quark is out of range
 196      * @throws TimeRangeException
 197      *             If the timestamp is invalid
 198      * @throws StateValueTypeException
 199      *             If the target attribute already exists, but its state value
 200      *             type is invalid (not an integer)
 201      */
 202     ITmfStateValue popAttribute(long t, int attributeQuark)
 203             throws StateValueTypeException;
 204
 205     /**
 206      * Remove attribute method. Similar to the above modify- methods, with value
 207      * = 0 / null, except we will also "nullify" all the sub-contents of the
 208      * requested path (a bit like "rm -rf")
 209      *
 210      * @param t
 211      *            Timestamp of the state change
 212      * @param attributeQuark
 213      *            Attribute to remove
 214      * @throws TimeRangeException
 215      *             If the timestamp is invalid
 216      * @throws IndexOutOfBoundsException
 217      *             If the attribute quark is out of range
 218      */
 219     void removeAttribute(long t, int attributeQuark);
 220
 221     /**
 222      * Method to close off the History Provider. This happens for example when
 223      * we are done reading an off-line trace. First we close the TransientState,
 224      * commit it to the Provider, mark it as inactive, then we write the
 225      * Attribute Tree somewhere so we can reopen it later.
 226      *
 227      * @param endTime
 228      *            The requested End Time of the history, since it could be
 229      *            bigger than the timestamp of the last event or state change we
 230      *            have seen. All "ongoing" states will be extended until this
 231      *            'endTime'.
 232      * @throws TimeRangeException
 233      *             If the passed endTime doesn't make sense (for example, if
 234      *             it's earlier than the latest time) and the backend doesn't
 235      *             know how to handle it.
 236      */
 237     void closeHistory(long endTime);
 238
 239     /**
 240      * Delete any generated files or anything that might have been created by
 241      * the history backend (either temporary or save files). By calling this, we
 242      * return to the state as it was before ever building the history.
 243      *
 244      * You might not want to call automatically if, for example, you want an
 245      * index file to persist on disk. This could be limited to actions
 246      * originating from the user.
 247      *
 248      * FIXME Change to abstract for 3.0
 249      *
 250      * @since 2.1
 251      */
 252     default void removeFiles() {
 253         // FIXME Change to abstract for 3.0
 254     }
 255 }