tmf/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 and return whether the trace
  91      * could be successfully set
  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      * @return {@code true} if the trace was successfully set on the module,
 101      *         {@code false} if the analysis cannot be applied to the trace,
 102      *         for instance if the trace does not have the right requirements
 103      * @throws TmfAnalysisException
 104      *             This exception should be thrown if the trace is set more than
 105      *             once
 106      * @since 1.0
 107      */
 108     boolean setTrace(@NonNull ITmfTrace trace) throws TmfAnalysisException;
 109
 110     /**
 111      * Add a parameter to this module
 112      *
 113      * @param name
 114      *            Name of the parameter
 115      */
 116     void addParameter(@NonNull String name);
 117
 118     /**
 119      * Sets the value of a parameter
 120      *
 121      * @param name
 122      *            The name of the parameter
 123      * @param value
 124      *            The value (subclasses may type-check it)
 125      * @throws RuntimeException
 126      */
 127     void setParameter(@NonNull String name, @Nullable Object value);
 128
 129     /**
 130      * Gets the value of a parameter
 131      *
 132      * @param name
 133      *            Name of the parameter
 134      * @return The value of a parameter
 135      */
 136     @Nullable Object getParameter(@NonNull String name);
 137
 138     // -----------------------------------------------------
 139     // Functionalities
 140     // -----------------------------------------------------
 141
 142     /**
 143      * Can an analysis be executed on a given trace (otherwise, it is shown
 144      * grayed out and a help message is available to see why it is not
 145      * applicable)
 146      *
 147      * @param trace
 148      *            The trace to analyze
 149      * @return Whether the analysis can be executed
 150      */
 151     boolean canExecute(@NonNull ITmfTrace trace);
 152
 153     /**
 154      * Schedule the execution of the analysis. If the trace has been set and is
 155      * opened, the analysis will be executed right away, otherwise it should
 156      * scheduled for execution once all pre-conditions are satisfied.
 157      *
 158      * @return An IStatus indicating if the execution of the analysis could be
 159      *         scheduled successfully or not.
 160      */
 161     @NonNull IStatus schedule();
 162
 163     /**
 164      * Gets a list of outputs
 165      *
 166      * @return The list of {@link IAnalysisOutput}
 167      */
 168     @NonNull Iterable<IAnalysisOutput> getOutputs();
 169
 170     /**
 171      * Registers an output for this analysis
 172      *
 173      * @param output
 174      *            The {@link IAnalysisOutput} object
 175      */
 176     void registerOutput(@NonNull IAnalysisOutput output);
 177
 178     /**
 179      * Block the calling thread until this analysis has completed (or has been
 180      * cancelled).
 181      *
 182      * @return True if the analysis finished successfully, false if it was
 183      *         cancelled.
 184      */
 185     boolean waitForCompletion();
 186
 187     /**
 188      * Typically the output of an analysis will be available only after it is
 189      * completed. This method allows to wait until an analysis has been
 190      * completed or the analysis has been cancelled
 191      *
 192      * To avoid UI freezes, it should not be called from the main thread of the
 193      * application
 194      *
 195      * @param monitor
 196      *            The progress monitor to check for cancellation
 197      * @return If the analysis was successfully completed. If false is returned,
 198      *         this either means there was a problem during the analysis, or it
 199      *         got cancelled before it could finished or it has not been
 200      *         scheduled to run at all. In all cases, the quality or
 201      *         availability of the output(s) and results is not guaranteed.
 202      */
 203     boolean waitForCompletion(@NonNull IProgressMonitor monitor);
 204
 205     /**
 206      * Cancels the current analysis
 207      */
 208     void cancel();
 209
 210     // -----------------------------------------------------
 211     // Utilities
 212     // -----------------------------------------------------
 213
 214     /**
 215      * Gets a generic help message/documentation for this analysis module
 216      *
 217      * This help text will be displayed to the user and may contain information
 218      * on what the module does, how to use it and how to correctly generate the
 219      * trace to make it available
 220      *
 221      * TODO: Help texts could be quite long. They should reside in their own
 222      * file and be accessed either with text, for a command line man page, or
 223      * through the eclipse help context.
 224      *
 225      * @return The generic help text
 226      */
 227     @NonNull String getHelpText();
 228
 229     /**
 230      * Gets a help text specific for a given trace
 231      *
 232      * For instance, it may explain why the analysis module cannot be executed
 233      * on a trace and how to correct this
 234      *
 235      * @param trace
 236      *            The trace to analyze
 237      * @return A help text with information on a specific trace
 238      */
 239     @NonNull String getHelpText(@NonNull ITmfTrace trace);
 240
 241     /**
 242      * Notify the module that the value of a parameter has changed
 243      *
 244      * @param name
 245      *            The of the parameter that changed
 246      */
 247     void notifyParameterChanged(@NonNull String name);
 248 }