org.eclipse.tracecompass.tmf.core/src/org/eclipse/tracecompass/tmf/core/request/ITmfEventRequest.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 - Merge with ITmfDataRequest
  12  *******************************************************************************/
  13
  14 package org.eclipse.tracecompass.tmf.core.request;
  15
  16 import org.eclipse.jdt.annotation.NonNull;
  17 import org.eclipse.tracecompass.tmf.core.event.ITmfEvent;
  18 import org.eclipse.tracecompass.tmf.core.filter.ITmfFilter;
  19 import org.eclipse.tracecompass.tmf.core.timestamp.TmfTimeRange;
  20
  21 /**
  22  * The TMF event request
  23  *
  24  * @author Francois Chouinard
  25  */
  26 public interface ITmfEventRequest {
  27
  28     // ------------------------------------------------------------------------
  29     // Constants
  30     // ------------------------------------------------------------------------
  31
  32     /**
  33      * The request count for all the events
  34      */
  35     static final int ALL_DATA = Integer.MAX_VALUE;
  36
  37     /**
  38      * The request execution type/priority
  39      */
  40     enum ExecutionType {
  41         /**
  42          * Backgroung, long-running, lower priority request
  43          */
  44         BACKGROUND,
  45         /**
  46          * Foreground, short-running, high priority request
  47          */
  48         FOREGROUND
  49     }
  50
  51     // ------------------------------------------------------------------------
  52     // Accessors
  53     // ------------------------------------------------------------------------
  54
  55     /**
  56      * @return request data type (T)
  57      */
  58     Class<? extends ITmfEvent> getDataType();
  59
  60     /**
  61      * @return request ID
  62      */
  63     int getRequestId();
  64
  65     /**
  66      * @return request ID
  67      */
  68     ExecutionType getExecType();
  69
  70     /**
  71      * @return the index of the first event requested
  72      */
  73     long getIndex();
  74
  75     /**
  76      * @return the number of requested events
  77      */
  78     int getNbRequested();
  79
  80     /**
  81      * @return the number of events read so far
  82      */
  83     int getNbRead();
  84
  85     /**
  86      * @return the requested time range
  87      */
  88     TmfTimeRange getRange();
  89
  90     /**
  91      * @return the event provider filter to verify if an event is provided by
  92      *         the relevant event provider.
  93      */
  94     ITmfFilter getProviderFilter();
  95
  96     /**
  97      * Sets a provider filter to verify if an event is provided by the relevant
  98      * event provider.
  99      *
 100      * @param filter
 101      *            event provider filter to set
 102      */
 103     void setProviderFilter(ITmfFilter filter);
 104
 105     // ------------------------------------------------------------------------
 106     // Request state predicates
 107     // ------------------------------------------------------------------------
 108
 109     /**
 110      * @return true if the request is still active
 111      */
 112     boolean isRunning();
 113
 114     /**
 115      * @return true if the request is completed
 116      */
 117     boolean isCompleted();
 118
 119     /**
 120      * @return true if the request has failed
 121      */
 122     boolean isFailed();
 123
 124     /**
 125      * @return true if the request was cancelled
 126      */
 127     boolean isCancelled();
 128
 129     // ------------------------------------------------------------------------
 130     // Data handling
 131     // ------------------------------------------------------------------------
 132
 133     /**
 134      * Process the piece of data
 135      *
 136      * @param event
 137      *            The trace event to process
 138      */
 139     void handleData(@NonNull ITmfEvent event);
 140
 141     // ------------------------------------------------------------------------
 142     // Request notifications
 143     // ------------------------------------------------------------------------
 144
 145     /**
 146      * Request processing start notification
 147      */
 148     void handleStarted();
 149
 150     /**
 151      * Request processing completion notification
 152      */
 153     void handleCompleted();
 154
 155     /**
 156      * Request successful completion notification
 157      */
 158     void handleSuccess();
 159
 160     /**
 161      * Request failure notification
 162      */
 163     void handleFailure();
 164
 165     /**
 166      * Request cancellation notification
 167      */
 168     void handleCancel();
 169
 170     /**
 171      * To suspend the client thread until the request completes (or is
 172      * cancelled).
 173      *
 174      * @throws InterruptedException
 175      *             thrown if the request was cancelled
 176      */
 177     void waitForCompletion() throws InterruptedException;
 178
 179     // ------------------------------------------------------------------------
 180     // Request state modifiers
 181     // ------------------------------------------------------------------------
 182
 183     /**
 184      * Put the request in the running state
 185      */
 186     void start();
 187
 188     /**
 189      * Put the request in the completed state
 190      */
 191     void done();
 192
 193     /**
 194      * Put the request in the failed completed state
 195      */
 196     void fail();
 197
 198     /**
 199      * Put the request in the cancelled completed state
 200      */
 201     void cancel();
 202
 203     // ------------------------------------------------------------------------
 204     // Others
 205     // ------------------------------------------------------------------------
 206
 207     /**
 208      * This method is called by the event provider to set the index
 209      * corresponding to the time range start time
 210      *
 211      * @param index
 212      *            The start time index
 213      */
 214     void setStartIndex(int index);
 215
 216 }