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