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

   1 /*******************************************************************************
   2  * Copyright (c) 2009, 2011 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 java.io.FileNotFoundException;
  16
  17 import org.eclipse.core.resources.IProject;
  18 import org.eclipse.linuxtools.tmf.core.component.ITmfComponent;
  19 import org.eclipse.linuxtools.tmf.core.event.ITmfTimestamp;
  20 import org.eclipse.linuxtools.tmf.core.event.TmfEvent;
  21 import org.eclipse.linuxtools.tmf.core.event.TmfTimeRange;
  22
  23 /**
  24  * <b><u>ITmfTrace</u></b>
  25  * <p>
  26  */
  27 public interface ITmfTrace<T extends TmfEvent> extends ITmfComponent {
  28
  29     // initTrace variants
  30     public void initTrace(String path, Class<T> eventType) throws FileNotFoundException;
  31
  32     public void initTrace(String path, Class<T> eventType, int cacheSize) throws FileNotFoundException;
  33
  34     public void initTrace(String path, Class<T> eventType, boolean indexTrace) throws FileNotFoundException;
  35
  36     public void initTrace(String path, Class<T> eventType, int cacheSize, boolean indexTrace) throws FileNotFoundException;
  37
  38     public void initTrace(String path, Class<T> eventType, int cacheSize, boolean indexTrace, String name) throws FileNotFoundException;
  39
  40     // Trace type validation
  41     public boolean validate(IProject project, String path);
  42
  43     public ITmfTrace<T> copy();
  44
  45     /**
  46      * @return the trace path
  47      */
  48     public String getPath();
  49
  50     /**
  51      * @return the trace name
  52      */
  53     @Override
  54     public String getName();
  55
  56     /**
  57      * @return the cache size
  58      */
  59     public int getCacheSize();
  60
  61     /**
  62      * @return the number of events in the trace
  63      */
  64     public long getNbEvents();
  65
  66     /**
  67      * Trace time range accesses
  68      */
  69     public TmfTimeRange getTimeRange();
  70
  71     public ITmfTimestamp getStartTime();
  72
  73     public ITmfTimestamp getEndTime();
  74
  75     /**
  76      * @return the streaming interval in ms (0 if not streaming)
  77      */
  78     public long getStreamingInterval();
  79
  80     /**
  81      * Positions the trace at the first event with the specified timestamp or index (i.e. the nth event in the trace).
  82      *
  83      * Returns a context which can later be used to read the event.
  84      *
  85      * @param location
  86      * @param timestamp
  87      * @param rank
  88      * @return a context object for subsequent reads
  89      */
  90     public TmfContext seekLocation(ITmfLocation<?> location);
  91
  92     public TmfContext seekEvent(ITmfTimestamp timestamp);
  93
  94     public TmfContext seekEvent(long rank);
  95
  96     /**
  97      * Positions the trace at the event located at the specified ratio.
  98      *
  99      * Returns a context which can later be used to read the event.
 100      *
 101      * @param ratio
 102      *            a floating-point number between 0.0 (beginning) and 1.0 (end)
 103      * @return a context object for subsequent reads
 104      */
 105     public TmfContext seekLocation(double ratio);
 106
 107     /**
 108      * Returns the ratio corresponding to the specified location.
 109      *
 110      * @param location
 111      *            a trace location
 112      * @return a floating-point number between 0.0 (beginning) and 1.0 (end)
 113      */
 114     public double getLocationRatio(ITmfLocation<?> location);
 115
 116     public ITmfLocation<?> getCurrentLocation();
 117
 118     /**
 119      * Returns the rank of the first event with the requested timestamp. If none, returns the index of the next event
 120      * (if any).
 121      *
 122      * @param timestamp
 123      * @return
 124      */
 125     public long getRank(ITmfTimestamp timestamp);
 126
 127     /**
 128      * Return the event pointed by the supplied context (or null if no event left) and updates the context to the next
 129      * event.
 130      *
 131      * @return the next event in the stream
 132      */
 133     public TmfEvent getNextEvent(TmfContext context);
 134
 135     /**
 136      * Return the event pointed by the supplied context (or null if no event left) and *does not* update the context.
 137      *
 138      * @return the next event in the stream
 139      */
 140     public TmfEvent parseEvent(TmfContext context);
 141
 142 }