Commit | Line | Data |
---|---|---|
cc1b8519 AM |
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 | ||
46f0c09c | 12 | import org.eclipse.core.runtime.CoreException; |
cc1b8519 | 13 | import org.eclipse.core.runtime.IProgressMonitor; |
cc1b8519 AM |
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 | ||
9dbc0f9a AM |
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 | ||
cc1b8519 AM |
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 | |
fb88f89d AM |
85 | * The timerange on which to execute the analysis. |
86 | * {@link TmfTimeRange#ETERNITY} can be used to indicate the | |
87 | * whole trace. | |
cc1b8519 | 88 | * @param extraParams |
fb88f89d AM |
89 | * Extra user-defined parameters to add to the analysis's |
90 | * command. | |
cc1b8519 | 91 | * @param monitor |
fb88f89d AM |
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. | |
cc1b8519 AM |
95 | * @return The results of this analysis. Exact object type is |
96 | * analysis-dependent, a more specific return type is encouraged. | |
46f0c09c | 97 | * @throws CoreException |
fb88f89d AM |
98 | * If something went wrong with the execution, and expected |
99 | * results will not be returned | |
cc1b8519 | 100 | */ |
fb88f89d | 101 | Object execute(ITmfTrace trace, TmfTimeRange range, String extraParams, |
46f0c09c | 102 | IProgressMonitor monitor) throws CoreException; |
cc1b8519 | 103 | } |