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

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