1 /*******************************************************************************
2 * Copyright (c) 2016 EfficiOS Inc., Alexandre Montplaisir
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 *******************************************************************************/
10 package org
.eclipse
.tracecompass
.tmf
.core
.analysis
.ondemand
;
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
;
17 * An on-demand analysis is an analysis run on a trace and started from an
18 * explicit action from the user.
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.
23 * @author Alexandre Montplaisir
26 public interface IOnDemandAnalysis
{
29 * Get the displayed name of this analysis. It should usually be
32 * @return The name of this analysis
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).
40 * @return <code>true</code> if this analysis is defined by a user
42 boolean isUserDefined();
45 * Determine if the current analysis can run on the given trace.
47 * If it does not apply, then it should not be suggested for the given trace
50 * This method should be a quick filter, and should not for instance call
54 * The trace to check for
55 * @return If this analysis applies to the trace
57 boolean appliesTo(ITmfTrace trace
);
60 * Second level of checking if an analysis can run on a trace.
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.
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.
70 * The trace to check for
71 * @return If this analysis can be run on this trace
73 boolean canExecute(ITmfTrace trace
);
76 * Execute the analysis on the given trace.
78 * It should have been ensured that the analysis can run first on this
79 * trace, by calling both {@link #appliesTo} and {@link #canExecute}.
82 * The trace on which to execute the analysis
84 * The timerange on which to execute the analysis.
85 * {@link TmfTimeRange#ETERNITY} can be used to indicate the
88 * Extra user-defined parameters to add to the analysis's
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
100 Object
execute(ITmfTrace trace
, TmfTimeRange range
, String extraParams
,
101 IProgressMonitor monitor
) throws OnDemandAnalysisException
;