tmf/org.eclipse.tracecompass.tmf.core/src/org/eclipse/tracecompass/tmf/core/analysis/IAnalysisModuleHelper.java

   1 /*******************************************************************************
   2  * Copyright (c) 2013, 2014 École Polytechnique de Montréal
   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
  13 package org.eclipse.tracecompass.tmf.core.analysis;
  14
  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;
  21
  22 /**
  23  * Interface for modules helpers that provide basic module information and
  24  * creates module from a source when requested.
  25  *
  26  * @author Geneviève Bastien
  27  */
  28 public interface IAnalysisModuleHelper extends IAnalysisRequirementProvider {
  29
  30     // ------------------------------------
  31     // Getters
  32     // ------------------------------------
  33
  34     /**
  35      * Gets the id of the analysis module
  36      *
  37      * @return The id of the module
  38      */
  39     @NonNull String getId();
  40
  41     /**
  42      * Gets the name of the analysis module
  43      *
  44      * @return The id of the module
  45      */
  46     @NonNull String getName();
  47
  48     /**
  49      * Gets whether the analysis should be run automatically at trace opening
  50      *
  51      * @return true if analysis is to be run automatically
  52      */
  53     boolean isAutomatic();
  54
  55     /**
  56      * Gets a generic help message/documentation for this analysis module
  57      *
  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
  61      *
  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.
  67      *
  68      * @return The generic help text
  69      */
  70     String getHelpText();
  71
  72     /**
  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
  76      * not and why.
  77      *
  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
  81      *
  82      * @param trace
  83      *            A trace for which to get specific help message
  84      * @return The generic help text
  85      */
  86     String getHelpText(@NonNull ITmfTrace trace);
  87
  88     /**
  89      * Gets the icon for this module
  90      *
  91      * @return The icon path
  92      */
  93     String getIcon();
  94
  95     /**
  96      * Gets the bundle this analysis module is part of
  97      *
  98      * @return The bundle
  99      */
 100     Bundle getBundle();
 101
 102     /**
 103      * Does an analysis apply to a given trace type (otherwise, it is not shown)
 104      *
 105      * @param traceclass
 106      *            The trace to analyze
 107      * @return whether the analysis applies
 108      */
 109     boolean appliesToTraceType(Class<? extends ITmfTrace> traceclass);
 110
 111     /**
 112      * Gets the list of valid trace types that the analysis can operate on.
 113      *
 114      * @return List of the trace type
 115      */
 116     Iterable<Class<? extends ITmfTrace>> getValidTraceTypes();
 117
 118     /**
 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.
 125      *
 126      * @return whether this analysis should be run on an experiment
 127      * @since 1.0
 128      */
 129     boolean appliesToExperiment();
 130
 131     // ---------------------------------------
 132     // Functionalities
 133     // ---------------------------------------
 134
 135     /**
 136      * Creates a new instance of the {@link IAnalysisModule} represented by this
 137      * helper and initializes it with the trace.
 138      *
 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.
 142      *
 143      * @param trace
 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
 149      */
 150     @Nullable IAnalysisModule newModule(@NonNull ITmfTrace trace) throws TmfAnalysisException;
 151
 152 }