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 | |
54eae41f | 15 | import org.eclipse.jdt.annotation.NonNull; |
2bdf0193 AM |
16 | import org.eclipse.tracecompass.tmf.core.exceptions.TmfAnalysisException; |
17 | import org.eclipse.tracecompass.tmf.core.trace.ITmfTrace; | |
c068a752 GB |
18 | import org.osgi.framework.Bundle; |
19 | ||
20 | /** | |
21 | * Interface for modules helpers that provide basic module information and | |
22 | * creates module from a source when requested. | |
23 | * | |
24 | * @author Geneviève Bastien | |
25 | */ | |
63c43609 | 26 | public interface IAnalysisModuleHelper extends IAnalysisRequirementProvider { |
c068a752 GB |
27 | |
28 | // ------------------------------------ | |
29 | // Getters | |
30 | // ------------------------------------ | |
31 | ||
32 | /** | |
33 | * Gets the id of the analysis module | |
34 | * | |
35 | * @return The id of the module | |
36 | */ | |
ba27dd38 | 37 | @NonNull String getId(); |
c068a752 GB |
38 | |
39 | /** | |
40 | * Gets the name of the analysis module | |
41 | * | |
42 | * @return The id of the module | |
43 | */ | |
ba27dd38 | 44 | @NonNull String getName(); |
c068a752 GB |
45 | |
46 | /** | |
47 | * Gets whether the analysis should be run automatically at trace opening | |
48 | * | |
49 | * @return true if analysis is to be run automatically | |
50 | */ | |
51 | boolean isAutomatic(); | |
52 | ||
53 | /** | |
54 | * Gets a generic help message/documentation for this analysis module | |
55 | * | |
56 | * This help text will be displayed to the user and may contain information | |
57 | * on what the module does, how to use it and how to correctly generate the | |
58 | * trace to make it available | |
59 | * | |
60 | * TODO: Help texts could be quite long. They should reside in their own | |
61 | * file and be accessed either with text, for a command line man page, or | |
62 | * through the eclipse help context. There should be a custom way to make it | |
63 | * available through the helper, without instantiating the analysis, though | |
64 | * help text after analysis instantiation may be richer. | |
65 | * | |
66 | * @return The generic help text | |
67 | */ | |
68 | String getHelpText(); | |
69 | ||
54eae41f GB |
70 | /** |
71 | * Gets a specific help message/documentation for this analysis module | |
72 | * applied on the given trace. This help message can add information on the | |
73 | * status of this analysis for a given trace, whether it can be executed or | |
74 | * not and why. | |
75 | * | |
76 | * This help text will be displayed to the user and may contain information | |
77 | * on what the module does, how to use it and how to correctly generate the | |
78 | * trace to make it available | |
79 | * | |
80 | * @param trace | |
81 | * A trace for which to get specific help message | |
82 | * @return The generic help text | |
83 | */ | |
84 | String getHelpText(@NonNull ITmfTrace trace); | |
85 | ||
c068a752 GB |
86 | /** |
87 | * Gets the icon for this module | |
88 | * | |
89 | * @return The icon path | |
90 | */ | |
91 | String getIcon(); | |
92 | ||
93 | /** | |
94 | * Gets the bundle this analysis module is part of | |
95 | * | |
96 | * @return The bundle | |
97 | */ | |
98 | Bundle getBundle(); | |
99 | ||
100 | /** | |
101 | * Does an analysis apply to a given trace type (otherwise, it is not shown) | |
102 | * | |
103 | * @param traceclass | |
104 | * The trace to analyze | |
105 | * @return whether the analysis applies | |
106 | */ | |
107 | boolean appliesToTraceType(Class<? extends ITmfTrace> traceclass); | |
108 | ||
63c43609 MR |
109 | /** |
110 | * Gets the list of valid trace types that the analysis can operate on. | |
111 | * | |
112 | * @return List of the trace type | |
113 | */ | |
114 | Iterable<Class<? extends ITmfTrace>> getValidTraceTypes(); | |
115 | ||
ff7b95a5 GB |
116 | /** |
117 | * Determine if an analysis should be run on an experiment if it applies to | |
118 | * at least one of its traces. It means that an instance of the analysis | |
119 | * module will be created specifically for the experiment and the result | |
120 | * will be more than a simple aggregation of the results of each trace's | |
121 | * module. This method does not actually do the check, it just returns | |
122 | * whether it should apply. | |
123 | * | |
124 | * @return whether this analysis should be run on an experiment | |
125 | * @since 1.0 | |
126 | */ | |
127 | boolean appliesToExperiment(); | |
128 | ||
c068a752 GB |
129 | // --------------------------------------- |
130 | // Functionalities | |
131 | // --------------------------------------- | |
132 | ||
133 | /** | |
134 | * Creates a new instance of the {@link IAnalysisModule} represented by this | |
135 | * helper and initializes it with the trace. | |
136 | * | |
3a26292f | 137 | * After the module is fully created, this method should call |
54eae41f GB |
138 | * {@link TmfAnalysisManager#analysisModuleCreated(IAnalysisModule)} in |
139 | * order for the new module listeners to be executed on this module. | |
3a26292f | 140 | * |
c068a752 GB |
141 | * @param trace |
142 | * The trace to be linked to the module | |
143 | * @return A new {@link IAnalysisModule} instance initialized with the | |
144 | * trace. | |
145 | * @throws TmfAnalysisException | |
146 | * Exceptions that occurred when setting trace | |
147 | */ | |
ba27dd38 | 148 | IAnalysisModule newModule(@NonNull ITmfTrace trace) throws TmfAnalysisException; |
c068a752 GB |
149 | |
150 | } |