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

   1 /*******************************************************************************
   2  * Copyright (c) 2012, 2013 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  * @since 2.0
  30  */
  31 public interface ITmfStateProvider {
  32
  33     /**
  34      * Event handler plugins should provide a version number. This is used to
  35      * determine if a potential existing file can be re-opened later (if the
  36      * versions in the file and in the viewer match), or if the file should be
  37      * rebuilt from scratch (if the versions don't match).
  38      *
  39      * @return The version number of the input plugin
  40      * @since 2.0
  41      */
  42     int getVersion();
  43
  44     /**
  45      * Get the trace with which this state input plugin is associated.
  46      *
  47      * @return The associated trace
  48      */
  49     ITmfTrace getTrace();
  50
  51     /**
  52      * Return the start time of this "state change input", which is normally the
  53      * start time of the originating trace (or it can be the time of the first
  54      * state-changing event).
  55      *
  56      * @return The start time
  57      */
  58     long getStartTime();
  59
  60     /**
  61      * Method for the input plugin to specify which type of events it expects.
  62      * This will guarantee that all events it receives via processEvent() are
  63      * indeed of the given type, so it should be safe to cast to that type.
  64      *
  65      * @return The expected Class of the event. Only events of this class (and
  66      *         valid subclasses) will be handled.
  67      * @since 2.0
  68      */
  69     Class<? extends ITmfEvent> getExpectedEventType();
  70
  71     /**
  72      * Assign the target state system where this SCI will insert its state
  73      * changes. Because of dependencies issues, this can normally not be done at
  74      * the constructor.
  75      *
  76      * This needs to be called before .run()!
  77      *
  78      * @param ssb
  79      *            Target state system for the state changes generated by this
  80      *            input plugin
  81      * @since 3.0
  82      */
  83     void assignTargetStateSystem(ITmfStateSystemBuilder ssb);
  84
  85     /**
  86      * Return the currently assigned target state system.
  87      *
  88      * @return Reference to the currently assigned state system, or null if no
  89      *         SS is assigned yet
  90      * @since 3.0
  91      */
  92     @Nullable ITmfStateSystem getAssignedStateSystem();
  93
  94     /**
  95      * Send an event to this input plugin for processing. The implementation
  96      * should check the contents, and call the state-modifying methods of its
  97      * IStateSystemBuilder object accordingly.
  98      *
  99      * @param event
 100      *            The event (which should be safe to cast to the
 101      *            expectedEventType) that has to be processed.
 102      */
 103     void processEvent(ITmfEvent event);
 104
 105     /**
 106      * Provide a non-initialized copy of this state input plugin. You will need
 107      * to call {@link #assignTargetStateSystem} on it to assign its target.
 108      *
 109      * @return A new state change input object, of the same type, but without an
 110      *         assigned target state system
 111      * @since 2.0
 112      */
 113     ITmfStateProvider getNewInstance();
 114
 115     /**
 116      * Indicate to the state history building process that we are done (for now),
 117      * and that it should close its current history.
 118      */
 119     void dispose();
 120 }