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