lttng: More luna annotation updates

[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 1f16da37bf07576fa0ff243d6e331007b673b937..a36b3e039a473c0a62b0159652a5eb007eb68890 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
@@ -1,11 +1,11 @@
 /*******************************************************************************
- * Copyright (c) 2012 Ericsson
- * 
+ * Copyright (c) 2012, 2013 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
  *******************************************************************************/
@@ -13,52 +13,102 @@
 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.timestamp.ITmfTimestamp;
+import org.eclipse.linuxtools.tmf.core.timestamp.TmfTimeRange;
 
 /**
- * The generic trace indexer in TMF.
- * 
+ * 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>> {
+public interface ITmfTraceIndexer {
 
     /**
      * 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
+     *            Should we block the calling thread until the build is
+     *            complete?
+     * @since 2.0
      */
-    public void buildIndex(boolean waitForCompletion);
-    
+    void buildIndex(long offset, TmfTimeRange range, boolean waitForCompletion);
+
     /**
-     * Adds an entry to the trace index. 
-     * 
-     * @param context
-     * @param timestamp
+     * 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 void updateIndex(ITmfContext context, ITmfTimestamp timestamp);
-    
+    boolean isIndexing();
+
+    /**
+     * Adds an entry to the trace index.
+     *
+     * @param context The trace context to save
+     * @param timestamp The timestamp matching this context
+     * @since 2.0
+     */
+    void updateIndex(ITmfContext context, ITmfTimestamp timestamp);
+
     /**
      * Returns the context of the checkpoint immediately preceding the requested
      * timestamp (or at the timestamp if it coincides with a checkpoint).
-     * 
+     *
      * @param timestamp the requested timestamp
      * @return the checkpoint context
+     * @since 2.0
      */
-    public ITmfContext seekIndex(ITmfTimestamp timestamp);
+    ITmfContext seekIndex(ITmfTimestamp timestamp);
 
     /**
      * Returns the context of the checkpoint immediately preceding the requested
      * rank (or at rank if it coincides with a checkpoint).
-     * 
+     *
      * @param rank the requested event rank
      * @return the checkpoint context
      */
-    public ITmfContext seekIndex(long rank);
+    ITmfContext seekIndex(long rank);
+
+    /**
+     * Perform cleanup when the indexer is no longer required.
+     */
+    void dispose();
 
 }