TMF: Have IAnalysisModule#setTrace return boolean instead of throw exception

[deliverable/tracecompass.git] / org.eclipse.tracecompass.tmf.core / src / org / eclipse / tracecompass / tmf / core / analysis / IAnalysisModuleHelper.java

/*******************************************************************************
 * Copyright (c) 2013, 2014 École Polytechnique de Montréal
 *
 * All rights reserved. This program and the accompanying materials are
 * made available under the terms of the Eclipse Public License v1.0 which
 * accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *   Geneviève Bastien - Initial API and implementation
 *******************************************************************************/

package org.eclipse.tracecompass.tmf.core.analysis;

import org.eclipse.jdt.annotation.NonNull;
import org.eclipse.jdt.annotation.Nullable;
import org.eclipse.tracecompass.tmf.core.exceptions.TmfAnalysisException;
import org.eclipse.tracecompass.tmf.core.trace.ITmfTrace;
import org.osgi.framework.Bundle;

/**
 * Interface for modules helpers that provide basic module information and
 * creates module from a source when requested.
 *
 * @author Geneviève Bastien
 */
public interface IAnalysisModuleHelper extends IAnalysisRequirementProvider {

    // ------------------------------------
    // Getters
    // ------------------------------------

    /**
     * Gets the id of the analysis module
     *
     * @return The id of the module
     */
    @NonNull String getId();

    /**
     * Gets the name of the analysis module
     *
     * @return The id of the module
     */
    @NonNull String getName();

    /**
     * Gets whether the analysis should be run automatically at trace opening
     *
     * @return true if analysis is to be run automatically
     */
    boolean isAutomatic();

    /**
     * Gets a generic help message/documentation for this analysis module
     *
     * This help text will be displayed to the user and may contain information
     * on what the module does, how to use it and how to correctly generate the
     * trace to make it available
     *
     * TODO: Help texts could be quite long. They should reside in their own
     * file and be accessed either with text, for a command line man page, or
     * through the eclipse help context. There should be a custom way to make it
     * available through the helper, without instantiating the analysis, though
     * help text after analysis instantiation may be richer.
     *
     * @return The generic help text
     */
    String getHelpText();

    /**
     * Gets a specific help message/documentation for this analysis module
     * applied on the given trace. This help message can add information on the
     * status of this analysis for a given trace, whether it can be executed or
     * not and why.
     *
     * This help text will be displayed to the user and may contain information
     * on what the module does, how to use it and how to correctly generate the
     * trace to make it available
     *
     * @param trace
     *            A trace for which to get specific help message
     * @return The generic help text
     */
    String getHelpText(@NonNull ITmfTrace trace);

    /**
     * Gets the icon for this module
     *
     * @return The icon path
     */
    String getIcon();

    /**
     * Gets the bundle this analysis module is part of
     *
     * @return The bundle
     */
    Bundle getBundle();

    /**
     * Does an analysis apply to a given trace type (otherwise, it is not shown)
     *
     * @param traceclass
     *            The trace to analyze
     * @return whether the analysis applies
     */
    boolean appliesToTraceType(Class<? extends ITmfTrace> traceclass);

    /**
     * Gets the list of valid trace types that the analysis can operate on.
     *
     * @return List of the trace type
     */
    Iterable<Class<? extends ITmfTrace>> getValidTraceTypes();

    /**
     * Determine if an analysis should be run on an experiment if it applies to
     * at least one of its traces. It means that an instance of the analysis
     * module will be created specifically for the experiment and the result
     * will be more than a simple aggregation of the results of each trace's
     * module. This method does not actually do the check, it just returns
     * whether it should apply.
     *
     * @return whether this analysis should be run on an experiment
     * @since 1.0
     */
    boolean appliesToExperiment();

    // ---------------------------------------
    // Functionalities
    // ---------------------------------------

    /**
     * Creates a new instance of the {@link IAnalysisModule} represented by this
     * helper and initializes it with the trace.
     *
     * After the module is fully created, this method should call
     * {@link TmfAnalysisManager#analysisModuleCreated(IAnalysisModule)} in
     * order for the new module listeners to be executed on this module.
     *
     * @param trace
     *            The trace to be linked to the module
     * @return A new {@link IAnalysisModule} instance initialized with the
     *         trace or {@code null} if the module couldn't be instantiated
     * @throws TmfAnalysisException
     *             Exceptions that occurred when setting trace
     */
    @Nullable IAnalysisModule newModule(@NonNull ITmfTrace trace) throws TmfAnalysisException;

}