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
.analysis
.requirements
.IAnalysisRequirementProvider
;
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
;
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.
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.
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
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.
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
44 * @author Geneviève Bastien
46 public interface IAnalysisModule
extends ITmfComponent
, IAnalysisRequirementProvider
{
48 // --------------------------------------------------------
49 // Getters and setters
50 // --------------------------------------------------------
53 * Sets the name of the analysis module
58 void setName(@NonNull String name
);
61 * Sets the id of the module
66 void setId(@NonNull String id
);
69 * Gets the id of the analysis module
71 * @return The id of the module
73 @NonNull String
getId();
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 and return whether the trace
92 * could be successfully set
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.
100 * The trace to run the analysis on
101 * @return {@code true} if the trace was successfully set on the module,
102 * {@code false} if the analysis cannot be applied to the trace, for
103 * instance if the trace does not have the right requirements
104 * @throws TmfAnalysisException
105 * This exception should be thrown if the trace is set more than
109 boolean setTrace(@NonNull ITmfTrace trace
) throws TmfAnalysisException
;
112 * Add a parameter to this module
115 * Name of the parameter
117 void addParameter(@NonNull String name
);
120 * Sets the value of a parameter
123 * The name of the parameter
125 * The value (subclasses may type-check it)
126 * @throws RuntimeException
128 void setParameter(@NonNull String name
, @Nullable Object value
);
131 * Gets the value of a parameter
134 * Name of the parameter
135 * @return The value of a parameter
137 @Nullable Object
getParameter(@NonNull String name
);
139 // -----------------------------------------------------
141 // -----------------------------------------------------
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
149 * The trace to analyze
150 * @return Whether the analysis can be executed
152 boolean canExecute(@NonNull ITmfTrace trace
);
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.
159 * @return An IStatus indicating if the execution of the analysis could be
160 * scheduled successfully or not.
162 @NonNull IStatus
schedule();
165 * Gets a list of outputs
167 * @return The list of {@link IAnalysisOutput}
169 @NonNull Iterable
<IAnalysisOutput
> getOutputs();
172 * Registers an output for this analysis
175 * The {@link IAnalysisOutput} object
177 void registerOutput(@NonNull IAnalysisOutput output
);
180 * Block the calling thread until this analysis has completed (or has been
183 * @return True if the analysis finished successfully, false if it was
186 boolean waitForCompletion();
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
193 * To avoid UI freezes, it should not be called from the main thread of the
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.
204 boolean waitForCompletion(@NonNull IProgressMonitor monitor
);
207 * Return whether the analysis is ready to be queried at a given time.
209 * A return value of <code>false</code> means that the caller can wait and
210 * this will eventually return <code>true</code>.
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.
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.
226 default boolean isQueryable(long ts
) {
231 * Cancels the current analysis
235 // -----------------------------------------------------
237 // -----------------------------------------------------
240 * Gets a generic help message/documentation for this analysis module
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
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.
250 * @return The generic help text
252 @NonNull String
getHelpText();
255 * Gets a help text specific for a given trace
257 * For instance, it may explain why the analysis module cannot be executed
258 * on a trace and how to correct this
261 * The trace to analyze
262 * @return A help text with information on a specific trace
264 @NonNull String
getHelpText(@NonNull ITmfTrace trace
);
267 * Notify the module that the value of a parameter has changed
270 * The of the parameter that changed
272 void notifyParameterChanged(@NonNull String name
);