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

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