tmf/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          * Background, 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      * Gets the dependency level. Use different dependency level for requests
  72      * that have a dependency with each other. They will be serviced separately.
  73      *
  74      * @return dependency
  75      * @since 2.0
  76      */
  77     default int getDependencyLevel() {
  78         return 0;
  79     }
  80
  81     /**
  82      * @return the index of the first event requested
  83      */
  84     long getIndex();
  85
  86     /**
  87      * @return the number of requested events
  88      */
  89     int getNbRequested();
  90
  91     /**
  92      * @return the number of events read so far
  93      */
  94     int getNbRead();
  95
  96     /**
  97      * @return the requested time range
  98      */
  99     TmfTimeRange getRange();
 100
 101     /**
 102      * @return the event provider filter to verify if an event is provided by
 103      *         the relevant event provider.
 104      */
 105     ITmfFilter getProviderFilter();
 106
 107     /**
 108      * Sets a provider filter to verify if an event is provided by the relevant
 109      * event provider.
 110      *
 111      * @param filter
 112      *            event provider filter to set
 113      */
 114     void setProviderFilter(ITmfFilter filter);
 115
 116     // ------------------------------------------------------------------------
 117     // Request state predicates
 118     // ------------------------------------------------------------------------
 119
 120     /**
 121      * @return true if the request is still active
 122      */
 123     boolean isRunning();
 124
 125     /**
 126      * @return true if the request is completed
 127      */
 128     boolean isCompleted();
 129
 130     /**
 131      * @return true if the request has failed
 132      */
 133     boolean isFailed();
 134
 135     /**
 136      * @return true if the request was cancelled
 137      */
 138     boolean isCancelled();
 139
 140     // ------------------------------------------------------------------------
 141     // Data handling
 142     // ------------------------------------------------------------------------
 143
 144     /**
 145      * Process the piece of data
 146      *
 147      * @param event
 148      *            The trace event to process
 149      */
 150     void handleData(@NonNull ITmfEvent event);
 151
 152     // ------------------------------------------------------------------------
 153     // Request notifications
 154     // ------------------------------------------------------------------------
 155
 156     /**
 157      * Request processing start notification
 158      */
 159     void handleStarted();
 160
 161     /**
 162      * Request processing completion notification
 163      */
 164     void handleCompleted();
 165
 166     /**
 167      * Request successful completion notification
 168      */
 169     void handleSuccess();
 170
 171     /**
 172      * Request failure notification
 173      */
 174     void handleFailure();
 175
 176     /**
 177      * Request cancellation notification
 178      */
 179     void handleCancel();
 180
 181     /**
 182      * To suspend the client thread until the request completes (or is
 183      * cancelled).
 184      *
 185      * @throws InterruptedException
 186      *             thrown if the request was cancelled
 187      */
 188     void waitForCompletion() throws InterruptedException;
 189
 190     // ------------------------------------------------------------------------
 191     // Request state modifiers
 192     // ------------------------------------------------------------------------
 193
 194     /**
 195      * Put the request in the running state
 196      */
 197     void start();
 198
 199     /**
 200      * Put the request in the completed state
 201      */
 202     void done();
 203
 204     /**
 205      * Put the request in the failed completed state
 206      */
 207     void fail();
 208
 209     /**
 210      * Put the request in the cancelled completed state
 211      */
 212     void cancel();
 213
 214     // ------------------------------------------------------------------------
 215     // Others
 216     // ------------------------------------------------------------------------
 217
 218     /**
 219      * This method is called by the event provider to set the index
 220      * corresponding to the time range start time
 221      *
 222      * @param index
 223      *            The start time index
 224      */
 225     void setStartIndex(int index);
 226
 227 }