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.CoreException;
  13 import org.eclipse.core.runtime.IProgressMonitor;
  14 import org.eclipse.tracecompass.tmf.core.timestamp.TmfTimeRange;
  15 import org.eclipse.tracecompass.tmf.core.trace.ITmfTrace;
  16
  17 /**
  18  * An on-demand analysis is an analysis run on a trace and started from an
  19  * explicit action from the user.
  20  *
  21  * The on-demand analysis object should be stateless, meaning every call of the
  22  * {@link #execute} method should be independant and not affect each other.
  23  *
  24  * @author Alexandre Montplaisir
  25  * @since 2.0
  26  */
  27 public interface IOnDemandAnalysis {
  28
  29     /**
  30      * Get the displayed name of this analysis. It should usually be
  31      * externalized.
  32      *
  33      * @return The name of this analysis
  34      */
  35     String getName();
  36
  37     /**
  38      * Returns whether or not this analysis is defined by a user, as opposed to
  39      * being built into Trace Compass (or an extension plugin).
  40      *
  41      * @return <code>true</code> if this analysis is defined by a user
  42      */
  43     boolean isUserDefined();
  44
  45     /**
  46      * Determine if the current analysis can run on the given trace.
  47      *
  48      * If it does not apply, then it should not be suggested for the given trace
  49      * at all.
  50      *
  51      * This method should be a quick filter, and should not for instance call
  52      * external processes.
  53      *
  54      * @param trace
  55      *            The trace to check for
  56      * @return If this analysis applies to the trace
  57      */
  58     boolean appliesTo(ITmfTrace trace);
  59
  60     /**
  61      * Second level of checking if an analysis can run on a trace.
  62      *
  63      * A analysis that {@link #appliesTo} a trace but whose {@link #canExecute}
  64      * returns false should be suggested to the user, albeit unavailable. For
  65      * example, striked-out in the UI.
  66      *
  67      * This will indicate to the user that in normal cases this analysis should
  68      * work, but something (trace contents, environment, etc.) is preventing it.
  69      *
  70      * @param trace
  71      *            The trace to check for
  72      * @return If this analysis can be run on this trace
  73      */
  74     boolean canExecute(ITmfTrace trace);
  75
  76     /**
  77      * Execute the analysis on the given trace.
  78      *
  79      * It should have been ensured that the analysis can run first on this
  80      * trace, by calling both {@link #appliesTo} and {@link #canExecute}.
  81      *
  82      * @param trace
  83      *            The trace on which to execute the analysis
  84      * @param range
  85      *            The timerange on which to execute the analysis.
  86      *            {@link TmfTimeRange#ETERNITY} can be used to indicate the
  87      *            whole trace.
  88      * @param extraParams
  89      *            Extra user-defined parameters to add to the analysis's
  90      *            command.
  91      * @param monitor
  92      *            The progress monitor to use to display progress, if the
  93      *            analysis supports it. You can pass 'new NullProgressMonitor()'
  94      *            for a default monitor.
  95      * @return The results of this analysis. Exact object type is
  96      *         analysis-dependent, a more specific return type is encouraged.
  97      * @throws CoreException
  98      *             If something went wrong with the execution, and expected
  99      *             results will not be returned
 100      */
 101     Object execute(ITmfTrace trace, TmfTimeRange range, String extraParams,
 102             IProgressMonitor monitor) throws CoreException;
 103 }