tmf: Make IOnDemandAnalysis#execute() throw an exception

If execution of an analysis yields an error, it should be reported
to the user. This can be done using a custom exception.

Avoid @Nullable parameters while at it, and document what can be
used instead.

Change-Id: I499ec1938339f6fd6c00e5fb0b5ecf25f082f7ff
Signed-off-by: Alexandre Montplaisir <alexmonthy@efficios.com>
Reviewed-on: https://git.eclipse.org/r/71563
Reviewed-by: Patrick Tasse <patrick.tasse@gmail.com>
Tested-by: Patrick Tasse <patrick.tasse@gmail.com>
Reviewed-by: Hudson CI

diff --git a/tmf/org.eclipse.tracecompass.tmf.core/src/org/eclipse/tracecompass/tmf/core/analysis/ondemand/IOnDemandAnalysis.java b/tmf/org.eclipse.tracecompass.tmf.core/src/org/eclipse/tracecompass/tmf/core/analysis/ondemand/IOnDemandAnalysis.java
index ca0daaf251a14942cb3528383c787f6e4c33ebfa..58ef0fd49616602d8df9f08b59cd7da1fd0d20f7 100644 (file)
--- a/tmf/org.eclipse.tracecompass.tmf.core/src/org/eclipse/tracecompass/tmf/core/analysis/ondemand/IOnDemandAnalysis.java
+++ b/tmf/org.eclipse.tracecompass.tmf.core/src/org/eclipse/tracecompass/tmf/core/analysis/ondemand/IOnDemandAnalysis.java
@@ -10,7 +10,6 @@
 package org.eclipse.tracecompass.tmf.core.analysis.ondemand;
 
 import org.eclipse.core.runtime.IProgressMonitor;
-import org.eclipse.jdt.annotation.Nullable;
 import org.eclipse.tracecompass.tmf.core.timestamp.TmfTimeRange;
 import org.eclipse.tracecompass.tmf.core.trace.ITmfTrace;
 
@@ -74,15 +73,22 @@ public interface IOnDemandAnalysis {
      * @param trace
      *            The trace on which to execute the analysis
      * @param range
-     *            The time range on which to execute the analysis
+     *            The timerange on which to execute the analysis.
+     *            {@link TmfTimeRange#ETERNITY} can be used to indicate the
+     *            whole trace.
      * @param extraParams
-     *            Extra user-specified parameters to pass to the analysis
+     *            Extra user-defined parameters to add to the analysis's
+     *            command.
      * @param monitor
-     *            The progress monitor, can be null for a default monitor
+     *            The progress monitor to use to display progress, if the
+     *            analysis supports it. You can pass 'new NullProgressMonitor()'
+     *            for a default monitor.
      * @return The results of this analysis. Exact object type is
      *         analysis-dependent, a more specific return type is encouraged.
+     * @throws OnDemandAnalysisException
+     *             If something went wrong with the execution, and expected
+     *             results will not be returned
      */
-    Object execute(ITmfTrace trace, @Nullable TmfTimeRange range,
-            String extraParams, @Nullable IProgressMonitor monitor);
-
+    Object execute(ITmfTrace trace, TmfTimeRange range, String extraParams,
+            IProgressMonitor monitor) throws OnDemandAnalysisException;
 }

diff --git a/tmf/org.eclipse.tracecompass.tmf.core/src/org/eclipse/tracecompass/tmf/core/analysis/ondemand/OnDemandAnalysisException.java b/tmf/org.eclipse.tracecompass.tmf.core/src/org/eclipse/tracecompass/tmf/core/analysis/ondemand/OnDemandAnalysisException.java
new file mode 100644 (file)
index 0000000..5abd3bb
--- /dev/null
+++ b/tmf/org.eclipse.tracecompass.tmf.core/src/org/eclipse/tracecompass/tmf/core/analysis/ondemand/OnDemandAnalysisException.java
@@ -0,0 +1,43 @@
+/*******************************************************************************
+ * Copyright (c) 2016 EfficiOS Inc., Alexandre Montplaisir
+ *
+ * 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
+ *******************************************************************************/
+
+package org.eclipse.tracecompass.tmf.core.analysis.ondemand;
+
+import org.eclipse.jdt.annotation.Nullable;
+
+/**
+ * Exceptions resulting from the execution of on-demand analyses.
+ *
+ * The suggested behavior is to display the reported messages to the end user,
+ * so they know why execution did not end normally.
+ *
+ * @author Alexandre Montplaisir
+ * @since 2.0
+ */
+public class OnDemandAnalysisException extends Exception {
+
+    private static final long serialVersionUID = 7296987172562152876L;
+
+    /**
+     * Build a new exception. If the message is not null, it should be reported
+     * to the user.
+     *
+     * @param message
+     *            The message to display, if any
+     */
+    public OnDemandAnalysisException(@Nullable String message) {
+        super(message);
+    }
+
+    @Override
+    public @Nullable String getMessage() {
+        return super.getMessage();
+    }
+
+}