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

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