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      * Returns whether or not this analysis is defined by a user, as opposed to
  38      * being built into Trace Compass (or an extension plugin).
  39      *
  40      * @return <code>true</code> if this analysis is defined by a user
  41      */
  42     boolean isUserDefined();
  43
  44     /**
  45      * Determine if the current analysis can run on the given trace.
  46      *
  47      * If it does not apply, then it should not be suggested for the given trace
  48      * at all.
  49      *
  50      * This method should be a quick filter, and should not for instance call
  51      * external processes.
  52      *
  53      * @param trace
  54      *            The trace to check for
  55      * @return If this analysis applies to the trace
  56      */
  57     boolean appliesTo(ITmfTrace trace);
  58
  59     /**
  60      * Second level of checking if an analysis can run on a trace.
  61      *
  62      * A analysis that {@link #appliesTo} a trace but whose {@link #canExecute}
  63      * returns false should be suggested to the user, albeit unavailable. For
  64      * example, striked-out in the UI.
  65      *
  66      * This will indicate to the user that in normal cases this analysis should
  67      * work, but something (trace contents, environment, etc.) is preventing it.
  68      *
  69      * @param trace
  70      *            The trace to check for
  71      * @return If this analysis can be run on this trace
  72      */
  73     boolean canExecute(ITmfTrace trace);
  74
  75     /**
  76      * Execute the analysis on the given trace.
  77      *
  78      * It should have been ensured that the analysis can run first on this
  79      * trace, by calling both {@link #appliesTo} and {@link #canExecute}.
  80      *
  81      * @param trace
  82      *            The trace on which to execute the analysis
  83      * @param range
  84      *            The timerange on which to execute the analysis.
  85      *            {@link TmfTimeRange#ETERNITY} can be used to indicate the
  86      *            whole trace.
  87      * @param extraParams
  88      *            Extra user-defined parameters to add to the analysis's
  89      *            command.
  90      * @param monitor
  91      *            The progress monitor to use to display progress, if the
  92      *            analysis supports it. You can pass 'new NullProgressMonitor()'
  93      *            for a default monitor.
  94      * @return The results of this analysis. Exact object type is
  95      *         analysis-dependent, a more specific return type is encouraged.
  96      * @throws OnDemandAnalysisException
  97      *             If something went wrong with the execution, and expected
  98      *             results will not be returned
  99      */
 100     Object execute(ITmfTrace trace, TmfTimeRange range, String extraParams,
 101             IProgressMonitor monitor) throws OnDemandAnalysisException;
 102 }