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

   1 /*******************************************************************************
   2  * Copyright (c) 2009, 2011, 2012 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  *   Francois Chouinard - Updated as per TMF Trace Model 1.0
  12  *******************************************************************************/
  13
  14 package org.eclipse.linuxtools.tmf.core.trace;
  15
  16 import java.io.FileNotFoundException;
  17
  18 import org.eclipse.core.resources.IProject;
  19 import org.eclipse.core.resources.IResource;
  20 import org.eclipse.linuxtools.tmf.core.component.ITmfDataProvider;
  21 import org.eclipse.linuxtools.tmf.core.event.ITmfEvent;
  22 import org.eclipse.linuxtools.tmf.core.event.ITmfTimestamp;
  23 import org.eclipse.linuxtools.tmf.core.event.TmfTimeRange;
  24
  25 /**
  26  * <b><u>ITmfTrace</u></b>
  27  * <p>
  28  * The event stream structure in TMF. In its basic form, a trace has:
  29  * <ul>
  30  * <li> the associated Eclipse resource
  31  * <li> the path to its location on the file system
  32  * <li> the type of the events it contains
  33  * <li> the number of events it contains
  34  * <li> the time range (span) of the events it contains
  35  * </ul>
  36  * Concrete ITmfTrace classes have to provide a parameter-less constructor and
  37  * an initialization method (initTace())if they are to be opened from the
  38  * Project View. Also, a validation (validate()) method has to be provided to
  39  * ensure that the trace is of the correct type.
  40  * <p>
  41  * A trace can be accessed simultaneously from multiple threads by various
  42  * application components. To avoid obvious multi-threading issues, the trace
  43  * uses an ITmfContext as a synchronization aid for its read operations.
  44  * <p>
  45  * A proper ITmfContext can be obtained by performing a seek operation on the
  46  * trace. Seek operations can be performed for a particular event (by rank or
  47  * timestamp) or for a plain trace location.
  48  * <p>
  49  * <b>Example 1</b>: Read a whole trace
  50  * <pre>
  51  * ITmfContext context = trace.seekLocationt(null);
  52  * ITmfEvent event = trace.getEvent(context);
  53  * while (event != null) {
  54  *     // Do something ...
  55  *     event = trace.getEvent(context);
  56  * }
  57  * </pre>
  58  * <b>Example 2</b>: Process 50 events starting from the 1000th event
  59  * <pre>
  60  * int nbEventsRead = 0;
  61  * ITmfContext context = trace.seekEvent(1000);
  62  * ITmfEvent event = trace.getEvent(context);
  63  * while (event != null && nbEventsRead < 50) {
  64  *     nbEventsRead++;
  65  *     // Do something ...
  66  *     event = trace.getEvent(context);
  67  * }
  68  * </pre>
  69  * <b>Example 3</b>: Process the events between 2 timestamps (inclusive)
  70  * <pre>
  71  * ITmfTimestamp startTime = ...;
  72  * ITmfTimestamp endTime = ...;
  73  * ITmfContext context = trace.seekEvent(startTime);
  74  * ITmfEvent event = trace.getEvent(context);
  75  * while (event != null && event.getTimestamp().compareTo(endTime) <= 0) {
  76  *     // Do something ...
  77  *     event = trace.getEvent(context);
  78  * }
  79  * </pre>
  80  */
  81 public interface ITmfTrace<T extends ITmfEvent> extends ITmfDataProvider<T> {
  82
  83     // ------------------------------------------------------------------------
  84     // Initializers
  85     // ------------------------------------------------------------------------
  86
  87     /**
  88      * Initialize a newly instantiated "empty" trace object. This is used to
  89      * properly parameterize an ITmfTrace instantiated with its parameterless
  90      * constructor.
  91      *
  92      * Typically, the parameterless constructor will provide the block size
  93      * and its associated parser and indexer.
  94      *
  95      * @param resource the trace resource
  96      * @param path the trace path
  97      * @param type the trace event type
  98      * @throws FileNotFoundException
  99      */
 100     public void initTrace(IResource resource, String path, Class<T> type) throws FileNotFoundException;
 101
 102     /**
 103      * Validate that the trace is of the correct type.
 104      *
 105      * @param project the eclipse project
 106      * @param path the trace path
 107      *
 108      * @return true if trace is valid
 109      */
 110     public boolean validate(IProject project, String path);
 111
 112     // ------------------------------------------------------------------------
 113     // Basic getters
 114     // ------------------------------------------------------------------------
 115
 116     /**
 117      * @return the trace event type
 118      */
 119     public Class<T> getType();
 120
 121     /**
 122      * @return the associated trace resource
 123      */
 124     public IResource getResource();
 125
 126     /**
 127      * @return the trace path
 128      */
 129     public String getPath();
 130
 131     // ------------------------------------------------------------------------
 132     // Trace characteristics getters
 133     // ------------------------------------------------------------------------
 134
 135     /**
 136      * @return the number of events in the trace
 137      */
 138     public long getNbEvents();
 139
 140     /**
 141      * @return the trace time range
 142      */
 143     public TmfTimeRange getTimeRange();
 144
 145     /**
 146      * @return the timestamp of the first trace event
 147      */
 148     public ITmfTimestamp getStartTime();
 149
 150     /**
 151      * @return the timestamp of the last trace event
 152      */
 153     public ITmfTimestamp getEndTime();
 154
 155     // ------------------------------------------------------------------------
 156     // Trace positioning getters
 157     // ------------------------------------------------------------------------
 158
 159     /**
 160      * @return the current trace location
 161      */
 162     public ITmfLocation<?> getCurrentLocation();
 163
 164     /**
 165      * Returns the ratio (proportion) corresponding to the specified location.
 166      *
 167      * @param location a trace specific location
 168      * @return a floating-point number between 0.0 (beginning) and 1.0 (end)
 169      */
 170     public double getLocationRatio(ITmfLocation<?> location);
 171
 172     // ------------------------------------------------------------------------
 173     // Seek operations (returning a reading context)
 174     // ------------------------------------------------------------------------
 175
 176     /**
 177      * Position the trace at the specified location. The null location
 178      * is used to indicate that the first trace event is requested.
 179      * <p>
 180      * <ul>
 181      * <li> a <b>null</b> location returns the context of the first event
 182      * <li> an invalid location, including beyond the last event, returns a null context
 183      * </ul>
 184      * <p>
 185      * @param location the trace specific location (null for 1st event)
 186      * @return a context which can later be used to read the corresponding event
 187      */
 188     public ITmfContext seekLocation(ITmfLocation<?> location);
 189
 190     /**
 191      * Position the trace at the event located at the specified ratio in the
 192      * trace file.
 193      * <p>
 194      * The notion of ratio (0.0 <= r <= 1.0) is trace specific and left
 195      * voluntarily vague. Typically, it would refer to the event proportional
 196      * rank (arguably more intuitive) or timestamp in the trace file.
 197      *
 198      * @param ratio the proportional 'rank' in the trace
 199      * @return a context which can later be used to read the corresponding event
 200      */
 201     public ITmfContext seekLocation(double ratio);
 202
 203     /**
 204      * Position the trace at the first event with the specified timestamp. If
 205      * there is no event with the requested timestamp, a context pointing to
 206      * the next chronological event is returned.
 207      * <p>
 208      * A null timestamp is interpreted as seeking for the first event of the
 209      * trace.
 210      * <p>
 211      * If the requested timestamp is beyond the last trace event, the context
 212      * returned will yield a null event if used in a subsequent read.
 213      *
 214      * @param timestamp the timestamp of desired event
 215      * @return a context which can later be used to read the corresponding event
 216      */
 217     public ITmfContext seekEvent(ITmfTimestamp timestamp);
 218
 219     /**
 220      * Position the trace at the 'rank'th event in the trace.
 221      * <p>
 222      * If the requested rank is beyond the last trace event, the context
 223      * returned will yield a null event if used in a subsequent read.
 224      *
 225      * @param rank the event rank
 226      * @return a context which can later be used to read the corresponding event
 227      */
 228     public ITmfContext seekEvent(long rank);
 229
 230     // ------------------------------------------------------------------------
 231     // Read operations (returning an actual event)
 232     // ------------------------------------------------------------------------
 233
 234     /**
 235      * Return the event pointed by the supplied context (or null if no event
 236      * left) and updates the context to point the next event.
 237      *
 238      * @param context the read context (will be updated)
 239      * @return the event pointed to by the context
 240      */
 241     public ITmfEvent getNextEvent(ITmfContext context);
 242
 243     /**
 244      * Return the event pointed by the supplied context (or null if no event
 245      * left) and *does not* update the context.
 246      *
 247      * @param context the read context
 248      * @return the next event in the stream
 249      */
 250     public ITmfEvent parseEvent(ITmfContext context);
 251
 252     // ------------------------------------------------------------------------
 253     // ------------------------------------------------------------------------
 254
 255     /**
 256      * @return the trace index page size
 257      */
 258     public int getIndexPageSize();
 259
 260     /**
 261      * @return the streaming interval in ms (0 if not a streaming trace)
 262      */
 263     public long getStreamingInterval();
 264
 265 }