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

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