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