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
.jdt
.annotation
.NonNull
;
16 import org
.eclipse
.jdt
.annotation
.Nullable
;
17 import org
.eclipse
.tracecompass
.tmf
.core
.analysis
.requirements
.IAnalysisRequirementProvider
;
18 import org
.eclipse
.tracecompass
.tmf
.core
.exceptions
.TmfAnalysisException
;
19 import org
.eclipse
.tracecompass
.tmf
.core
.trace
.ITmfTrace
;
20 import org
.osgi
.framework
.Bundle
;
23 * Interface for modules helpers that provide basic module information and
24 * creates module from a source when requested.
26 * @author Geneviève Bastien
28 public interface IAnalysisModuleHelper
extends IAnalysisRequirementProvider
{
30 // ------------------------------------
32 // ------------------------------------
35 * Gets the id of the analysis module
37 * @return The id of the module
39 @NonNull String
getId();
42 * Gets the name of the analysis module
44 * @return The id of the module
46 @NonNull String
getName();
49 * Gets whether the analysis should be run automatically at trace opening
51 * @return true if analysis is to be run automatically
53 boolean isAutomatic();
56 * Gets a generic help message/documentation for this analysis module
58 * This help text will be displayed to the user and may contain information
59 * on what the module does, how to use it and how to correctly generate the
60 * trace to make it available
62 * TODO: Help texts could be quite long. They should reside in their own
63 * file and be accessed either with text, for a command line man page, or
64 * through the eclipse help context. There should be a custom way to make it
65 * available through the helper, without instantiating the analysis, though
66 * help text after analysis instantiation may be richer.
68 * @return The generic help text
73 * Gets a specific help message/documentation for this analysis module
74 * applied on the given trace. This help message can add information on the
75 * status of this analysis for a given trace, whether it can be executed or
78 * This help text will be displayed to the user and may contain information
79 * on what the module does, how to use it and how to correctly generate the
80 * trace to make it available
83 * A trace for which to get specific help message
84 * @return The generic help text
86 String
getHelpText(@NonNull ITmfTrace trace
);
89 * Gets the icon for this module
91 * @return The icon path
96 * Gets the bundle this analysis module is part of
103 * Does an analysis apply to a given trace type (otherwise, it is not shown)
106 * The trace to analyze
107 * @return whether the analysis applies
109 boolean appliesToTraceType(Class
<?
extends ITmfTrace
> traceclass
);
112 * Gets the list of valid trace types that the analysis can operate on.
114 * @return List of the trace type
116 Iterable
<Class
<?
extends ITmfTrace
>> getValidTraceTypes();
119 * Determine if an analysis should be run on an experiment if it applies to
120 * at least one of its traces. It means that an instance of the analysis
121 * module will be created specifically for the experiment and the result
122 * will be more than a simple aggregation of the results of each trace's
123 * module. This method does not actually do the check, it just returns
124 * whether it should apply.
126 * @return whether this analysis should be run on an experiment
129 boolean appliesToExperiment();
131 // ---------------------------------------
133 // ---------------------------------------
136 * Creates a new instance of the {@link IAnalysisModule} represented by this
137 * helper and initializes it with the trace.
139 * After the module is fully created, this method should call
140 * {@link TmfAnalysisManager#analysisModuleCreated(IAnalysisModule)} in
141 * order for the new module listeners to be executed on this module.
144 * The trace to be linked to the module
145 * @return A new {@link IAnalysisModule} instance initialized with the
146 * trace or {@code null} if the module couldn't be instantiated
147 * @throws TmfAnalysisException
148 * Exceptions that occurred when setting trace
150 @Nullable IAnalysisModule
newModule(@NonNull ITmfTrace trace
) throws TmfAnalysisException
;