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