1 /*******************************************************************************
2 * Copyright (c) 2013, 2014 École Polytechnique de Montréal
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
10 * Geneviève Bastien - Initial API and implementation
11 *******************************************************************************/
13 package org
.eclipse
.tracecompass
.tmf
.core
.analysis
;
15 import org
.eclipse
.core
.runtime
.IProgressMonitor
;
16 import org
.eclipse
.core
.runtime
.IStatus
;
17 import org
.eclipse
.jdt
.annotation
.NonNull
;
18 import org
.eclipse
.tracecompass
.tmf
.core
.component
.ITmfComponent
;
19 import org
.eclipse
.tracecompass
.tmf
.core
.exceptions
.TmfAnalysisException
;
20 import org
.eclipse
.tracecompass
.tmf
.core
.trace
.ITmfTrace
;
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.
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.
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
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.
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
42 * @author Geneviève Bastien
45 public interface IAnalysisModule
extends ITmfComponent
, IAnalysisRequirementProvider
, AutoCloseable
{
47 // --------------------------------------------------------
48 // Getters and setters
49 // --------------------------------------------------------
52 * Sets the name of the analysis module
57 void setName(String name
);
60 * Sets the id of the module
65 void setId(String id
);
68 * Gets the id of the analysis module
70 * @return The id of the module
76 * Sets whether this analysis should be run automatically at trace opening
79 * True if analysis should be run automatically for a trace
81 void setAutomatic(boolean auto
);
84 * Gets whether the analysis should be run automatically at trace opening
86 * @return true if analysis is to be run automatically
88 boolean isAutomatic();
91 * Sets the trace on which to run the analysis
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.
99 * The trace to run the analysis on
100 * @throws TmfAnalysisException
102 void setTrace(ITmfTrace trace
) throws TmfAnalysisException
;
105 * Add a parameter to this module
108 * Name of the parameter
110 void addParameter(String name
);
113 * Sets the value of a parameter
116 * The name of the parameter
118 * The value (subclasses may type-check it)
119 * @throws RuntimeException
121 void setParameter(String name
, Object value
);
124 * Gets the value of a parameter
127 * Name of the parameter
128 * @return The value of a parameter
130 Object
getParameter(String name
);
132 // -----------------------------------------------------
134 // -----------------------------------------------------
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
142 * The trace to analyze
143 * @return Whether the analysis can be executed
145 boolean canExecute(@NonNull ITmfTrace trace
);
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.
152 * @return An IStatus indicating if the execution of the analysis could be
153 * scheduled successfully or not.
158 * Gets a list of outputs
160 * @return The list of {@link IAnalysisOutput}
162 Iterable
<IAnalysisOutput
> getOutputs();
165 * Registers an output for this analysis
168 * The {@link IAnalysisOutput} object
170 void registerOutput(IAnalysisOutput output
);
173 * Block the calling thread until this analysis has completed (or has been
176 * @return True if the analysis finished successfully, false if it was
179 boolean waitForCompletion();
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
186 * To avoid UI freezes, it should not be called from the main thread of the
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.
197 boolean waitForCompletion(IProgressMonitor monitor
);
200 * Cancels the current analysis
204 // -----------------------------------------------------
206 // -----------------------------------------------------
209 * Gets a generic help message/documentation for this analysis module
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
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.
219 * @return The generic help text
221 String
getHelpText();
224 * Gets a help text specific for a given trace
226 * For instance, it may explain why the analysis module cannot be executed
227 * on a trace and how to correct this
230 * The trace to analyze
231 * @return A help text with information on a specific trace
233 String
getHelpText(ITmfTrace trace
);
236 * Notify the module that the value of a parameter has changed
239 * The of the parameter that changed
241 void notifyParameterChanged(String name
);
243 // -----------------------------------------------------
244 // AutoCloseable (remove the thrown exception)
245 // -----------------------------------------------------