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