- Minor modification of the FW API (better trace/parser integration)

[deliverable/tracecompass.git] / org.eclipse.linuxtools.tmf / src / org / eclipse / linuxtools / tmf / trace / ITmfTrace.java

diff --git a/org.eclipse.linuxtools.tmf/src/org/eclipse/linuxtools/tmf/trace/ITmfTrace.java b/org.eclipse.linuxtools.tmf/src/org/eclipse/linuxtools/tmf/trace/ITmfTrace.java
index feb9d09af5810c282ef13dfec87bf52dc2ffebae..3d12f29c2bd304324f510c435c0ed5a9f3d7b394 100644 (file)
--- a/org.eclipse.linuxtools.tmf/src/org/eclipse/linuxtools/tmf/trace/ITmfTrace.java
+++ b/org.eclipse.linuxtools.tmf/src/org/eclipse/linuxtools/tmf/trace/ITmfTrace.java
@@ -17,7 +17,7 @@ import org.eclipse.linuxtools.tmf.event.TmfTimeRange;
 import org.eclipse.linuxtools.tmf.event.TmfTimestamp;
 
 /**
- * <b><u>ITmfEventStream</u></b>
+ * <b><u>ITmfTrace</u></b>
  * <p>
  * TODO: Implement me. Please.
  */
@@ -26,19 +26,19 @@ public interface ITmfTrace {
        /**
         * <b><u>StreamContext</u></b>
         * <p>
-        * Stream context keeper to avoid conflicting, concurrent accesses to the
-        * underlying stream. 
+        * Stream context keeper. Used to prevent conflicting, concurrent accesses
+        * to the underlying trace. 
         */
-       public class StreamContext {
+       public class TmfTraceContext {
                public Object location;
                public int    index;
 
-               public StreamContext(Object loc, int ind) {
+               public TmfTraceContext(Object loc, int ind) {
                        location = loc;
                        index = ind;
                }
 
-               public StreamContext(StreamContext other) {
+               public TmfTraceContext(TmfTraceContext other) {
                        if (other != null) {
                                location = other.location;
                                index = other.index;
@@ -47,56 +47,75 @@ public interface ITmfTrace {
        }
     
        /**
-        * @return 
+        * @return the trace name 
         */
        public String getName();
     
        /**
-        * @return the number of events in the stream
+        * @return the number of events in the trace
         */
        public int getNbEvents();
     
        /**
-        * @return the stream time range
+        * Trace time range handlers
         */
-    public TmfTimeRange getTimeRange();
+       public void setTimeRange(TmfTimeRange range);
+       public void setStartTime(TmfTimestamp startTime);
+       public void setEndTime(TmfTimestamp endTime);
 
-//     /**
-//      * @return The stream time range
-//      */
-//    public Map<String, Object> getAttributes();
+       public TmfTimeRange getTimeRange();
+    public TmfTimestamp getStartTime();
+    public TmfTimestamp getEndTime();
 
     /**
-     * Positions the stream at the first event with timestamp.
+     * Positions the trace at the first event with the specified
+     * timestamp or index (i.e. the nth event in the trace)
      * 
      * @param timestamp
+     * @param index
      * @return a context object for subsequent reads
      */
-    public StreamContext seekEvent(TmfTimestamp timestamp);
-    public StreamContext seekEvent(int index);
+    public TmfTraceContext seekEvent(TmfTimestamp timestamp);
+    public TmfTraceContext seekEvent(int index);
 
     /**
-     * Reads and the next event on the stream and updates the context.
-     * If there is no event left, return null.
+     * These functions handle the mapping between an abstract trace
+     * and the actual implementation.
+     * 
+     * <code>parseEvent()</code> parses the event at the current
+     * trace location.
+     * 
+     * <code>processEvent()</code> is a hook for application
+     * specific processing once the event has been read.
+     */
+    public Object getCurrentLocation();
+    public TmfTraceContext seekLocation(Object location);
+    public TmfEvent parseNextEvent();
+       public void processEvent(TmfEvent event);
+
+    /**
+     * These functions return the event pointed by the supplied context
+     * (or null if no event left).
+     * 
+     * The context is updated to point to the next trace event, expect
+     * for tpeekEvent() which doesn't update the context.
      * 
      * @return the next event in the stream
      */
-    public TmfEvent peekEvent(StreamContext context);
-    public TmfEvent getEvent(StreamContext context, TmfTimestamp timestamp);
-    public TmfEvent getEvent(StreamContext context, int index);
-    public TmfEvent getNextEvent(StreamContext context);
+    public TmfEvent peekEvent(TmfTraceContext context);
+    public TmfEvent getEvent(TmfTraceContext context, TmfTimestamp timestamp);
+    public TmfEvent getEvent(TmfTraceContext context, int index);
+    public TmfEvent getNextEvent(TmfTraceContext context);
 
     /**
-     * Parse the stream and creates the checkpoint structure.
+     * Index the stream and creates the checkpoint structure.
      * Normally invoked once at the creation of the event stream.
      */
-    public void indexStream(boolean waitForCompletion);
-
-    public Object getCurrentLocation();
-    public StreamContext seekLocation(Object location);
+    public void indexStream();
 
     /**
-     * Returns the index of the event at that timestamp
+     * Returns the index of the first event at the supplied timestamp.
+     * If there is no such event, return the next one (null if none left).
      * 
      * @param timestamp
      * @return
@@ -105,6 +124,7 @@ public interface ITmfTrace {
 
        /**
         * Returns the timestamp of the event at position [index]
+        * (null if none left). 
         * 
         * @param index the event index
         * @return the corresponding timestamp