org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/analysis/TmfAbstractAnalysisModule.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.linuxtools.tmf.core.analysis;
  14
  15 import java.util.ArrayList;
  16 import java.util.HashMap;
  17 import java.util.List;
  18 import java.util.Map;
  19 import java.util.concurrent.CountDownLatch;
  20 import java.util.concurrent.TimeUnit;
  21
  22 import org.eclipse.core.runtime.IProgressMonitor;
  23 import org.eclipse.core.runtime.IStatus;
  24 import org.eclipse.core.runtime.Status;
  25 import org.eclipse.core.runtime.jobs.Job;
  26 import org.eclipse.linuxtools.internal.tmf.core.Activator;
  27 import org.eclipse.linuxtools.tmf.core.component.TmfComponent;
  28 import org.eclipse.linuxtools.tmf.core.exceptions.TmfAnalysisException;
  29 import org.eclipse.linuxtools.tmf.core.signal.TmfSignalHandler;
  30 import org.eclipse.linuxtools.tmf.core.signal.TmfStartAnalysisSignal;
  31 import org.eclipse.linuxtools.tmf.core.signal.TmfTraceClosedSignal;
  32 import org.eclipse.linuxtools.tmf.core.trace.ITmfTrace;
  33 import org.eclipse.linuxtools.tmf.core.trace.TmfTrace;
  34 import org.eclipse.osgi.util.NLS;
  35
  36 /**
  37  * Base class that analysis modules main class may extend. It provides default
  38  * behavior to some methods of the analysis module
  39  *
  40  * @author Geneviève Bastien
  41  * @since 3.0
  42  */
  43 public abstract class TmfAbstractAnalysisModule extends TmfComponent implements IAnalysisModule {
  44
  45     private String fName, fId;
  46     private boolean fAutomatic = false, fStarted = false;
  47     private ITmfTrace fTrace;
  48     private final Map<String, Object> fParameters = new HashMap<>();
  49     private final List<String> fParameterNames = new ArrayList<>();
  50     private final List<IAnalysisOutput> fOutputs = new ArrayList<>();
  51     private List<IAnalysisParameterProvider> fParameterProviders = new ArrayList<>();
  52     private Job fJob = null;
  53
  54     private final Object syncObj = new Object();
  55
  56     /* Latch tracking if the analysis is completed or not */
  57     private CountDownLatch fFinishedLatch = new CountDownLatch(0);
  58
  59     private boolean fAnalysisCancelled = false;
  60
  61     @Override
  62     public boolean isAutomatic() {
  63         return fAutomatic;
  64     }
  65
  66     @Override
  67     public String getName() {
  68         return fName;
  69     }
  70
  71     @Override
  72     public void setName(String name) {
  73         fName = name;
  74     }
  75
  76     @Override
  77     public void setId(String id) {
  78         fId = id;
  79     }
  80
  81     @Override
  82     public String getId() {
  83         return fId;
  84     }
  85
  86     @Override
  87     public void setAutomatic(boolean auto) {
  88         fAutomatic = auto;
  89     }
  90
  91     @Override
  92     public void setTrace(ITmfTrace trace) throws TmfAnalysisException {
  93         if (fTrace != null) {
  94             throw new TmfAnalysisException(NLS.bind(Messages.TmfAbstractAnalysisModule_TraceSetMoreThanOnce, getName()));
  95         }
  96
  97         /* Check that analysis can be executed */
  98         if (!canExecute(trace)) {
  99             throw new TmfAnalysisException(NLS.bind(Messages.TmfAbstractAnalysisModule_AnalysisCannotExecute, getName()));
 100         }
 101         fTrace = trace;
 102         /* Get the parameter providers for this trace */
 103         fParameterProviders = TmfAnalysisManager.getParameterProviders(this, fTrace);
 104         for (IAnalysisParameterProvider provider : fParameterProviders) {
 105             provider.registerModule(this);
 106         }
 107         resetAnalysis();
 108         fStarted = false;
 109     }
 110
 111     /**
 112      * Gets the trace
 113      *
 114      * @return The trace
 115      */
 116     protected ITmfTrace getTrace() {
 117         return fTrace;
 118     }
 119
 120     @Override
 121     public void addParameter(String name) {
 122         fParameterNames.add(name);
 123     }
 124
 125     @Override
 126     public synchronized void setParameter(String name, Object value) {
 127         if (!fParameterNames.contains(name)) {
 128             throw new RuntimeException(NLS.bind(Messages.TmfAbstractAnalysisModule_InvalidParameter, name, getName()));
 129         }
 130         Object oldValue = fParameters.get(name);
 131         fParameters.put(name, value);
 132         if ((value != null) && !(value.equals(oldValue))) {
 133             parameterChanged(name);
 134         }
 135     }
 136
 137     @Override
 138     public synchronized void notifyParameterChanged(String name) {
 139         if (!fParameterNames.contains(name)) {
 140             throw new RuntimeException(NLS.bind(Messages.TmfAbstractAnalysisModule_InvalidParameter, name, getName()));
 141         }
 142         Object oldValue = fParameters.get(name);
 143         Object value = getParameter(name);
 144         if ((value != null) && !(value.equals(oldValue))) {
 145             parameterChanged(name);
 146         }
 147     }
 148
 149     /**
 150      * Used to indicate that a parameter value has been changed
 151      *
 152      * @param name
 153      *            The name of the modified parameter
 154      */
 155     protected void parameterChanged(String name) {
 156
 157     }
 158
 159     @Override
 160     public Object getParameter(String name) {
 161         Object paramValue = fParameters.get(name);
 162         /* The parameter is not set, maybe it can be provided by someone else */
 163         if ((paramValue == null) && (fTrace != null)) {
 164             for (IAnalysisParameterProvider provider : fParameterProviders) {
 165                 paramValue = provider.getParameter(name);
 166                 if (paramValue != null) {
 167                     break;
 168                 }
 169             }
 170         }
 171         return paramValue;
 172     }
 173
 174     @Override
 175     public boolean canExecute(ITmfTrace trace) {
 176         return true;
 177     }
 178
 179     /**
 180      * Set the countdown latch back to 1 so the analysis can be executed again
 181      */
 182     protected void resetAnalysis() {
 183         fFinishedLatch.countDown();
 184         fFinishedLatch = new CountDownLatch(1);
 185     }
 186
 187     /**
 188      * Actually executes the analysis itself
 189      *
 190      * @param monitor
 191      *            Progress monitor
 192      * @return Whether the analysis was completed successfully or not
 193      * @throws TmfAnalysisException
 194      *             Method may throw an analysis exception
 195      */
 196     protected abstract boolean executeAnalysis(final IProgressMonitor monitor) throws TmfAnalysisException;
 197
 198     /**
 199      * Indicate the analysis has been canceled. It is abstract to force
 200      * implementing class to cleanup what they are running. This is called by
 201      * the job's canceling. It does not need to be called directly.
 202      */
 203     protected abstract void canceling();
 204
 205     /**
 206      * To be called when the analysis is completed, whether normally or because
 207      * it was cancelled or for any other reason.
 208      *
 209      * It has to be called inside a synchronized block
 210      */
 211     private void setAnalysisCompleted() {
 212         fStarted = false;
 213         fJob = null;
 214         fFinishedLatch.countDown();
 215         if (fTrace instanceof TmfTrace) {
 216             ((TmfTrace) fTrace).refreshSupplementaryFiles();
 217         }
 218     }
 219
 220     /**
 221      * Cancels the analysis if it is executing
 222      */
 223     @Override
 224     public final void cancel() {
 225         synchronized (syncObj) {
 226             if (fJob != null) {
 227                 if (fJob.cancel()) {
 228                     fAnalysisCancelled = true;
 229                     setAnalysisCompleted();
 230                 }
 231             }
 232             fStarted = false;
 233         }
 234     }
 235
 236     private void execute() {
 237
 238         /*
 239          * TODO: The analysis in a job should be done at the analysis manager
 240          * level instead of depending on this abstract class implementation,
 241          * otherwise another analysis implementation may block the main thread
 242          */
 243
 244         /* Do not execute if analysis has already run */
 245         if (fFinishedLatch.getCount() == 0) {
 246             return;
 247         }
 248
 249         /* Do not execute if analysis already running */
 250         synchronized (syncObj) {
 251             if (fStarted) {
 252                 return;
 253             }
 254             fStarted = true;
 255         }
 256
 257         /*
 258          * Actual analysis will be run on a separate thread
 259          */
 260         fJob = new Job(NLS.bind(Messages.TmfAbstractAnalysisModule_RunningAnalysis, getName())) {
 261             @Override
 262             protected IStatus run(final IProgressMonitor monitor) {
 263                 try {
 264                     monitor.beginTask("", IProgressMonitor.UNKNOWN); //$NON-NLS-1$
 265                     broadcast(new TmfStartAnalysisSignal(TmfAbstractAnalysisModule.this, TmfAbstractAnalysisModule.this));
 266                     fAnalysisCancelled = !executeAnalysis(monitor);
 267                 } catch (TmfAnalysisException e) {
 268                     Activator.logError("Error executing analysis with trace " + getTrace().getName(), e); //$NON-NLS-1$
 269                 } finally {
 270                     synchronized (syncObj) {
 271                         monitor.done();
 272                         setAnalysisCompleted();
 273                     }
 274                 }
 275                 if (!fAnalysisCancelled) {
 276                     return Status.OK_STATUS;
 277                 }
 278                 // Reset analysis so that it can be executed again.
 279                 resetAnalysis();
 280                 return Status.CANCEL_STATUS;
 281             }
 282
 283             @Override
 284             protected void canceling() {
 285                 TmfAbstractAnalysisModule.this.canceling();
 286             }
 287
 288         };
 289         fJob.schedule();
 290     }
 291
 292     @Override
 293     public IStatus schedule() {
 294         if (fTrace == null) {
 295             return new Status(IStatus.ERROR, Activator.PLUGIN_ID, String.format("No trace specified for analysis %s", getName())); //$NON-NLS-1$
 296         }
 297         execute();
 298
 299         return Status.OK_STATUS;
 300     }
 301
 302     @Override
 303     public Iterable<IAnalysisOutput> getOutputs() {
 304         return fOutputs;
 305     }
 306
 307     @Override
 308     public void registerOutput(IAnalysisOutput output) {
 309         if (!fOutputs.contains(output)) {
 310             fOutputs.add(output);
 311         }
 312     }
 313
 314     @Override
 315     public boolean waitForCompletion() {
 316         try {
 317             fFinishedLatch.await();
 318         } catch (InterruptedException e) {
 319             Activator.logError("Error while waiting for module completion", e); //$NON-NLS-1$
 320         }
 321         return !fAnalysisCancelled;
 322     }
 323
 324     @Override
 325     public boolean waitForCompletion(IProgressMonitor monitor) {
 326         try {
 327             while (!fFinishedLatch.await(500, TimeUnit.MILLISECONDS)) {
 328                 if (fAnalysisCancelled || monitor.isCanceled()) {
 329                     fAnalysisCancelled = true;
 330                     return false;
 331                 }
 332             }
 333         } catch (InterruptedException e) {
 334             Activator.logError("Error while waiting for module completion", e); //$NON-NLS-1$
 335         }
 336         return !fAnalysisCancelled;
 337     }
 338
 339     /**
 340      * Signal handler for trace closing
 341      *
 342      * @param signal
 343      *            Trace closed signal
 344      */
 345     @TmfSignalHandler
 346     public void traceClosed(TmfTraceClosedSignal signal) {
 347         /* Is the closing trace the one that was requested? */
 348         if (signal.getTrace() == fTrace) {
 349             cancel();
 350             fTrace = null;
 351         }
 352     }
 353
 354     /**
 355      * Returns a full help text to display
 356      *
 357      * @return Full help text for the module
 358      */
 359     protected String getFullHelpText() {
 360         return NLS.bind(Messages.TmfAbstractAnalysisModule_AnalysisModule, getName());
 361     }
 362
 363     /**
 364      * Gets a short help text, to display as header to other help text
 365      *
 366      * @param trace
 367      *            The trace to show help for
 368      *
 369      * @return Short help text describing the module
 370      */
 371     protected String getShortHelpText(ITmfTrace trace) {
 372         return NLS.bind(Messages.TmfAbstractAnalysisModule_AnalysisForTrace, getName(), trace.getName());
 373     }
 374
 375     /**
 376      * Gets the help text specific for a trace who does not have required
 377      * characteristics for module to execute
 378      *
 379      * @param trace
 380      *            The trace to apply the analysis to
 381      * @return Help text
 382      */
 383     protected String getTraceCannotExecuteHelpText(ITmfTrace trace) {
 384         return Messages.TmfAbstractAnalysisModule_AnalysisCannotExecute;
 385     }
 386
 387     @Override
 388     public String getHelpText() {
 389         return getFullHelpText();
 390     }
 391
 392     @Override
 393     public String getHelpText(ITmfTrace trace) {
 394         if (trace == null) {
 395             return getHelpText();
 396         }
 397         String text = getShortHelpText(trace);
 398         if (!canExecute(trace)) {
 399             text = text + getTraceCannotExecuteHelpText(trace);
 400         }
 401         return text;
 402     }
 403
 404 }