tmf/org.eclipse.tracecompass.tmf.core/src/org/eclipse/tracecompass/tmf/core/request/TmfEventRequest.java

   1 /*******************************************************************************
   2  * Copyright (c) 2009, 2015 Ericsson
   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  *   Francois Chouinard - Initial API and implementation
  11  *   Alexandre Montplaisir - Consolidate constructors, merge with TmfDataRequest
  12  *******************************************************************************/
  13
  14 package org.eclipse.tracecompass.tmf.core.request;
  15
  16 import java.util.concurrent.CountDownLatch;
  17
  18 import org.eclipse.jdt.annotation.Nullable;
  19 import org.eclipse.tracecompass.internal.tmf.core.TmfCoreTracer;
  20 import org.eclipse.tracecompass.tmf.core.event.ITmfEvent;
  21 import org.eclipse.tracecompass.tmf.core.filter.ITmfFilter;
  22 import org.eclipse.tracecompass.tmf.core.timestamp.TmfTimeRange;
  23
  24 /**
  25  * TmfEventRequest's are used to obtain series of events from an event provider.
  26  * Open ranges can be used, especially for continuous streaming.
  27  * <p>
  28  * The request is processed asynchronously by a TmfEventProvider and, as events
  29  * become available, handleData() is invoked synchronously for each one.
  30  * <p>
  31  * The TmfEventProvider indicates that the request is completed by calling
  32  * done(). The request can be cancelled at any time with cancel().
  33  * <p>
  34  * Typical usage:
  35  *
  36  * <pre>
  37  * <code>
  38  * TmfEventRequest request = new TmfEventRequest(DataType.class, range, startIndex, nbEvents, priority) {
  39  *
  40  *     public void handleData(ITmfEvent event) {
  41  *         // do something with the event
  42  *     }
  43  *
  44  *     public void handleSuccess() {
  45  *         // callback for when the request completes successfully
  46  *     }
  47  *
  48  *     public void handleFailure() {
  49  *         // callback for when the request fails due to an error
  50  *     }
  51  *
  52  *     public void handleCancel() {
  53  *         // callback for when the request is cancelled via .cancel()
  54  *     }
  55  *
  56  * };
  57  *
  58  * eventProvider.sendRequest(request);
  59  * </code>
  60  * </pre>
  61  *
  62  *
  63  * TODO: Implement request failures (codes, etc...)
  64  *
  65  * @author Francois Chouinard
  66  */
  67 public abstract class TmfEventRequest implements ITmfEventRequest {
  68
  69     // ------------------------------------------------------------------------
  70     // Constants
  71     // ------------------------------------------------------------------------
  72
  73     private static int fRequestNumber = 0;
  74
  75     // ------------------------------------------------------------------------
  76     // Attributes
  77     // ------------------------------------------------------------------------
  78
  79     private final Class<? extends ITmfEvent> fDataType;
  80     private final ExecutionType fExecType;
  81
  82     /** A unique request ID */
  83     private final int fRequestId;
  84
  85     /** The requested events time range */
  86     private final TmfTimeRange fRange;
  87
  88     /** The index (rank) of the requested event */
  89     protected long fIndex;
  90
  91     /** The number of requested events (ALL_DATA for all) */
  92     protected int fNbRequested;
  93
  94     /** The number of reads so far */
  95     private int fNbRead;
  96
  97     private final CountDownLatch startedLatch = new CountDownLatch(1);
  98     private final CountDownLatch completedLatch = new CountDownLatch(1);
  99
 100     private boolean fRequestRunning;
 101     private boolean fRequestCompleted;
 102     private boolean fRequestFailed;
 103     private boolean fRequestCanceled;
 104
 105     private ITmfFilter fEventFilter;
 106
 107     private int fDependencyLevel;
 108
 109     private @Nullable Throwable fFailureCause;
 110
 111     // ------------------------------------------------------------------------
 112     // Constructors
 113     // ------------------------------------------------------------------------
 114
 115     /**
 116      * Request 'n' events of a given type, for the *whole* trace, at the given
 117      * priority.
 118      *
 119      * @param dataType
 120      *            The requested data type.
 121      * @param index
 122      *            The index of the first event to retrieve. You can use '0' to
 123      *            start at the beginning of the trace.
 124      * @param nbRequested
 125      *            The number of events requested. You can use
 126      *            {@link TmfEventRequest#ALL_DATA} to indicate you want all
 127      *            events in the trace.
 128      * @param priority
 129      *            The requested execution priority.
 130      */
 131     public TmfEventRequest(Class<? extends ITmfEvent> dataType,
 132             long index,
 133             int nbRequested,
 134             ExecutionType priority) {
 135         this(dataType, TmfTimeRange.ETERNITY, index, nbRequested, priority);
 136     }
 137
 138     /**
 139      * Request 'n' events of a given type, for the given time range, at the
 140      * given priority.
 141      *
 142      * @param dataType
 143      *            The requested data type.
 144      * @param range
 145      *            The time range of the requested events. You can use
 146      *            {@link TmfTimeRange#ETERNITY} to indicate you want to cover
 147      *            the whole trace.
 148      * @param index
 149      *            The index of the first event to retrieve. You can use '0' to
 150      *            start at the beginning of the trace.
 151      * @param nbRequested
 152      *            The number of events requested. You can use
 153      *            {@link TmfEventRequest#ALL_DATA} to indicate you want all
 154      *            events in the time range.
 155      * @param priority
 156      *            The requested execution priority.
 157      */
 158     public TmfEventRequest(Class<? extends ITmfEvent> dataType,
 159             TmfTimeRange range,
 160             long index,
 161             int nbRequested,
 162             ExecutionType priority) {
 163         this(dataType, range, index, nbRequested, priority, 0);
 164     }
 165
 166     /**
 167      * Request 'n' events of a given type, for the given time range, at the
 168      * given priority.
 169      *
 170      * @param dataType
 171      *            The requested data type.
 172      * @param range
 173      *            The time range of the requested events. You can use
 174      *            {@link TmfTimeRange#ETERNITY} to indicate you want to cover
 175      *            the whole trace.
 176      * @param index
 177      *            The index of the first event to retrieve. You can use '0' to
 178      *            start at the beginning of the trace.
 179      * @param nbRequested
 180      *            The number of events requested. You can use
 181      *            {@link TmfEventRequest#ALL_DATA} to indicate you want all
 182      *            events in the time range.
 183      * @param priority
 184      *            The requested execution priority.
 185      * @param dependencyLevel
 186      *            The dependency level. Use different dependency level for
 187      *            requests that have a dependency with each other. They will
 188      *            be serviced separately.
 189      * @since 2.0
 190      */
 191     public TmfEventRequest(Class<? extends ITmfEvent> dataType,
 192             TmfTimeRange range,
 193             long index,
 194             int nbRequested,
 195             ExecutionType priority,
 196             int dependencyLevel) {
 197
 198         synchronized (TmfEventRequest.class) {
 199             fRequestId = fRequestNumber++;
 200         }
 201         fDataType = dataType;
 202         fIndex = index;
 203         fNbRequested = nbRequested;
 204         fExecType = priority;
 205         fRange = range;
 206         fNbRead = 0;
 207         fDependencyLevel = dependencyLevel;
 208
 209         fRequestRunning = false;
 210         fRequestCompleted = false;
 211         fRequestFailed = false;
 212         fRequestCanceled = false;
 213
 214         /* Setup the request tracing if it's enabled */
 215         if (TmfCoreTracer.isRequestTraced()) {
 216             String type = getClass().getName();
 217             type = type.substring(type.lastIndexOf('.') + 1);
 218             @SuppressWarnings("nls")
 219             String message = "CREATED "
 220                     + (getExecType() == ExecutionType.BACKGROUND ? "(BG)" : "(FG)")
 221                     + " Type=" + type + " Index=" + getIndex() + " NbReq=" + getNbRequested()
 222                     + " Range=" + getRange()
 223                     + " DataType=" + getDataType().getSimpleName()
 224                     + " DependencyLevel= " + fDependencyLevel;
 225             TmfCoreTracer.traceRequest(fRequestId, message);
 226         }
 227     }
 228
 229     // ------------------------------------------------------------------------
 230     // Accessors
 231     // ------------------------------------------------------------------------
 232
 233     @Override
 234     public int getRequestId() {
 235         return fRequestId;
 236     }
 237
 238     @Override
 239     public long getIndex() {
 240         return fIndex;
 241     }
 242
 243     @Override
 244     public ExecutionType getExecType() {
 245         return fExecType;
 246     }
 247
 248     @Override
 249     public int getNbRequested() {
 250         return fNbRequested;
 251     }
 252
 253     @Override
 254     public synchronized int getNbRead() {
 255         return fNbRead;
 256     }
 257
 258     @Override
 259     public synchronized boolean isRunning() {
 260         return fRequestRunning;
 261     }
 262
 263     @Override
 264     public synchronized boolean isCompleted() {
 265         return fRequestCompleted;
 266     }
 267
 268     @Override
 269     public synchronized boolean isFailed() {
 270         return fRequestFailed;
 271     }
 272
 273     @Override
 274     public synchronized boolean isCancelled() {
 275         return fRequestCanceled;
 276     }
 277
 278     @Override
 279     public Class<? extends ITmfEvent> getDataType() {
 280         return fDataType;
 281     }
 282
 283     @Override
 284     public TmfTimeRange getRange() {
 285         return fRange;
 286     }
 287
 288     @Override
 289     public ITmfFilter getProviderFilter() {
 290         return fEventFilter;
 291     }
 292
 293     @Override
 294     public void setProviderFilter(ITmfFilter provider) {
 295         fEventFilter = provider;
 296     }
 297
 298     /** @since 2.0 */
 299     @Override
 300     public int getDependencyLevel() {
 301         return fDependencyLevel;
 302     }
 303
 304     /**
 305      * @since 2.0
 306      */
 307     @Override
 308     public @Nullable Throwable getFailureCause() {
 309         return fFailureCause;
 310     }
 311
 312     // ------------------------------------------------------------------------
 313     // Setters
 314     // ------------------------------------------------------------------------
 315
 316     /**
 317      * This method is called by the event provider to set the index
 318      * corresponding to the time range start time
 319      *
 320      * @param index
 321      *            The start time index
 322      */
 323     protected void setIndex(int index) {
 324         fIndex = index;
 325     }
 326
 327     @Override
 328     public void setStartIndex(int index) {
 329         setIndex(index);
 330     }
 331
 332     // ------------------------------------------------------------------------
 333     // Operators
 334     // ------------------------------------------------------------------------
 335
 336     @Override
 337     public void handleData(ITmfEvent event) {
 338         fNbRead++;
 339     }
 340
 341     @Override
 342     public void handleStarted() {
 343         if (TmfCoreTracer.isRequestTraced()) {
 344             TmfCoreTracer.traceRequest(getRequestId(), "STARTED"); //$NON-NLS-1$
 345         }
 346     }
 347
 348     @Override
 349     public void handleCompleted() {
 350         boolean requestFailed = false;
 351         boolean requestCanceled = false;
 352         synchronized (this) {
 353             requestFailed = fRequestFailed;
 354             requestCanceled = fRequestCanceled;
 355         }
 356
 357         if (requestFailed) {
 358             handleFailure();
 359         } else if (requestCanceled) {
 360             handleCancel();
 361         } else {
 362             handleSuccess();
 363         }
 364         if (TmfCoreTracer.isRequestTraced()) {
 365             TmfCoreTracer.traceRequest(getRequestId(), "COMPLETED (" + fNbRead + " events read)"); //$NON-NLS-1$ //$NON-NLS-2$
 366         }
 367     }
 368
 369     @Override
 370     public void handleSuccess() {
 371         if (TmfCoreTracer.isRequestTraced()) {
 372             TmfCoreTracer.traceRequest(getRequestId(), "SUCCEEDED"); //$NON-NLS-1$
 373         }
 374     }
 375
 376     @Override
 377     public void handleFailure() {
 378         if (TmfCoreTracer.isRequestTraced()) {
 379             TmfCoreTracer.traceRequest(getRequestId(), "FAILED"); //$NON-NLS-1$
 380         }
 381     }
 382
 383     @Override
 384     public void handleCancel() {
 385         if (TmfCoreTracer.isRequestTraced()) {
 386             TmfCoreTracer.traceRequest(getRequestId(), "CANCELLED"); //$NON-NLS-1$
 387         }
 388     }
 389
 390     /**
 391      * To suspend the client thread until the request starts (or is canceled).
 392      *
 393      * @throws InterruptedException
 394      *             If the thread was interrupted while waiting
 395      */
 396     public void waitForStart() throws InterruptedException {
 397         while (!fRequestRunning) {
 398             startedLatch.await();
 399         }
 400     }
 401
 402     @Override
 403     public void waitForCompletion() throws InterruptedException {
 404         while (!fRequestCompleted) {
 405             completedLatch.await();
 406         }
 407     }
 408
 409     @Override
 410     public void start() {
 411         synchronized (this) {
 412             fRequestRunning = true;
 413         }
 414         handleStarted();
 415         startedLatch.countDown();
 416     }
 417
 418     @Override
 419     public void done() {
 420         synchronized (this) {
 421             if (!fRequestCompleted) {
 422                 fRequestRunning = false;
 423                 fRequestCompleted = true;
 424             } else {
 425                 return;
 426             }
 427         }
 428         try {
 429             handleCompleted();
 430         } finally {
 431             completedLatch.countDown();
 432         }
 433     }
 434
 435     /**
 436      * @since 2.0
 437      */
 438     @Override
 439     public void fail(Exception e) {
 440         synchronized (this) {
 441             fRequestFailed = true;
 442         }
 443         fFailureCause = e;
 444         done();
 445     }
 446
 447     @Override
 448     public void cancel() {
 449         synchronized (this) {
 450             fRequestCanceled = true;
 451         }
 452         done();
 453     }
 454
 455     // ------------------------------------------------------------------------
 456     // Object
 457     // ------------------------------------------------------------------------
 458
 459     @Override
 460     public String toString() {
 461         String name = getClass().getName();
 462         int dot = name.lastIndexOf('.');
 463         if (dot >= 0) {
 464             name = name.substring(dot + 1);
 465         }
 466         return '[' + name + '(' + getRequestId() + ',' + getDataType().getSimpleName() +
 467                 ',' + getExecType() + ',' + getRange() + ',' + getIndex() +
 468                 ',' + getNbRequested() + ','+ getDependencyLevel() + ")]"; //$NON-NLS-1$
 469     }
 470
 471 }