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