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