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 * Determine if the current analysis can run on the given trace.
39 * If it does not apply, then it should not be suggested for the given trace
42 * This method should be a quick filter, and should not for instance call
46 * The trace to check for
47 * @return If this analysis applies to the trace
49 boolean appliesTo(ITmfTrace trace
);
52 * Second level of checking if an analysis can run on a trace.
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.
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.
62 * The trace to check for
63 * @return If this analysis can be run on this trace
65 boolean canExecute(ITmfTrace trace
);
68 * Execute the analysis on the given trace.
70 * It should have been ensured that the analysis can run first on this
71 * trace, by calling both {@link #appliesTo} and {@link #canExecute}.
74 * The trace on which to execute the analysis
76 * The timerange on which to execute the analysis.
77 * {@link TmfTimeRange#ETERNITY} can be used to indicate the
80 * Extra user-defined parameters to add to the analysis's
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
92 Object
execute(ITmfTrace trace
, TmfTimeRange range
, String extraParams
,
93 IProgressMonitor monitor
) throws OnDemandAnalysisException
;