Commit | Line | Data |
---|---|---|
c068a752 | 1 | /******************************************************************************* |
60ae41e1 | 2 | * Copyright (c) 2013, 2014 École Polytechnique de Montréal |
c068a752 GB |
3 | * |
4 | * All rights reserved. This program and the accompanying materials are | |
5 | * made available under the terms of the Eclipse Public License v1.0 which | |
6 | * accompanies this distribution, and is available at | |
7 | * http://www.eclipse.org/legal/epl-v10.html | |
8 | * | |
9 | * Contributors: | |
10 | * Geneviève Bastien - Initial API and implementation | |
11 | *******************************************************************************/ | |
12 | ||
13 | package org.eclipse.linuxtools.tmf.core.analysis; | |
14 | ||
c068a752 GB |
15 | import org.eclipse.core.runtime.IProgressMonitor; |
16 | import org.eclipse.core.runtime.IStatus; | |
dc58a1fb | 17 | import org.eclipse.jdt.annotation.NonNull; |
a1529f38 | 18 | import org.eclipse.linuxtools.tmf.core.component.ITmfComponent; |
c068a752 GB |
19 | import org.eclipse.linuxtools.tmf.core.exceptions.TmfAnalysisException; |
20 | import org.eclipse.linuxtools.tmf.core.trace.ITmfTrace; | |
21 | ||
22 | /** | |
23 | * Interface that hooks analysis modules to the rest of TMF. Analysis modules | |
24 | * are a set of operations to be run on a trace (or experiment). They will | |
25 | * typically either provide outputs to the end user, or feed other analysis. | |
26 | * | |
27 | * An analysis module must tell what trace type it applies to and if it can be | |
28 | * executed on a given trace of the right type. | |
29 | * | |
30 | * Implementations of this interface must define how an analysis will be | |
31 | * executed once scheduled and provide help texts to describe how to use the | |
32 | * analysis. | |
33 | * | |
34 | * Analysis can also take parameters, manually set, through default values or | |
35 | * using an {@link IAnalysisParameterProvider}. {@link IAnalysisOutput} can also | |
36 | * be registered to an analysis modules to display the results of the analysis. | |
37 | * | |
38 | * This interface just allows to hook the analysis to the TMF framework, but the | |
39 | * developer is free to implement the internals of its operations the way he | |
40 | * wishes. | |
41 | * | |
42 | * @author Geneviève Bastien | |
43 | * @since 3.0 | |
44 | */ | |
bd64ee73 | 45 | public interface IAnalysisModule extends ITmfComponent, IAnalysisRequirementProvider, AutoCloseable { |
c068a752 GB |
46 | |
47 | // -------------------------------------------------------- | |
48 | // Getters and setters | |
49 | // -------------------------------------------------------- | |
50 | ||
51 | /** | |
52 | * Sets the name of the analysis module | |
53 | * | |
54 | * @param name | |
55 | * name of the module | |
56 | */ | |
57 | void setName(String name); | |
58 | ||
c068a752 GB |
59 | /** |
60 | * Sets the id of the module | |
61 | * | |
62 | * @param id | |
63 | * id of the module | |
64 | */ | |
65 | void setId(String id); | |
66 | ||
67 | /** | |
68 | * Gets the id of the analysis module | |
69 | * | |
70 | * @return The id of the module | |
71 | */ | |
dc58a1fb | 72 | @NonNull |
c068a752 GB |
73 | String getId(); |
74 | ||
75 | /** | |
76 | * Sets whether this analysis should be run automatically at trace opening | |
77 | * | |
78 | * @param auto | |
79 | * True if analysis should be run automatically for a trace | |
80 | */ | |
81 | void setAutomatic(boolean auto); | |
82 | ||
83 | /** | |
84 | * Gets whether the analysis should be run automatically at trace opening | |
85 | * | |
86 | * @return true if analysis is to be run automatically | |
87 | */ | |
88 | boolean isAutomatic(); | |
89 | ||
90 | /** | |
91 | * Sets the trace on which to run the analysis | |
92 | * | |
93 | * Note: The trace cannot be final since most modules are instantiated in a | |
94 | * way that does not know about the trace, but it shouldn't be set more than | |
95 | * once since an instance of a module belongs to a trace. It is up to each | |
96 | * implementation to make sure the trace is set only once. | |
97 | * | |
98 | * @param trace | |
99 | * The trace to run the analysis on | |
100 | * @throws TmfAnalysisException | |
101 | */ | |
102 | void setTrace(ITmfTrace trace) throws TmfAnalysisException; | |
103 | ||
104 | /** | |
105 | * Add a parameter to this module | |
106 | * | |
107 | * @param name | |
108 | * Name of the parameter | |
109 | */ | |
110 | void addParameter(String name); | |
111 | ||
112 | /** | |
113 | * Sets the value of a parameter | |
114 | * | |
115 | * @param name | |
116 | * The name of the parameter | |
117 | * @param value | |
118 | * The value (subclasses may type-check it) | |
119 | * @throws RuntimeException | |
120 | */ | |
121 | void setParameter(String name, Object value); | |
122 | ||
123 | /** | |
124 | * Gets the value of a parameter | |
125 | * | |
126 | * @param name | |
127 | * Name of the parameter | |
128 | * @return The value of a parameter | |
129 | */ | |
130 | Object getParameter(String name); | |
131 | ||
132 | // ----------------------------------------------------- | |
133 | // Functionalities | |
134 | // ----------------------------------------------------- | |
135 | ||
136 | /** | |
137 | * Can an analysis be executed on a given trace (otherwise, it is shown | |
138 | * grayed out and a help message is available to see why it is not | |
139 | * applicable) | |
140 | * | |
141 | * @param trace | |
142 | * The trace to analyze | |
143 | * @return Whether the analysis can be executed | |
144 | */ | |
26683871 | 145 | boolean canExecute(@NonNull ITmfTrace trace); |
c068a752 GB |
146 | |
147 | /** | |
148 | * Schedule the execution of the analysis. If the trace has been set and is | |
149 | * opened, the analysis will be executed right away, otherwise it should | |
150 | * scheduled for execution once all pre-conditions are satisfied. | |
151 | * | |
152 | * @return An IStatus indicating if the execution of the analysis could be | |
153 | * scheduled successfully or not. | |
154 | */ | |
155 | IStatus schedule(); | |
156 | ||
157 | /** | |
158 | * Gets a list of outputs | |
159 | * | |
160 | * @return The list of {@link IAnalysisOutput} | |
161 | */ | |
d9810555 | 162 | Iterable<IAnalysisOutput> getOutputs(); |
c068a752 GB |
163 | |
164 | /** | |
165 | * Registers an output for this analysis | |
166 | * | |
167 | * @param output | |
168 | * The {@link IAnalysisOutput} object | |
169 | */ | |
170 | void registerOutput(IAnalysisOutput output); | |
171 | ||
7d6122fc AM |
172 | /** |
173 | * Block the calling thread until this analysis has completed (or has been | |
174 | * cancelled). | |
175 | * | |
176 | * @return True if the analysis finished successfully, false if it was | |
177 | * cancelled. | |
178 | */ | |
179 | boolean waitForCompletion(); | |
180 | ||
c068a752 GB |
181 | /** |
182 | * Typically the output of an analysis will be available only after it is | |
183 | * completed. This method allows to wait until an analysis has been | |
184 | * completed or the analysis has been cancelled | |
185 | * | |
186 | * To avoid UI freezes, it should not be called from the main thread of the | |
187 | * application | |
188 | * | |
189 | * @param monitor | |
190 | * The progress monitor to check for cancellation | |
191 | * @return If the analysis was successfully completed. If false is returned, | |
192 | * this either means there was a problem during the analysis, or it | |
193 | * got cancelled before it could finished or it has not been | |
194 | * scheduled to run at all. In all cases, the quality or | |
195 | * availability of the output(s) and results is not guaranteed. | |
196 | */ | |
197 | boolean waitForCompletion(IProgressMonitor monitor); | |
198 | ||
199 | /** | |
200 | * Cancels the current analysis | |
201 | */ | |
7d6122fc | 202 | void cancel(); |
c068a752 GB |
203 | |
204 | // ----------------------------------------------------- | |
205 | // Utilities | |
206 | // ----------------------------------------------------- | |
207 | ||
208 | /** | |
209 | * Gets a generic help message/documentation for this analysis module | |
210 | * | |
211 | * This help text will be displayed to the user and may contain information | |
212 | * on what the module does, how to use it and how to correctly generate the | |
213 | * trace to make it available | |
214 | * | |
215 | * TODO: Help texts could be quite long. They should reside in their own | |
216 | * file and be accessed either with text, for a command line man page, or | |
217 | * through the eclipse help context. | |
218 | * | |
219 | * @return The generic help text | |
220 | */ | |
221 | String getHelpText(); | |
222 | ||
223 | /** | |
224 | * Gets a help text specific for a given trace | |
225 | * | |
226 | * For instance, it may explain why the analysis module cannot be executed | |
227 | * on a trace and how to correct this | |
228 | * | |
229 | * @param trace | |
230 | * The trace to analyze | |
231 | * @return A help text with information on a specific trace | |
232 | */ | |
233 | String getHelpText(ITmfTrace trace); | |
234 | ||
235 | /** | |
236 | * Notify the module that the value of a parameter has changed | |
237 | * | |
238 | * @param name | |
239 | * The of the parameter that changed | |
240 | */ | |
241 | void notifyParameterChanged(String name); | |
bd64ee73 AM |
242 | |
243 | // ----------------------------------------------------- | |
244 | // AutoCloseable (remove the thrown exception) | |
245 | // ----------------------------------------------------- | |
246 | ||
247 | @Override | |
248 | void close(); | |
c068a752 | 249 | } |