tmf: Fix regression in event requests

[deliverable/tracecompass.git] / org.eclipse.linuxtools.tmf.core / src / org / eclipse / linuxtools / tmf / core / request / ITmfDataRequest.java

diff --git a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/request/ITmfDataRequest.java b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/request/ITmfDataRequest.java
index 5f04f6df93d5e5bf2066faf4dd46ef27aca9c5be..f22d0ea2fba41440b9e2a0b1aa67fd4ca92e234f 100644 (file)
--- a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/request/ITmfDataRequest.java
+++ b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/request/ITmfDataRequest.java
@@ -1,11 +1,11 @@
 /*******************************************************************************
  * Copyright (c) 2009, 2010 Ericsson
- * 
+ *
  * All rights reserved. This program and the accompanying materials are
  * made available under the terms of the Eclipse Public License v1.0 which
  * accompanies this distribution, and is available at
  * http://www.eclipse.org/legal/epl-v10.html
- * 
+ *
  * Contributors:
  *   Francois Chouinard - Initial API and implementation
  *******************************************************************************/
@@ -15,18 +15,31 @@ package org.eclipse.linuxtools.tmf.core.request;
 import org.eclipse.linuxtools.tmf.core.event.ITmfEvent;
 
 /**
- * <b><u>ITmfDataRequest</u></b>
- * <p>
- * TODO: Implement me. Please.
+ * The TMF data request
+ *
+ * @version 1.0
+ * @author Francois Chouinard
  */
-public interface ITmfDataRequest<T extends ITmfEvent> {
+public interface ITmfDataRequest {
 
        // ------------------------------------------------------------------------
        // Constants
        // ------------------------------------------------------------------------
 
-    public enum ExecutionType { BACKGROUND, FOREGROUND };
-    
+    /**
+     * The request execution type/priority
+     */
+    public enum ExecutionType {
+        /**
+         * Backgroung, long-running, lower priority request
+         */
+        BACKGROUND,
+        /**
+         * Foreground, short-running, high priority request
+         */
+        FOREGROUND
+    }
+
        // ------------------------------------------------------------------------
        // Accessors
        // ------------------------------------------------------------------------
@@ -34,7 +47,7 @@ public interface ITmfDataRequest<T extends ITmfEvent> {
     /**
      * @return request data type (T)
      */
-    public Class<T> getDataType();
+    public Class<? extends ITmfEvent> getDataType();
 
     /**
      * @return request ID
@@ -67,33 +80,74 @@ public interface ITmfDataRequest<T extends ITmfEvent> {
     public int getNbRead();
 
        // ------------------------------------------------------------------------
-       // Request state
+       // Request state predicates
        // ------------------------------------------------------------------------
 
+    /**
+     * @return true if the request is still active
+     */
     public boolean isRunning();
+
+    /**
+     * @return true if the request is completed
+     */
     public boolean isCompleted();
+
+    /**
+     * @return true if the request has failed
+     */
     public boolean isFailed();
+
+    /**
+     * @return true if the request was cancelled
+     */
     public boolean isCancelled();
 
        // ------------------------------------------------------------------------
        // Data handling
        // ------------------------------------------------------------------------
 
-    public void handleData(T data);
+    /**
+     * Process the piece of data
+     *
+     * @param data the data to process
+     */
+    public void handleData(ITmfEvent data);
 
        // ------------------------------------------------------------------------
-       // Request handling
+       // Request notifications
        // ------------------------------------------------------------------------
 
+    /**
+     * Request processing start notification
+     */
     public void handleStarted();
+
+    /**
+     * Request processing completion notification
+     */
     public void handleCompleted();
+
+    /**
+     * Request successful completion notification
+     */
     public void handleSuccess();
+
+    /**
+     * Request failure notification
+     */
     public void handleFailure();
+
+    /**
+     * Request cancellation notification
+     */
     public void handleCancel();
 
     /**
      * To suspend the client thread until the request completes
      * (or is canceled).
+     *
+     * @throws InterruptedException thrown if the request was cancelled
      */
     public void waitForCompletion() throws InterruptedException;
 
@@ -101,8 +155,23 @@ public interface ITmfDataRequest<T extends ITmfEvent> {
        // Request state modifiers
        // ------------------------------------------------------------------------
 
+    /**
+     * Put the request in the running state
+     */
     public void start();
+
+    /**
+     * Put the request in the completed state
+     */
     public void done();
+
+    /**
+     * Put the request in the failed completed state
+     */
     public void fail();
+
+    /**
+     * Put the request in the cancelled completed state
+     */
     public void cancel();
 }