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