| 1 | /******************************************************************************* |
| 2 | * Copyright (c) 2016 EfficiOS Inc., Alexandre Montplaisir |
| 3 | * |
| 4 | * All rights reserved. This program and the accompanying materials |
| 5 | * are made available under the terms of the Eclipse Public License v1.0 |
| 6 | * which accompanies this distribution, and is available at |
| 7 | * http://www.eclipse.org/legal/epl-v10.html |
| 8 | *******************************************************************************/ |
| 9 | |
| 10 | package org.eclipse.tracecompass.tmf.core.analysis.ondemand; |
| 11 | |
| 12 | import org.eclipse.core.runtime.CoreException; |
| 13 | import org.eclipse.core.runtime.IProgressMonitor; |
| 14 | import org.eclipse.tracecompass.tmf.core.timestamp.TmfTimeRange; |
| 15 | import org.eclipse.tracecompass.tmf.core.trace.ITmfTrace; |
| 16 | |
| 17 | /** |
| 18 | * An on-demand analysis is an analysis run on a trace and started from an |
| 19 | * explicit action from the user. |
| 20 | * |
| 21 | * The on-demand analysis object should be stateless, meaning every call of the |
| 22 | * {@link #execute} method should be independant and not affect each other. |
| 23 | * |
| 24 | * @author Alexandre Montplaisir |
| 25 | * @since 2.0 |
| 26 | */ |
| 27 | public interface IOnDemandAnalysis { |
| 28 | |
| 29 | /** |
| 30 | * Get the displayed name of this analysis. It should usually be |
| 31 | * externalized. |
| 32 | * |
| 33 | * @return The name of this analysis |
| 34 | */ |
| 35 | String getName(); |
| 36 | |
| 37 | /** |
| 38 | * Returns whether or not this analysis is defined by a user, as opposed to |
| 39 | * being built into Trace Compass (or an extension plugin). |
| 40 | * |
| 41 | * @return <code>true</code> if this analysis is defined by a user |
| 42 | */ |
| 43 | boolean isUserDefined(); |
| 44 | |
| 45 | /** |
| 46 | * Determine if the current analysis can run on the given trace. |
| 47 | * |
| 48 | * If it does not apply, then it should not be suggested for the given trace |
| 49 | * at all. |
| 50 | * |
| 51 | * This method should be a quick filter, and should not for instance call |
| 52 | * external processes. |
| 53 | * |
| 54 | * @param trace |
| 55 | * The trace to check for |
| 56 | * @return If this analysis applies to the trace |
| 57 | */ |
| 58 | boolean appliesTo(ITmfTrace trace); |
| 59 | |
| 60 | /** |
| 61 | * Second level of checking if an analysis can run on a trace. |
| 62 | * |
| 63 | * A analysis that {@link #appliesTo} a trace but whose {@link #canExecute} |
| 64 | * returns false should be suggested to the user, albeit unavailable. For |
| 65 | * example, striked-out in the UI. |
| 66 | * |
| 67 | * This will indicate to the user that in normal cases this analysis should |
| 68 | * work, but something (trace contents, environment, etc.) is preventing it. |
| 69 | * |
| 70 | * @param trace |
| 71 | * The trace to check for |
| 72 | * @return If this analysis can be run on this trace |
| 73 | */ |
| 74 | boolean canExecute(ITmfTrace trace); |
| 75 | |
| 76 | /** |
| 77 | * Execute the analysis on the given trace. |
| 78 | * |
| 79 | * It should have been ensured that the analysis can run first on this |
| 80 | * trace, by calling both {@link #appliesTo} and {@link #canExecute}. |
| 81 | * |
| 82 | * @param trace |
| 83 | * The trace on which to execute the analysis |
| 84 | * @param range |
| 85 | * The timerange on which to execute the analysis. |
| 86 | * {@link TmfTimeRange#ETERNITY} can be used to indicate the |
| 87 | * whole trace. |
| 88 | * @param extraParams |
| 89 | * Extra user-defined parameters to add to the analysis's |
| 90 | * command. |
| 91 | * @param monitor |
| 92 | * The progress monitor to use to display progress, if the |
| 93 | * analysis supports it. You can pass 'new NullProgressMonitor()' |
| 94 | * for a default monitor. |
| 95 | * @return The results of this analysis. Exact object type is |
| 96 | * analysis-dependent, a more specific return type is encouraged. |
| 97 | * @throws CoreException |
| 98 | * If something went wrong with the execution, and expected |
| 99 | * results will not be returned |
| 100 | */ |
| 101 | Object execute(ITmfTrace trace, TmfTimeRange range, String extraParams, |
| 102 | IProgressMonitor monitor) throws CoreException; |
| 103 | } |