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

   1 /*******************************************************************************
   2  * Copyright (c) 2009, 2014 Ericsson, École Polytechnique de Montréal
   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  *   Geneviève Bastien  - Added timestamp transforms and timestamp
  13  *                        creation functions
  14  *   Patrick Tasse - Add support for folder elements
  15  *******************************************************************************/
  16
  17 package org.eclipse.tracecompass.tmf.core.trace;
  18
  19 import org.eclipse.core.resources.IProject;
  20 import org.eclipse.core.resources.IResource;
  21 import org.eclipse.core.runtime.IStatus;
  22 import org.eclipse.jdt.annotation.NonNull;
  23 import org.eclipse.jdt.annotation.Nullable;
  24 import org.eclipse.tracecompass.tmf.core.analysis.IAnalysisModule;
  25 import org.eclipse.tracecompass.tmf.core.component.ITmfEventProvider;
  26 import org.eclipse.tracecompass.tmf.core.event.ITmfEvent;
  27 import org.eclipse.tracecompass.tmf.core.event.aspect.ITmfEventAspect;
  28 import org.eclipse.tracecompass.tmf.core.exceptions.TmfTraceException;
  29 import org.eclipse.tracecompass.tmf.core.synchronization.ITmfTimestampTransform;
  30 import org.eclipse.tracecompass.tmf.core.timestamp.ITmfTimestamp;
  31 import org.eclipse.tracecompass.tmf.core.timestamp.TmfTimeRange;
  32 import org.eclipse.tracecompass.tmf.core.trace.indexer.ITmfTraceIndexer;
  33 import org.eclipse.tracecompass.tmf.core.trace.location.ITmfLocation;
  34
  35 /**
  36  * The event stream structure in TMF. In its basic form, a trace has:
  37  * <ul>
  38  * <li> an associated Eclipse resource
  39  * <li> a path to its location on the file system
  40  * <li> the type of the events it contains
  41  * <li> the number of events it contains
  42  * <li> the time range (span) of the events it contains
  43  * </ul>
  44  * Concrete ITmfTrace classes have to provide a parameter-less constructor and
  45  * an initialization method (<i>initTrace</i>) if they are to be opened from the
  46  * Project View. Also, a validation method (<i>validate</i>) has to be provided
  47  * to ensure that the trace is of the correct type.
  48  * <p>
  49  * A trace can be accessed simultaneously from multiple threads by various
  50  * application components. To avoid obvious multi-threading issues, the trace
  51  * uses an ITmfContext as a synchronization aid for its read operations.
  52  * <p>
  53  * A proper ITmfContext can be obtained by performing a seek operation on the
  54  * trace. Seek operations can be performed for a particular event (by rank or
  55  * timestamp) or for a plain trace location.
  56  * <p>
  57  * <b>Example 1</b>: Process a whole trace
  58  * <pre>
  59  * ITmfContext context = trace.seekEvent(0);
  60  * ITmfEvent event = trace.getNext(context);
  61  * while (event != null) {
  62  *     processEvent(event);
  63  *     event = trace.getNext(context);
  64  * }
  65  * </pre>
  66  * <b>Example 2</b>: Process 50 events starting from the 1000th event
  67  * <pre>
  68  * int nbEventsRead = 0;
  69  * ITmfContext context = trace.seekEvent(1000);
  70  * ITmfEvent event = trace.getNext(context);
  71  * while (event != null && nbEventsRead < 50) {
  72  *     nbEventsRead++;
  73  *     processEvent(event);
  74  *     event = trace.getNext(context);
  75  * }
  76  * </pre>
  77  * <b>Example 3</b>: Process the events between 2 timestamps (inclusive)
  78  * <pre>
  79  * ITmfTimestamp startTime = ...;
  80  * ITmfTimestamp endTime = ...;
  81  * ITmfContext context = trace.seekEvent(startTime);
  82  * ITmfEvent event = trace.getNext(context);
  83  * while (event != null && event.getTimestamp().compareTo(endTime) <= 0) {
  84  *     processEvent(event);
  85  *     event = trace.getNext(context);
  86  * }
  87  * </pre>
  88  *
  89  * A trace is also an event provider so it can process event requests
  90  * asynchronously (and coalesce compatible, concurrent requests).
  91  * <p>
  92  *
  93  * <b>Example 4</b>: Process a whole trace (see ITmfEventRequest for
  94  * variants)
  95  * <pre>
  96  * ITmfRequest request = new TmfEventRequest&lt;MyEventType&gt;(MyEventType.class) {
  97  *     &#064;Override
  98  *     public void handleData(MyEventType event) {
  99  *         super.handleData(event);
 100  *         processEvent(event);
 101  *     }
 102  *
 103  *     &#064;Override
 104  *     public void handleCompleted() {
 105  *         finish();
 106  *         super.handleCompleted();
 107  *     }
 108  * };
 109  *
 110  * fTrace.handleRequest(request);
 111  * if (youWant) {
 112  *     request.waitForCompletion();
 113  * }
 114  * </pre>
 115  *
 116  * @version 1.0
 117  * @author Francois Chouinard
 118  *
 119  * @see ITmfContext
 120  * @see ITmfEvent
 121  * @see ITmfTraceIndexer
 122  * @see ITmfEventParser
 123  */
 124 public interface ITmfTrace extends ITmfEventProvider {
 125
 126     // ------------------------------------------------------------------------
 127     // Constants
 128     // ------------------------------------------------------------------------
 129
 130     /**
 131      * The default trace cache size
 132      */
 133     public static final int DEFAULT_TRACE_CACHE_SIZE = 1000;
 134
 135     // ------------------------------------------------------------------------
 136     // Initializers
 137     // ------------------------------------------------------------------------
 138
 139     /**
 140      * Initialize a newly instantiated "empty" trace object. This is used to
 141      * properly parameterize an ITmfTrace instantiated with its parameterless
 142      * constructor.
 143      * <p>
 144      * Typically, the parameterless constructor will provide the block size and
 145      * its associated parser and indexer.
 146      *
 147      * @param resource
 148      *            the trace resource
 149      * @param path
 150      *            the trace path. The path should suitable for passing to
 151      *            <code>java.io.File(String)</code> and should use the
 152      *            platform-dependent path separator.
 153      * @param type
 154      *            the trace event type
 155      * @throws TmfTraceException
 156      *             If we couldn't open the trace
 157      */
 158     void initTrace(IResource resource, String path, Class<? extends ITmfEvent> type) throws TmfTraceException;
 159
 160     /**
 161      * Initialize a newly instantiated "empty" trace object. This is used to
 162      * properly parameterize an ITmfTrace instantiated with its parameterless
 163      * constructor.
 164      * <p>
 165      * Typically, the parameterless constructor will provide the block size and
 166      * its associated parser and indexer.
 167      *
 168      * @param resource
 169      *            the trace resource
 170      * @param path
 171      *            the trace path
 172      * @param type
 173      *            the trace event type
 174      * @param name
 175      *            the trace name
 176      * @throws TmfTraceException
 177      *             If we couldn't open the trace
 178      */
 179     void initTrace(IResource resource, String path, Class<? extends ITmfEvent> type, String name) throws TmfTraceException;
 180
 181     /**
 182      * Validate that the trace is of the correct type. The implementation should
 183      * return a TraceValidationStatus to indicate success with a certain level
 184      * of confidence.
 185      *
 186      * @param project
 187      *            the eclipse project
 188      * @param path
 189      *            the trace path. The path should suitable for passing to
 190      *            <code>java.io.File(String)</code> and should use the
 191      *            platform-dependent path separator.
 192      *
 193      * @return an IStatus object with validation result. Use severity OK to
 194      *         indicate success.
 195      * @see TraceValidationStatus
 196      * @since 2.0
 197      */
 198     IStatus validate(IProject project, String path);
 199
 200     // ------------------------------------------------------------------------
 201     // Basic getters
 202     // ------------------------------------------------------------------------
 203
 204     /**
 205      * @return the trace event type
 206      */
 207     Class<? extends ITmfEvent> getEventType();
 208
 209     /**
 210      * @return the associated trace resource
 211      */
 212     IResource getResource();
 213
 214     /**
 215      * @return the trace path
 216      */
 217     String getPath();
 218
 219     /**
 220      * @return the trace cache size
 221      */
 222     int getCacheSize();
 223
 224     /**
 225      * Index the trace. Depending on the trace type, this could be done at the
 226      * constructor or initTrace phase too, so this could be implemented as a
 227      * no-op.
 228      *
 229      * @param waitForCompletion
 230      *            Should we block the caller until indexing is finished, or not.
 231      * @since 2.0
 232      */
 233     void indexTrace(boolean waitForCompletion);
 234
 235     // ------------------------------------------------------------------------
 236     // Analysis getters
 237     // ------------------------------------------------------------------------
 238
 239     /**
 240      * Returns an analysis module with the given ID.
 241      *
 242      * @param id
 243      *            The analysis module ID
 244      * @return The {@link IAnalysisModule} object, or null if an analysis with
 245      *         the given ID does no exist.
 246      * @since 3.0
 247      */
 248     @Nullable
 249     IAnalysisModule getAnalysisModule(String id);
 250
 251     /**
 252      * Get a list of all analysis modules currently available for this trace.
 253      *
 254      * @return An iterable view of the analysis modules
 255      * @since 3.0
 256      */
 257     @NonNull
 258     Iterable<IAnalysisModule> getAnalysisModules();
 259
 260     /**
 261      * Get an analysis module belonging to this trace, with the specified ID and
 262      * class.
 263      *
 264      * @param moduleClass
 265      *            Returned modules must extend this class
 266      * @param id
 267      *            The ID of the analysis module
 268      * @return The analysis module with specified class and ID, or null if no
 269      *         such module exists.
 270      * @since 3.0
 271      */
 272     @Nullable
 273     <T extends IAnalysisModule> T getAnalysisModuleOfClass(Class<T> moduleClass, String id);
 274
 275     /**
 276      * Return the analysis modules that are of a given class. Module are already
 277      * casted to the requested class.
 278      *
 279      * @param moduleClass
 280      *            Returned modules must extend this class
 281      * @return List of modules of class moduleClass
 282      * @since 3.0
 283      */
 284     @NonNull
 285     <T> Iterable<T> getAnalysisModulesOfClass(Class<T> moduleClass);
 286
 287     // ------------------------------------------------------------------------
 288     // Aspect getters
 289     // ------------------------------------------------------------------------
 290
 291     /**
 292      * Return the pre-defined set of event aspects exposed by this trace.
 293      *
 294      * @return The event aspects for this trace
 295      */
 296     Iterable<ITmfEventAspect> getEventAspects();
 297
 298     // ------------------------------------------------------------------------
 299     // Trace characteristics getters
 300     // ------------------------------------------------------------------------
 301
 302     /**
 303      * @return the number of events in the trace
 304      */
 305     long getNbEvents();
 306
 307     /**
 308      * @return the trace time range
 309      * @since 2.0
 310      */
 311     TmfTimeRange getTimeRange();
 312
 313     /**
 314      * @return the timestamp of the first trace event
 315      * @since 2.0
 316      */
 317     ITmfTimestamp getStartTime();
 318
 319     /**
 320      * @return the timestamp of the last trace event
 321      * @since 2.0
 322      */
 323     ITmfTimestamp getEndTime();
 324
 325     /**
 326      * @return the streaming interval in ms (0 if not a streaming trace)
 327      */
 328     long getStreamingInterval();
 329
 330     // ------------------------------------------------------------------------
 331     // Trace positioning getters
 332     // ------------------------------------------------------------------------
 333
 334     /**
 335      * @return the current trace location
 336      * @since 3.0
 337      */
 338     ITmfLocation getCurrentLocation();
 339
 340     /**
 341      * Returns the ratio (proportion) corresponding to the specified location.
 342      *
 343      * @param location
 344      *            a trace specific location
 345      * @return a floating-point number between 0.0 (beginning) and 1.0 (end)
 346      * @since 3.0
 347      */
 348     double getLocationRatio(ITmfLocation location);
 349
 350     // ------------------------------------------------------------------------
 351     // SeekEvent operations (returning a trace context)
 352     // ------------------------------------------------------------------------
 353
 354     /**
 355      * Position the trace at the specified (trace specific) location.
 356      * <p>
 357      * A null location is interpreted as seeking for the first event of the
 358      * trace.
 359      * <p>
 360      * If not null, the location requested must be valid otherwise the returned
 361      * context is undefined (up to the implementation to recover if possible).
 362      * <p>
 363      *
 364      * @param location
 365      *            the trace specific location
 366      * @return a context which can later be used to read the corresponding event
 367      * @since 3.0
 368      */
 369     ITmfContext seekEvent(ITmfLocation location);
 370
 371     /**
 372      * Position the trace at the 'rank'th event in the trace.
 373      * <p>
 374      * A rank <= 0 is interpreted as seeking for the first event of the trace.
 375      * <p>
 376      * If the requested rank is beyond the last trace event, the context
 377      * returned will yield a null event if used in a subsequent read.
 378      *
 379      * @param rank
 380      *            the event rank
 381      * @return a context which can later be used to read the corresponding event
 382      */
 383     ITmfContext seekEvent(long rank);
 384
 385     /**
 386      * Position the trace at the first event with the specified timestamp. If
 387      * there is no event with the requested timestamp, a context pointing to the
 388      * next chronological event is returned.
 389      * <p>
 390      * A null timestamp is interpreted as seeking for the first event of the
 391      * trace.
 392      * <p>
 393      * If the requested timestamp is beyond the last trace event, the context
 394      * returned will yield a null event if used in a subsequent read.
 395      *
 396      * @param timestamp
 397      *            the timestamp of desired event
 398      * @return a context which can later be used to read the corresponding event
 399      * @since 2.0
 400      */
 401     ITmfContext seekEvent(ITmfTimestamp timestamp);
 402
 403     /**
 404      * Position the trace at the event located at the specified ratio in the
 405      * trace file.
 406      * <p>
 407      * The notion of ratio (0.0 <= r <= 1.0) is trace specific and left
 408      * voluntarily vague. Typically, it would refer to the event proportional
 409      * rank (arguably more intuitive) or timestamp in the trace file.
 410      *
 411      * @param ratio
 412      *            the proportional 'rank' in the trace
 413      * @return a context which can later be used to read the corresponding event
 414      */
 415     ITmfContext seekEvent(double ratio);
 416
 417     /**
 418      * Returns the initial range offset
 419      *
 420      * @return the initial range offset
 421      * @since 2.0
 422      */
 423     ITmfTimestamp getInitialRangeOffset();
 424
 425     /**
 426      * Returns the ID of the host this trace is from. The host ID is not
 427      * necessarily the hostname, but should be a unique identifier for the
 428      * machine on which the trace was taken. It can be used to determine if two
 429      * traces were taken on the exact same machine (timestamp are already
 430      * synchronized, resources with same id are the same if taken at the same
 431      * time, etc).
 432      *
 433      * @return The host id of this trace
 434      * @since 3.0
 435      */
 436     @NonNull String getHostId();
 437
 438     // ------------------------------------------------------------------------
 439     // Timestamp transformation functions
 440     // ------------------------------------------------------------------------
 441
 442     /**
 443      * Returns the timestamp transformation for this trace
 444      *
 445      * @return the timestamp transform
 446      * @since 3.0
 447      */
 448     ITmfTimestampTransform getTimestampTransform();
 449
 450     /**
 451      * Sets the trace's timestamp transform
 452      *
 453      * @param tt
 454      *            The timestamp transform for all timestamps of this trace
 455      * @since 3.0
 456      */
 457     void setTimestampTransform(final ITmfTimestampTransform tt);
 458
 459     /**
 460      * Creates a timestamp for this trace, using the transformation formula
 461      *
 462      * @param ts
 463      *            The time in nanoseconds with which to create the timestamp
 464      * @return The new timestamp
 465      * @since 3.0
 466      */
 467     ITmfTimestamp createTimestamp(long ts);
 468
 469 }