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
.jdt
.annotation
.Nullable
;
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
;
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.
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.
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
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.
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
43 * @author Geneviève Bastien
45 public interface IAnalysisModule
extends ITmfComponent
, IAnalysisRequirementProvider
{
47 // --------------------------------------------------------
48 // Getters and setters
49 // --------------------------------------------------------
52 * Sets the name of the analysis module
57 void setName(@NonNull String name
);
60 * Sets the id of the module
65 void setId(@NonNull String id
);
68 * Gets the id of the analysis module
70 * @return The id of the module
72 @NonNull String
getId();
75 * Sets whether this analysis should be run automatically at trace opening
78 * True if analysis should be run automatically for a trace
80 void setAutomatic(boolean auto
);
83 * Gets whether the analysis should be run automatically at trace opening
85 * @return true if analysis is to be run automatically
87 boolean isAutomatic();
90 * Sets the trace on which to run the analysis and return whether the trace
91 * could be successfully set
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 * @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
103 * @throws TmfAnalysisException
104 * This exception should be thrown if the trace is set more than
108 boolean setTrace(@NonNull ITmfTrace trace
) throws TmfAnalysisException
;
111 * Add a parameter to this module
114 * Name of the parameter
116 void addParameter(@NonNull String name
);
119 * Sets the value of a parameter
122 * The name of the parameter
124 * The value (subclasses may type-check it)
125 * @throws RuntimeException
127 void setParameter(@NonNull String name
, @Nullable Object value
);
130 * Gets the value of a parameter
133 * Name of the parameter
134 * @return The value of a parameter
136 @Nullable Object
getParameter(@NonNull String name
);
138 // -----------------------------------------------------
140 // -----------------------------------------------------
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
148 * The trace to analyze
149 * @return Whether the analysis can be executed
151 boolean canExecute(@NonNull ITmfTrace trace
);
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.
158 * @return An IStatus indicating if the execution of the analysis could be
159 * scheduled successfully or not.
161 @NonNull IStatus
schedule();
164 * Gets a list of outputs
166 * @return The list of {@link IAnalysisOutput}
168 @NonNull Iterable
<IAnalysisOutput
> getOutputs();
171 * Registers an output for this analysis
174 * The {@link IAnalysisOutput} object
176 void registerOutput(@NonNull IAnalysisOutput output
);
179 * Block the calling thread until this analysis has completed (or has been
182 * @return True if the analysis finished successfully, false if it was
185 boolean waitForCompletion();
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
192 * To avoid UI freezes, it should not be called from the main thread of the
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.
203 boolean waitForCompletion(@NonNull IProgressMonitor monitor
);
206 * Cancels the current analysis
210 // -----------------------------------------------------
212 // -----------------------------------------------------
215 * Gets a generic help message/documentation for this analysis module
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
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.
225 * @return The generic help text
227 @NonNull String
getHelpText();
230 * Gets a help text specific for a given trace
232 * For instance, it may explain why the analysis module cannot be executed
233 * on a trace and how to correct this
236 * The trace to analyze
237 * @return A help text with information on a specific trace
239 @NonNull String
getHelpText(@NonNull ITmfTrace trace
);
242 * Notify the module that the value of a parameter has changed
245 * The of the parameter that changed
247 void notifyParameterChanged(@NonNull String name
);