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

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