Revert "Fix for bug 381411: Implement ranked location in experiment."

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

diff --git a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/trace/ITmfTraceIndexer.java b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/trace/ITmfTraceIndexer.java
index dcf878f49a23b24ad94cf16f3f3e968d362d83b9..e0bec7cc7046cb6cdcb4e830dc2a7e936b7b65b6 100644 (file)
--- a/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/trace/ITmfTraceIndexer.java
+++ b/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/trace/ITmfTraceIndexer.java
@@ -14,10 +14,16 @@ package org.eclipse.linuxtools.tmf.core.trace;
 
 import org.eclipse.linuxtools.tmf.core.event.ITmfEvent;
 import org.eclipse.linuxtools.tmf.core.event.ITmfTimestamp;
+import org.eclipse.linuxtools.tmf.core.event.TmfTimeRange;
 
 /**
- * <b><u>ITmfTraceIndexer</u></b>
- * <p>
+ * The generic trace indexer in TMF with support for incremental indexing.
+ * 
+ * @version 1.0
+ * @author Francois Chouinard
+ *
+ * @see ITmfTrace
+ * @see ITmfEvent
  */
 public interface ITmfTraceIndexer<T extends ITmfTrace<ITmfEvent>> {
 
@@ -25,19 +31,47 @@ public interface ITmfTraceIndexer<T extends ITmfTrace<ITmfEvent>> {
      * Start an asynchronous index building job and waits for the job completion
      * if required. Typically, the indexing job sends notifications at regular
      * intervals to indicate its progress.
+     * <p>
+     * <b>Example 1</b>: Index a whole trace asynchronously
+     * <pre>
+     * trace.getIndexer().buildIndex(0, TmfTimeRange.ETERNITY, false);
+     * </pre>
+     * <b>Example 2</b>: Index a whole trace synchronously
+     * <pre>
+     * trace.getIndexer().buildIndex(0, TmfTimeRange.ETERNITY, true);
+     * </pre>
+     * <b>Example 3</b>: Index a trace asynchronously, starting at rank 100
+     * <pre>
+     * trace.getIndexer().buildIndex(100, TmfTimeRange.ETERNITY, false);
+     * </pre>
+     * <b>Example 4</b>: Index a trace asynchronously, starting at rank 100 for events between
+     * T1 and T2 (inclusive). This is used for incremental indexing.
+     * <pre>
+     * TmfTimeRange range = new TmfTimeRange(T1, T2);
+     * trace.getIndexer().buildIndex(100, range, false);
+     * </pre>
      * 
+     * @param offset The offset of the first event to consider
+     * @param range The time range to consider
      * @param waitForCompletion
      */
-    public void buildIndex(boolean waitForCompletion);
+    public void buildIndex(long offset, TmfTimeRange range, boolean waitForCompletion);
+    
+    /**
+     * Indicates that the indexer is busy indexing the trace.
+     * Will always return false if the indexing is done synchronously. 
+     * 
+     * @return the state of the indexer (indexing or not)
+     */
+    public boolean isIndexing();
     
     /**
      * Adds an entry to the trace index. 
      * 
      * @param context
-     * @param rank
      * @param timestamp
      */
-    public void updateIndex(ITmfContext context, long rank, ITmfTimestamp timestamp);
+    public void updateIndex(ITmfContext context, ITmfTimestamp timestamp);
     
     /**
      * Returns the context of the checkpoint immediately preceding the requested
@@ -57,4 +91,9 @@ public interface ITmfTraceIndexer<T extends ITmfTrace<ITmfEvent>> {
      */
     public ITmfContext seekIndex(long rank);
 
+    /**
+     * Perform cleanup when the indexer is no longer required.
+     */
+    public void dispose();
+
 }