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