tmf/org.eclipse.tracecompass.tmf.core/src/org/eclipse/tracecompass/tmf/core/analysis/ondemand/IOnDemandAnalysis.java

   1 /*******************************************************************************
   2  * Copyright (c) 2016 EfficiOS Inc., Alexandre Montplaisir
   3  *
   4  * All rights reserved. This program and the accompanying materials
   5  * are made available under the terms of the Eclipse Public License v1.0
   6  * which accompanies this distribution, and is available at
   7  * http://www.eclipse.org/legal/epl-v10.html
   8  *******************************************************************************/
   9
  10 package org.eclipse.tracecompass.tmf.core.analysis.ondemand;
  11
  12 import org.eclipse.core.runtime.IProgressMonitor;
  13 import org.eclipse.tracecompass.tmf.core.timestamp.TmfTimeRange;
  14 import org.eclipse.tracecompass.tmf.core.trace.ITmfTrace;
  15
  16 /**
  17  * An on-demand analysis is an analysis run on a trace and started from an
  18  * explicit action from the user.
  19  *
  20  * The on-demand analysis object should be stateless, meaning every call of the
  21  * {@link #execute} method should be independant and not affect each other.
  22  *
  23  * @author Alexandre Montplaisir
  24  * @since 2.0
  25  */
  26 public interface IOnDemandAnalysis {
  27
  28     /**
  29      * Get the displayed name of this analysis. It should usually be
  30      * externalized.
  31      *
  32      * @return The name of this analysis
  33      */
  34     String getName();
  35
  36     /**
  37      * Determine if the current analysis can run on the given trace.
  38      *
  39      * If it does not apply, then it should not be suggested for the given trace
  40      * at all.
  41      *
  42      * This method should be a quick filter, and should not for instance call
  43      * external processes.
  44      *
  45      * @param trace
  46      *            The trace to check for
  47      * @return If this analysis applies to the trace
  48      */
  49     boolean appliesTo(ITmfTrace trace);
  50
  51     /**
  52      * Second level of checking if an analysis can run on a trace.
  53      *
  54      * A analysis that {@link #appliesTo} a trace but whose {@link #canExecute}
  55      * returns false should be suggested to the user, albeit unavailable. For
  56      * example, striked-out in the UI.
  57      *
  58      * This will indicate to the user that in normal cases this analysis should
  59      * work, but something (trace contents, environment, etc.) is preventing it.
  60      *
  61      * @param trace
  62      *            The trace to check for
  63      * @return If this analysis can be run on this trace
  64      */
  65     boolean canExecute(ITmfTrace trace);
  66
  67     /**
  68      * Execute the analysis on the given trace.
  69      *
  70      * It should have been ensured that the analysis can run first on this
  71      * trace, by calling both {@link #appliesTo} and {@link #canExecute}.
  72      *
  73      * @param trace
  74      *            The trace on which to execute the analysis
  75      * @param range
  76      *            The timerange on which to execute the analysis.
  77      *            {@link TmfTimeRange#ETERNITY} can be used to indicate the
  78      *            whole trace.
  79      * @param extraParams
  80      *            Extra user-defined parameters to add to the analysis's
  81      *            command.
  82      * @param monitor
  83      *            The progress monitor to use to display progress, if the
  84      *            analysis supports it. You can pass 'new NullProgressMonitor()'
  85      *            for a default monitor.
  86      * @return The results of this analysis. Exact object type is
  87      *         analysis-dependent, a more specific return type is encouraged.
  88      * @throws OnDemandAnalysisException
  89      *             If something went wrong with the execution, and expected
  90      *             results will not be returned
  91      */
  92     Object execute(ITmfTrace trace, TmfTimeRange range, String extraParams,
  93             IProgressMonitor monitor) throws OnDemandAnalysisException;
  94 }