tmf/org.eclipse.tracecompass.tmf.core/src/org/eclipse/tracecompass/tmf/core/statesystem/ITmfStateProvider.java

   1 /*******************************************************************************
   2  * Copyright (c) 2012, 2015 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.tracecompass.tmf.core.statesystem;
  14
  15 import org.eclipse.jdt.annotation.Nullable;
  16 import org.eclipse.tracecompass.statesystem.core.ITmfStateSystem;
  17 import org.eclipse.tracecompass.statesystem.core.ITmfStateSystemBuilder;
  18 import org.eclipse.tracecompass.tmf.core.event.ITmfEvent;
  19 import org.eclipse.tracecompass.tmf.core.trace.ITmfTrace;
  20
  21 /**
  22  * This is the interface used to define the "state change input", which is the
  23  * main type of input that goes in the state system.
  24  *
  25  * Usually a state change input, also called "state provider" is the piece of
  26  * the pipeline which converts trace events to state changes.
  27  *
  28  * @author Alexandre Montplaisir
  29  */
  30 public interface ITmfStateProvider {
  31
  32     /**
  33      * Event handler plugins should provide a version number. This is used to
  34      * determine if a potential existing file can be re-opened later (if the
  35      * versions in the file and in the viewer match), or if the file should be
  36      * rebuilt from scratch (if the versions don't match).
  37      *
  38      * @return The version number of the input plugin
  39      */
  40     int getVersion();
  41
  42     /**
  43      * Get the trace with which this state input plugin is associated.
  44      *
  45      * @return The associated trace
  46      */
  47     ITmfTrace getTrace();
  48
  49     /**
  50      * Return the start time of this "state change input", which is normally the
  51      * start time of the originating trace (or it can be the time of the first
  52      * state-changing event).
  53      *
  54      * @return The start time
  55      */
  56     long getStartTime();
  57
  58     /**
  59      * Return the last time at which it is safe to query the state system under
  60      * construction, ie not the current end time of the underlying state system,
  61      * but the time just before the latest event that has been processed.
  62      *
  63      * @return The last timestamp at which it is safe to query the state system
  64      *         underneath
  65      * @since 2.0
  66      */
  67     long getLatestSafeTime();
  68
  69     /**
  70      * Assign the target state system where this SCI will insert its state
  71      * changes. Because of dependencies issues, this can normally not be done at
  72      * the constructor.
  73      *
  74      * This needs to be called before .run()!
  75      *
  76      * @param ssb
  77      *            Target state system for the state changes generated by this
  78      *            input plugin
  79      */
  80     void assignTargetStateSystem(ITmfStateSystemBuilder ssb);
  81
  82     /**
  83      * Return the currently assigned target state system.
  84      *
  85      * @return Reference to the currently assigned state system, or null if no
  86      *         SS is assigned yet
  87      */
  88     @Nullable ITmfStateSystem getAssignedStateSystem();
  89
  90     /**
  91      * Send an event to this input plugin for processing. The implementation
  92      * should check the contents, and call the state-modifying methods of its
  93      * IStateSystemBuilder object accordingly.
  94      *
  95      * @param event
  96      *            The event (which should be safe to cast to the
  97      *            expectedEventType) that has to be processed.
  98      */
  99     void processEvent(ITmfEvent event);
 100
 101     /**
 102      * Provide a non-initialized copy of this state input plugin. You will need
 103      * to call {@link #assignTargetStateSystem} on it to assign its target.
 104      *
 105      * @return A new state change input object, of the same type, but without an
 106      *         assigned target state system
 107      */
 108     ITmfStateProvider getNewInstance();
 109
 110     /**
 111      * Indicate to the state history building process that we are done (for now),
 112      * and that it should close its current history.
 113      */
 114     void dispose();
 115 }