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

   1 /*******************************************************************************
   2  * Copyright (c) 2013 É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.linuxtools.tmf.core.exceptions.TmfAnalysisException;
  16 import org.eclipse.linuxtools.tmf.core.trace.ITmfTrace;
  17 import org.osgi.framework.Bundle;
  18
  19 /**
  20  * Interface for modules helpers that provide basic module information and
  21  * creates module from a source when requested.
  22  *
  23  * @author Geneviève Bastien
  24  * @since 3.0
  25  */
  26 public interface IAnalysisModuleHelper {
  27
  28     // ------------------------------------
  29     // Getters
  30     // ------------------------------------
  31
  32     /**
  33      * Gets the id of the analysis module
  34      *
  35      * @return The id of the module
  36      */
  37     String getId();
  38
  39     /**
  40      * Gets the name of the analysis module
  41      *
  42      * @return The id of the module
  43      */
  44     String getName();
  45
  46     /**
  47      * Gets whether the analysis should be run automatically at trace opening
  48      *
  49      * @return true if analysis is to be run automatically
  50      */
  51     boolean isAutomatic();
  52
  53     /**
  54      * Gets a generic help message/documentation for this analysis module
  55      *
  56      * This help text will be displayed to the user and may contain information
  57      * on what the module does, how to use it and how to correctly generate the
  58      * trace to make it available
  59      *
  60      * TODO: Help texts could be quite long. They should reside in their own
  61      * file and be accessed either with text, for a command line man page, or
  62      * through the eclipse help context. There should be a custom way to make it
  63      * available through the helper, without instantiating the analysis, though
  64      * help text after analysis instantiation may be richer.
  65      *
  66      * @return The generic help text
  67      */
  68     String getHelpText();
  69
  70     /**
  71      * Gets the icon for this module
  72      *
  73      * @return The icon path
  74      */
  75     String getIcon();
  76
  77     /**
  78      * Gets the bundle this analysis module is part of
  79      *
  80      * @return The bundle
  81      */
  82     Bundle getBundle();
  83
  84     /**
  85      * Does an analysis apply to a given trace type (otherwise, it is not shown)
  86      *
  87      * @param traceclass
  88      *            The trace to analyze
  89      * @return whether the analysis applies
  90      */
  91     boolean appliesToTraceType(Class<? extends ITmfTrace> traceclass);
  92
  93     // ---------------------------------------
  94     // Functionalities
  95     // ---------------------------------------
  96
  97     /**
  98      * Creates a new instance of the {@link IAnalysisModule} represented by this
  99      * helper and initializes it with the trace.
 100      *
 101      * @param trace
 102      *            The trace to be linked to the module
 103      * @return A new {@link IAnalysisModule} instance initialized with the
 104      *         trace.
 105      * @throws TmfAnalysisException
 106      *             Exceptions that occurred when setting trace
 107      */
 108     IAnalysisModule newModule(ITmfTrace trace) throws TmfAnalysisException;
 109
 110 }