org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/trace/ITmfTraceIndexer.java

   1 /*******************************************************************************
   2  * Copyright (c) 2012, 2013 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.trace;
  14
  15 import org.eclipse.linuxtools.tmf.core.event.ITmfEvent;
  16 import org.eclipse.linuxtools.tmf.core.timestamp.ITmfTimestamp;
  17 import org.eclipse.linuxtools.tmf.core.timestamp.TmfTimeRange;
  18
  19 /**
  20  * The generic trace indexer in TMF with support for incremental indexing.
  21  *
  22  * @version 1.0
  23  * @author Francois Chouinard
  24  *
  25  * @see ITmfTrace
  26  * @see ITmfEvent
  27  */
  28 public interface ITmfTraceIndexer {
  29
  30     /**
  31      * Start an asynchronous index building job and waits for the job completion
  32      * if required. Typically, the indexing job sends notifications at regular
  33      * intervals to indicate its progress.
  34      * <p>
  35      * <b>Example 1</b>: Index a whole trace asynchronously
  36      *
  37      * <pre>
  38      * trace.getIndexer().buildIndex(0, TmfTimeRange.ETERNITY, false);
  39      * </pre>
  40      *
  41      * <b>Example 2</b>: Index a whole trace synchronously
  42      *
  43      * <pre>
  44      * trace.getIndexer().buildIndex(0, TmfTimeRange.ETERNITY, true);
  45      * </pre>
  46      *
  47      * <b>Example 3</b>: Index a trace asynchronously, starting at rank 100
  48      *
  49      * <pre>
  50      * trace.getIndexer().buildIndex(100, TmfTimeRange.ETERNITY, false);
  51      * </pre>
  52      *
  53      * <b>Example 4</b>: Index a trace asynchronously, starting at rank 100 for
  54      * events between T1 and T2 (inclusive). This is used for incremental
  55      * indexing.
  56      *
  57      * <pre>
  58      * TmfTimeRange range = new TmfTimeRange(T1, T2);
  59      * trace.getIndexer().buildIndex(100, range, false);
  60      * </pre>
  61      *
  62      * @param offset
  63      *            The offset of the first event to consider
  64      * @param range
  65      *            The time range to consider
  66      * @param waitForCompletion
  67      *            Should we block the calling thread until the build is
  68      *            complete?
  69      * @since 2.0
  70      */
  71     public void buildIndex(long offset, TmfTimeRange range, boolean waitForCompletion);
  72
  73     /**
  74      * Indicates that the indexer is busy indexing the trace.
  75      * Will always return false if the indexing is done synchronously.
  76      *
  77      * @return the state of the indexer (indexing or not)
  78      */
  79     public boolean isIndexing();
  80
  81     /**
  82      * Adds an entry to the trace index.
  83      *
  84      * @param context The trace context to save
  85      * @param timestamp The timestamp matching this context
  86      * @since 2.0
  87      */
  88     public void updateIndex(ITmfContext context, ITmfTimestamp timestamp);
  89
  90     /**
  91      * Returns the context of the checkpoint immediately preceding the requested
  92      * timestamp (or at the timestamp if it coincides with a checkpoint).
  93      *
  94      * @param timestamp the requested timestamp
  95      * @return the checkpoint context
  96      * @since 2.0
  97      */
  98     public ITmfContext seekIndex(ITmfTimestamp timestamp);
  99
 100     /**
 101      * Returns the context of the checkpoint immediately preceding the requested
 102      * rank (or at rank if it coincides with a checkpoint).
 103      *
 104      * @param rank the requested event rank
 105      * @return the checkpoint context
 106      */
 107     public ITmfContext seekIndex(long rank);
 108
 109     /**
 110      * Perform cleanup when the indexer is no longer required.
 111      */
 112     public void dispose();
 113
 114 }