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