org.eclipse.tracecompass.tmf.core/src/org/eclipse/tracecompass/tmf/core/analysis/IAnalysisModule.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.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.component.ITmfComponent;
  20 import org.eclipse.tracecompass.tmf.core.exceptions.TmfAnalysisException;
  21 import org.eclipse.tracecompass.tmf.core.trace.ITmfTrace;
  22
  23 /**
  24  * Interface that hooks analysis modules to the rest of TMF. Analysis modules
  25  * are a set of operations to be run on a trace (or experiment). They will
  26  * typically either provide outputs to the end user, or feed other analysis.
  27  *
  28  * An analysis module must tell what trace type it applies to and if it can be
  29  * executed on a given trace of the right type.
  30  *
  31  * Implementations of this interface must define how an analysis will be
  32  * executed once scheduled and provide help texts to describe how to use the
  33  * analysis.
  34  *
  35  * Analysis can also take parameters, manually set, through default values or
  36  * using an {@link IAnalysisParameterProvider}. {@link IAnalysisOutput} can also
  37  * be registered to an analysis modules to display the results of the analysis.
  38  *
  39  * This interface just allows to hook the analysis to the TMF framework, but the
  40  * developer is free to implement the internals of its operations the way he
  41  * wishes.
  42  *
  43  * @author Geneviève Bastien
  44  */
  45 public interface IAnalysisModule extends ITmfComponent, IAnalysisRequirementProvider {
  46
  47     // --------------------------------------------------------
  48     // Getters and setters
  49     // --------------------------------------------------------
  50
  51     /**
  52      * Sets the name of the analysis module
  53      *
  54      * @param name
  55      *            name of the module
  56      */
  57     void setName(@NonNull String name);
  58
  59     /**
  60      * Sets the id of the module
  61      *
  62      * @param id
  63      *            id of the module
  64      */
  65     void setId(@NonNull String id);
  66
  67     /**
  68      * Gets the id of the analysis module
  69      *
  70      * @return The id of the module
  71      */
  72     @NonNull String getId();
  73
  74     /**
  75      * Sets whether this analysis should be run automatically at trace opening
  76      *
  77      * @param auto
  78      *            True if analysis should be run automatically for a trace
  79      */
  80     void setAutomatic(boolean auto);
  81
  82     /**
  83      * Gets whether the analysis should be run automatically at trace opening
  84      *
  85      * @return true if analysis is to be run automatically
  86      */
  87     boolean isAutomatic();
  88
  89     /**
  90      * Sets the trace on which to run the analysis
  91      *
  92      * Note: The trace cannot be final since most modules are instantiated in a
  93      * way that does not know about the trace, but it shouldn't be set more than
  94      * once since an instance of a module belongs to a trace. It is up to each
  95      * implementation to make sure the trace is set only once.
  96      *
  97      * @param trace
  98      *            The trace to run the analysis on
  99      * @throws TmfAnalysisException
 100      */
 101     void setTrace(@NonNull ITmfTrace trace) throws TmfAnalysisException;
 102
 103     /**
 104      * Add a parameter to this module
 105      *
 106      * @param name
 107      *            Name of the parameter
 108      */
 109     void addParameter(@NonNull String name);
 110
 111     /**
 112      * Sets the value of a parameter
 113      *
 114      * @param name
 115      *            The name of the parameter
 116      * @param value
 117      *            The value (subclasses may type-check it)
 118      * @throws RuntimeException
 119      */
 120     void setParameter(@NonNull String name, @Nullable Object value);
 121
 122     /**
 123      * Gets the value of a parameter
 124      *
 125      * @param name
 126      *            Name of the parameter
 127      * @return The value of a parameter
 128      */
 129     @Nullable Object getParameter(@NonNull String name);
 130
 131     // -----------------------------------------------------
 132     // Functionalities
 133     // -----------------------------------------------------
 134
 135     /**
 136      * Can an analysis be executed on a given trace (otherwise, it is shown
 137      * grayed out and a help message is available to see why it is not
 138      * applicable)
 139      *
 140      * @param trace
 141      *            The trace to analyze
 142      * @return Whether the analysis can be executed
 143      */
 144     boolean canExecute(@NonNull ITmfTrace trace);
 145
 146     /**
 147      * Schedule the execution of the analysis. If the trace has been set and is
 148      * opened, the analysis will be executed right away, otherwise it should
 149      * scheduled for execution once all pre-conditions are satisfied.
 150      *
 151      * @return An IStatus indicating if the execution of the analysis could be
 152      *         scheduled successfully or not.
 153      */
 154     @NonNull IStatus schedule();
 155
 156     /**
 157      * Gets a list of outputs
 158      *
 159      * @return The list of {@link IAnalysisOutput}
 160      */
 161     @NonNull Iterable<IAnalysisOutput> getOutputs();
 162
 163     /**
 164      * Registers an output for this analysis
 165      *
 166      * @param output
 167      *            The {@link IAnalysisOutput} object
 168      */
 169     void registerOutput(@NonNull IAnalysisOutput output);
 170
 171     /**
 172      * Block the calling thread until this analysis has completed (or has been
 173      * cancelled).
 174      *
 175      * @return True if the analysis finished successfully, false if it was
 176      *         cancelled.
 177      */
 178     boolean waitForCompletion();
 179
 180     /**
 181      * Typically the output of an analysis will be available only after it is
 182      * completed. This method allows to wait until an analysis has been
 183      * completed or the analysis has been cancelled
 184      *
 185      * To avoid UI freezes, it should not be called from the main thread of the
 186      * application
 187      *
 188      * @param monitor
 189      *            The progress monitor to check for cancellation
 190      * @return If the analysis was successfully completed. If false is returned,
 191      *         this either means there was a problem during the analysis, or it
 192      *         got cancelled before it could finished or it has not been
 193      *         scheduled to run at all. In all cases, the quality or
 194      *         availability of the output(s) and results is not guaranteed.
 195      */
 196     boolean waitForCompletion(@NonNull IProgressMonitor monitor);
 197
 198     /**
 199      * Cancels the current analysis
 200      */
 201     void cancel();
 202
 203     // -----------------------------------------------------
 204     // Utilities
 205     // -----------------------------------------------------
 206
 207     /**
 208      * Gets a generic help message/documentation for this analysis module
 209      *
 210      * This help text will be displayed to the user and may contain information
 211      * on what the module does, how to use it and how to correctly generate the
 212      * trace to make it available
 213      *
 214      * TODO: Help texts could be quite long. They should reside in their own
 215      * file and be accessed either with text, for a command line man page, or
 216      * through the eclipse help context.
 217      *
 218      * @return The generic help text
 219      */
 220     @NonNull String getHelpText();
 221
 222     /**
 223      * Gets a help text specific for a given trace
 224      *
 225      * For instance, it may explain why the analysis module cannot be executed
 226      * on a trace and how to correct this
 227      *
 228      * @param trace
 229      *            The trace to analyze
 230      * @return A help text with information on a specific trace
 231      */
 232     @NonNull String getHelpText(@NonNull ITmfTrace trace);
 233
 234     /**
 235      * Notify the module that the value of a parameter has changed
 236      *
 237      * @param name
 238      *            The of the parameter that changed
 239      */
 240     void notifyParameterChanged(@NonNull String name);
 241 }