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