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.util.Collection;
  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.exceptions.TmfTraceException;
  23 import org.eclipse.linuxtools.tmf.core.statesystem.ITmfStateSystem;
  24 import org.eclipse.linuxtools.tmf.core.statistics.ITmfStatistics;
  25 import org.eclipse.linuxtools.tmf.core.timestamp.ITmfTimestamp;
  26 import org.eclipse.linuxtools.tmf.core.timestamp.TmfTimeRange;
  27
  28 /**
  29  * The event stream structure in TMF. In its basic form, a trace has:
  30  * <ul>
  31  * <li> an associated Eclipse resource
  32  * <li> a path to its location on the file system
  33  * <li> the type of the events it contains
  34  * <li> the number of events it contains
  35  * <li> the time range (span) of the events it contains
  36  * </ul>
  37  * Concrete ITmfTrace classes have to provide a parameter-less constructor and
  38  * an initialization method (<i>initTrace</i>) if they are to be opened from
  39  * the Project View. Also, a validation method (<i>validate</i>) has to be
  40  * provided to ensure that the trace is of the correct type.
  41  * <p>
  42  * A trace can be accessed simultaneously from multiple threads by various
  43  * application components. To avoid obvious multi-threading issues, the trace
  44  * uses an ITmfContext as a synchronization aid for its read operations.
  45  * <p>
  46  * A proper ITmfContext can be obtained by performing a seek operation on the
  47  * trace. Seek operations can be performed for a particular event (by rank or
  48  * timestamp) or for a plain trace location.
  49  * <p>
  50  * <b>Example 1</b>: Process a whole trace
  51  * <pre>
  52  * ITmfContext context = trace.seekEvent(0);
  53  * ITmfEvent event = trace.getNext(context);
  54  * while (event != null) {
  55  *     processEvent(event);
  56  *     event = trace.getNext(context);
  57  * }
  58  * </pre>
  59  * <b>Example 2</b>: Process 50 events starting from the 1000th event
  60  * <pre>
  61  * int nbEventsRead = 0;
  62  * ITmfContext context = trace.seekEvent(1000);
  63  * ITmfEvent event = trace.getNext(context);
  64  * while (event != null && nbEventsRead < 50) {
  65  *     nbEventsRead++;
  66  *     processEvent(event);
  67  *     event = trace.getNext(context);
  68  * }
  69  * </pre>
  70  * <b>Example 3</b>: Process the events between 2 timestamps (inclusive)
  71  * <pre>
  72  * ITmfTimestamp startTime = ...;
  73  * ITmfTimestamp endTime = ...;
  74  * ITmfContext context = trace.seekEvent(startTime);
  75  * ITmfEvent event = trace.getNext(context);
  76  * while (event != null && event.getTimestamp().compareTo(endTime) <= 0) {
  77  *     processEvent(event);
  78  *     event = trace.getNext(context);
  79  * }
  80  * </pre>
  81  * A trace is also an event provider so it can process event requests
  82  * asynchronously (and coalesce compatible, concurrent requests).
  83  * <p>
  84  * </pre>
  85  * <b>Example 4</b>: Process a whole trace (see ITmfEventRequest for variants)
  86  * <pre>
  87  * ITmfRequest request = new TmfEventRequest&lt;MyEventType&gt;(MyEventType.class) {
  88  *     &#64;Override
  89  *     public void handleData(MyEventType event) {
  90  *         super.handleData(event);
  91  *         processEvent(event);
  92  *     }
  93  *     &#64;Override
  94  *     public void handleCompleted() {
  95  *         finish();
  96  *         super.handleCompleted();
  97  *     }
  98  * };
  99  *
 100  * fTrace.handleRequest(request);
 101  * if (youWant) {
 102  *     request.waitForCompletion();
 103  * }
 104  * </pre>
 105  *
 106  * @version 1.0
 107  * @author Francois Chouinard
 108  *
 109  * @see ITmfContext
 110  * @see ITmfEvent
 111  * @see ITmfTraceIndexer
 112  * @see ITmfEventParser
 113  */
 114 public interface ITmfTrace extends ITmfDataProvider {
 115
 116     // ------------------------------------------------------------------------
 117     // Constants
 118     // ------------------------------------------------------------------------
 119
 120     /**
 121      * The default trace cache size
 122      */
 123     public static final int DEFAULT_TRACE_CACHE_SIZE = 1000;
 124
 125     // ------------------------------------------------------------------------
 126     // Initializers
 127     // ------------------------------------------------------------------------
 128
 129     /**
 130      * Initialize a newly instantiated "empty" trace object. This is used to
 131      * properly parameterize an ITmfTrace instantiated with its parameterless
 132      * constructor.
 133      * <p>
 134      * Typically, the parameterless constructor will provide the block size
 135      * and its associated parser and indexer.
 136      *
 137      * @param resource the trace resource
 138      * @param path the trace path
 139      * @param type the trace event type
 140      * @throws TmfTraceException If we couldn't open the trace
 141      */
 142     public void initTrace(IResource resource, String path, Class<? extends ITmfEvent> type) throws TmfTraceException;
 143
 144     /**
 145      * Validate that the trace is of the correct type.
 146      *
 147      * @param project the eclipse project
 148      * @param path the trace path
 149      *
 150      * @return true if trace is valid
 151      */
 152     public boolean validate(IProject project, String path);
 153
 154     // ------------------------------------------------------------------------
 155     // Basic getters
 156     // ------------------------------------------------------------------------
 157
 158     /**
 159      * @return the trace event type
 160      */
 161     public Class<? extends ITmfEvent> getEventType();
 162
 163     /**
 164      * @return the associated trace resource
 165      */
 166     public IResource getResource();
 167
 168     /**
 169      * @return the trace path
 170      */
 171     public String getPath();
 172
 173     /**
 174      * @return the trace cache size
 175      */
 176     public int getCacheSize();
 177
 178     /**
 179      * @return The statistics provider for this trace
 180      * @since 2.0
 181      */
 182     public ITmfStatistics getStatistics();
 183
 184     /**
 185      * Retrieve a state system that belongs to this trace
 186      *
 187      * @param id
 188      *            The ID of the state system to retrieve.
 189      * @return The state system that is associated with this trace and ID, or
 190      *         'null' if such a match doesn't exist.
 191      * @since 2.0
 192      */
 193     public ITmfStateSystem getStateSystem(String id);
 194
 195     /**
 196      * Return the list of existing state systems registered with this trace.
 197      *
 198      * @return A Collection view of the available state systems. The collection
 199      *         could be empty, but should not be null.
 200      * @since 2.0
 201      */
 202     public Collection<String> listStateSystems();
 203
 204     // ------------------------------------------------------------------------
 205     // Trace characteristics getters
 206     // ------------------------------------------------------------------------
 207
 208     /**
 209      * @return the number of events in the trace
 210      */
 211     public long getNbEvents();
 212
 213     /**
 214      * @return the trace time range
 215      * @since 2.0
 216      */
 217     public TmfTimeRange getTimeRange();
 218
 219     /**
 220      * @return the timestamp of the first trace event
 221      * @since 2.0
 222      */
 223     public ITmfTimestamp getStartTime();
 224
 225     /**
 226      * @return the timestamp of the last trace event
 227      * @since 2.0
 228      */
 229     public ITmfTimestamp getEndTime();
 230
 231     /**
 232      * @return the streaming interval in ms (0 if not a streaming trace)
 233      */
 234     public long getStreamingInterval();
 235
 236     // ------------------------------------------------------------------------
 237     // Trace positioning getters
 238     // ------------------------------------------------------------------------
 239
 240     /**
 241      * @return the current trace location
 242      */
 243     public ITmfLocation getCurrentLocation();
 244
 245     /**
 246      * Returns the ratio (proportion) corresponding to the specified location.
 247      *
 248      * @param location a trace specific location
 249      * @return a floating-point number between 0.0 (beginning) and 1.0 (end)
 250      */
 251     public double getLocationRatio(ITmfLocation location);
 252
 253     // ------------------------------------------------------------------------
 254     // SeekEvent operations (returning a trace context)
 255     // ------------------------------------------------------------------------
 256
 257     /**
 258      * Position the trace at the specified (trace specific) location.
 259      * <p>
 260      * A null location is interpreted as seeking for the first event of the
 261      * trace.
 262      * <p>
 263      * If not null, the location requested must be valid otherwise the returned
 264      * context is undefined (up to the implementation to recover if possible).
 265      * <p>
 266      * @param location the trace specific location
 267      * @return a context which can later be used to read the corresponding event
 268      */
 269     public ITmfContext seekEvent(ITmfLocation location);
 270
 271     /**
 272      * Position the trace at the 'rank'th event in the trace.
 273      * <p>
 274      * A rank <= 0 is interpreted as seeking for the first event of the
 275      * trace.
 276      * <p>
 277      * If the requested rank is beyond the last trace event, the context
 278      * returned will yield a null event if used in a subsequent read.
 279      *
 280      * @param rank the event rank
 281      * @return a context which can later be used to read the corresponding event
 282      */
 283     public ITmfContext seekEvent(long rank);
 284
 285     /**
 286      * Position the trace at the first event with the specified timestamp. If
 287      * there is no event with the requested timestamp, a context pointing to
 288      * the next chronological event is returned.
 289      * <p>
 290      * A null timestamp is interpreted as seeking for the first event of the
 291      * trace.
 292      * <p>
 293      * If the requested timestamp is beyond the last trace event, the context
 294      * returned will yield a null event if used in a subsequent read.
 295      *
 296      * @param timestamp the timestamp of desired event
 297      * @return a context which can later be used to read the corresponding event
 298      * @since 2.0
 299      */
 300     public ITmfContext seekEvent(ITmfTimestamp timestamp);
 301
 302     /**
 303      * Position the trace at the event located at the specified ratio in the
 304      * trace file.
 305      * <p>
 306      * The notion of ratio (0.0 <= r <= 1.0) is trace specific and left
 307      * voluntarily vague. Typically, it would refer to the event proportional
 308      * rank (arguably more intuitive) or timestamp in the trace file.
 309      *
 310      * @param ratio the proportional 'rank' in the trace
 311      * @return a context which can later be used to read the corresponding event
 312      */
 313     public ITmfContext seekEvent(double ratio);
 314
 315     /**
 316      * Returns the initial range offset
 317      *
 318      * @return the initial range offset
 319      * @since 2.0
 320      */
 321     public ITmfTimestamp getInitialRangeOffset();
 322
 323     /**
 324      * Return the current selected time.
 325      *
 326      * @return the current time stamp
 327      * @since 2.0
 328      */
 329     public ITmfTimestamp getCurrentTime();
 330
 331     /**
 332      * Return the current selected range.
 333      *
 334      * @return the current time range
 335      * @since 2.0
 336      */
 337     public TmfTimeRange getCurrentRange();
 338 }