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

   1 /*******************************************************************************
   2  * Copyright (c) 2009, 2010, 2012 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.io.File;
  17 import java.io.FileNotFoundException;
  18
  19 import org.eclipse.core.resources.IProject;
  20 import org.eclipse.core.resources.IResource;
  21 import org.eclipse.core.runtime.Path;
  22 import org.eclipse.linuxtools.tmf.core.component.TmfEventProvider;
  23 import org.eclipse.linuxtools.tmf.core.event.ITmfEvent;
  24 import org.eclipse.linuxtools.tmf.core.event.ITmfTimestamp;
  25 import org.eclipse.linuxtools.tmf.core.event.TmfTimeRange;
  26 import org.eclipse.linuxtools.tmf.core.event.TmfTimestamp;
  27 import org.eclipse.linuxtools.tmf.core.request.ITmfDataRequest;
  28 import org.eclipse.linuxtools.tmf.core.request.ITmfEventRequest;
  29
  30 /**
  31  * <b><u>TmfTrace</u></b>
  32  * <p>
  33  * Abstract implementation of ITmfTrace.
  34  * <p>
  35  * Since the concept of 'location' is trace specific, the concrete classes have
  36  * to provide the related methods, namely:
  37  * <ul>
  38  * <li> public ITmfLocation<?> getCurrentLocation()
  39  * <li> public double getLocationRatio(ITmfLocation<?> location)
  40  * <li> public ITmfContext seekEvent(ITmfLocation<?> location)
  41  * <li> public ITmfContext seekEvent(double ratio)
  42  * </ul>
  43  * A concrete trace must provide its corresponding parser. A common way to
  44  * accomplish this is by making the concrete class extend TmfTrace and
  45  * implement ITmfEventParser.
  46  * <p>
  47  * The concrete class can either specify its own indexer or use the provided
  48  * TmfCheckpointIndexer (default). In this case, the trace cache size will be
  49  * used as checkpoint interval.
  50  */
  51 public abstract class TmfTrace<T extends ITmfEvent> extends TmfEventProvider<T> implements ITmfTrace<T> {
  52
  53     // ------------------------------------------------------------------------
  54     // Constants
  55     // ------------------------------------------------------------------------
  56
  57     /**
  58      * The default trace cache size
  59      */
  60     public static final int DEFAULT_TRACE_CACHE_SIZE = 1000;
  61
  62     // ------------------------------------------------------------------------
  63     // Attributes
  64     // ------------------------------------------------------------------------
  65
  66     // The resource used for persistent properties for this trace
  67     private IResource fResource;
  68
  69     // The trace path
  70     private String fPath;
  71
  72     /**
  73      * The cache page size
  74      */
  75     protected int fCacheSize = DEFAULT_TRACE_CACHE_SIZE;
  76
  77     /**
  78      * The number of events collected so far
  79      */
  80     protected long fNbEvents = 0;
  81
  82     // The time span of the event stream
  83     private ITmfTimestamp fStartTime = TmfTimestamp.BIG_CRUNCH;
  84     private ITmfTimestamp fEndTime = TmfTimestamp.BIG_BANG;
  85
  86     /**
  87      * The trace streaming interval (0 = no streaming)
  88      */
  89     protected long fStreamingInterval = 0;
  90
  91     /**
  92      * The trace indexer
  93      */
  94     protected ITmfTraceIndexer<ITmfTrace<ITmfEvent>> fIndexer;
  95
  96     /**
  97      * The trace parser
  98      */
  99     protected ITmfEventParser<ITmfEvent> fParser;
 100
 101     // ------------------------------------------------------------------------
 102     // Construction
 103     // ------------------------------------------------------------------------
 104
 105     /**
 106      * The default, parameterless, constructor
 107      */
 108     @SuppressWarnings({ "unchecked", "rawtypes" })
 109     public TmfTrace() {
 110         super();
 111         fIndexer = new TmfCheckpointIndexer(this);
 112     }
 113
 114     /**
 115      * The standard constructor (non-live trace). Applicable when the trace
 116      * implements its own parser and if at checkpoint-based index is OK.
 117      *
 118      * @param resource the resource associated to the trace
 119      * @param type the trace event type
 120      * @param path the trace path
 121      * @param cacheSize the trace cache size
 122      * @throws FileNotFoundException
 123      */
 124     protected TmfTrace(final IResource resource, final Class<T> type, final String path, final int cacheSize) throws FileNotFoundException {
 125         this(resource, type, path, cacheSize, 0, null);
 126     }
 127
 128     /**
 129      * The standard constructor (live trace). Applicable when the trace
 130      * implements its own parser and if at checkpoint-based index is OK.
 131      *
 132      * @param resource the resource associated to the trace
 133      * @param type the trace event type
 134      * @param path the trace path
 135      * @param cacheSize the trace cache size
 136      * @param interval the trace streaming interval
 137      * @throws FileNotFoundException
 138      */
 139     protected TmfTrace(final IResource resource, final Class<T> type, final String path, final int cacheSize, final long interval) throws FileNotFoundException {
 140         this(resource, type, path, cacheSize, interval, null);
 141     }
 142
 143     /**
 144      * The 'non-default indexer' constructor. Allows to provide a trace
 145      * specific indexer.
 146      *
 147      * @param resource the resource associated to the trace
 148      * @param type the trace event type
 149      * @param path the trace path
 150      * @param cacheSize the trace cache size
 151      * @param indexer the trace indexer
 152      * @throws FileNotFoundException
 153      */
 154     protected TmfTrace(final IResource resource, final Class<T> type, final String path, final int cacheSize,
 155             final long interval, final ITmfTraceIndexer<?> indexer) throws FileNotFoundException {
 156         this(resource, type, path, cacheSize, interval, null, null);
 157     }
 158
 159     /**
 160      * The full constructor where trace specific indexer/parser are provided.
 161      *
 162      * @param resource the resource associated to the trace
 163      * @param type the trace event type
 164      * @param path the trace path
 165      * @param cacheSize the trace cache size
 166      * @param indexer the trace indexer
 167      * @param parser the trace event parser
 168      * @throws FileNotFoundException
 169      */
 170     @SuppressWarnings({ "unchecked", "rawtypes" })
 171     protected TmfTrace(final IResource resource, final Class<T> type, final String path, final int cacheSize,
 172             final long interval, final ITmfTraceIndexer<?> indexer, final ITmfEventParser<ITmfEvent> parser) throws FileNotFoundException {
 173         super();
 174         fCacheSize = (cacheSize > 0) ? cacheSize : DEFAULT_TRACE_CACHE_SIZE;
 175         fStreamingInterval = interval;
 176         fIndexer = (indexer != null) ? indexer : new TmfCheckpointIndexer(this, fCacheSize);
 177         fParser = parser;
 178         initialize(resource, path, type);
 179     }
 180
 181     /**
 182      * Copy constructor
 183      *
 184      * @param trace the original trace
 185      */
 186     @SuppressWarnings({ "unchecked", "rawtypes" })
 187     public TmfTrace(final TmfTrace<T> trace) throws FileNotFoundException {
 188         super();
 189         if (trace == null)
 190             throw new IllegalArgumentException();
 191         fCacheSize = trace.getCacheSize();
 192         fStreamingInterval = trace.getStreamingInterval();
 193         fIndexer = new TmfCheckpointIndexer(this);
 194         fParser = trace.fParser;
 195         initialize(trace.getResource(), trace.getPath(), trace.getEventType());
 196     }
 197
 198     // ------------------------------------------------------------------------
 199     // ITmfTrace - Initializers
 200     // ------------------------------------------------------------------------
 201
 202     /* (non-Javadoc)
 203      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#initTrace(org.eclipse.core.resources.IResource, java.lang.String, java.lang.Class)
 204      */
 205     @Override
 206     public void initTrace(final IResource resource, final String path, final Class<T> type) throws FileNotFoundException {
 207         initialize(resource, path, type);
 208         fIndexer.buildIndex(false);
 209     }
 210
 211     /**
 212      * Initialize the trace common attributes and the base component.
 213      *
 214      * @param resource the Eclipse resource (trace)
 215      * @param path the trace path
 216      * @param type the trace event type
 217      *
 218      * @throws FileNotFoundException
 219      */
 220     protected void initialize(final IResource resource, final String path, final Class<T> type) throws FileNotFoundException {
 221         if (path == null)
 222             throw new FileNotFoundException();
 223         fPath = path;
 224         fResource = resource;
 225         String traceName = (resource != null) ? resource.getName() : null;
 226         // If no resource was provided, extract the display name the trace path
 227         if (traceName == null) {
 228             final int sep = path.lastIndexOf(Path.SEPARATOR);
 229             traceName = (sep >= 0) ? path.substring(sep + 1) : path;
 230         }
 231         super.init(traceName, type);
 232     }
 233
 234     /* (non-Javadoc)
 235      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#validate(org.eclipse.core.resources.IProject, java.lang.String)
 236      *
 237      * Default validation: make sure the trace file exists.
 238      */
 239     @Override
 240     public boolean validate(final IProject project, final String path) {
 241         final File file = new File(path);
 242         return file.exists();
 243     }
 244
 245     // ------------------------------------------------------------------------
 246     // ITmfTrace - Basic getters
 247     // ------------------------------------------------------------------------
 248
 249     /* (non-Javadoc)
 250      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getEventType()
 251      */
 252     @Override
 253     @SuppressWarnings("unchecked")
 254     public Class<T> getEventType() {
 255         return (Class<T>) super.getType();
 256     }
 257
 258     /* (non-Javadoc)
 259      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getResource()
 260      */
 261     @Override
 262     public IResource getResource() {
 263         return fResource;
 264     }
 265
 266     /* (non-Javadoc)
 267      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getPath()
 268      */
 269     @Override
 270     public String getPath() {
 271         return fPath;
 272     }
 273
 274     /* (non-Javadoc)
 275      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getIndexPageSize()
 276      */
 277     @Override
 278     public int getCacheSize() {
 279         return fCacheSize;
 280     }
 281
 282     /* (non-Javadoc)
 283      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getStreamingInterval()
 284      */
 285     @Override
 286     public long getStreamingInterval() {
 287         return fStreamingInterval;
 288     }
 289
 290     // ------------------------------------------------------------------------
 291     // ITmfTrace - Trace characteristics getters
 292     // ------------------------------------------------------------------------
 293
 294     /* (non-Javadoc)
 295      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getNbEvents()
 296      */
 297     @Override
 298     public long getNbEvents() {
 299         return fNbEvents;
 300     }
 301
 302     /* (non-Javadoc)
 303      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getTimeRange()
 304      */
 305     @Override
 306     public TmfTimeRange getTimeRange() {
 307         return new TmfTimeRange(fStartTime, fEndTime);
 308     }
 309
 310     /* (non-Javadoc)
 311      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getStartTime()
 312      */
 313     @Override
 314     public ITmfTimestamp getStartTime() {
 315         return fStartTime.clone();
 316     }
 317
 318     /* (non-Javadoc)
 319      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getEndTime()
 320      */
 321     @Override
 322     public ITmfTimestamp getEndTime() {
 323         return fEndTime.clone();
 324     }
 325
 326     // ------------------------------------------------------------------------
 327     // Convenience setters
 328     // ------------------------------------------------------------------------
 329
 330     /**
 331      * Update the trace events time range
 332      *
 333      * @param range the new time range
 334      */
 335     protected void setTimeRange(final TmfTimeRange range) {
 336         fStartTime = range.getStartTime().clone();
 337         fEndTime = range.getEndTime().clone();
 338     }
 339
 340     /**
 341      * Update the trace chronologically first event timestamp
 342      *
 343      * @param startTime the new first event timestamp
 344      */
 345     protected void setStartTime(final ITmfTimestamp startTime) {
 346         fStartTime = startTime.clone();
 347     }
 348
 349     /**
 350      * Update the trace chronologically last event timestamp
 351      *
 352      * @param endTime the new last event timestamp
 353      */
 354     protected void setEndTime(final ITmfTimestamp endTime) {
 355         fEndTime = endTime.clone();
 356     }
 357
 358     /**
 359      * Update the trace streaming interval
 360      *
 361      * @param interval the new trace streaming interval
 362      */
 363     protected void setStreamingInterval(final long interval) {
 364         fStreamingInterval = (interval > 0) ? interval : 0;
 365     }
 366
 367     // ------------------------------------------------------------------------
 368     // ITmfTrace - SeekEvent operations (returning a trace context)
 369     // ------------------------------------------------------------------------
 370
 371     /* (non-Javadoc)
 372      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#seekEvent(long)
 373      */
 374     @Override
 375     public synchronized ITmfContext seekEvent(final long rank) {
 376
 377         // A rank <= 0 indicates to seek the first event
 378         if (rank <= 0)
 379             return seekEvent((ITmfLocation<?>) null);
 380
 381         // Position the trace at the checkpoint
 382         final ITmfContext context = fIndexer.seekIndex(rank);
 383
 384         // And locate the requested event context
 385         long pos = context.getRank();
 386         if (pos < rank) {
 387             ITmfEvent event = readEvent(context);
 388             while (event != null && ++pos < rank) {
 389                 event = readEvent(context);
 390             }
 391         }
 392         return context;
 393     }
 394
 395     /* (non-Javadoc)
 396      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#seekEvent(org.eclipse.linuxtools.tmf.core.event.ITmfTimestamp)
 397      */
 398     @Override
 399     public synchronized ITmfContext seekEvent(final ITmfTimestamp timestamp) {
 400
 401         // A null timestamp indicates to seek the first event
 402         if (timestamp == null)
 403             return seekEvent(0);
 404
 405         // Position the trace at the checkpoint
 406         final ITmfContext context = fIndexer.seekIndex(timestamp);
 407
 408         // And locate the requested event context
 409         final ITmfContext nextEventContext = context.clone(); // Must use clone() to get the right subtype...
 410         ITmfEvent event = readEvent(nextEventContext);
 411         while (event != null && event.getTimestamp().compareTo(timestamp, false) < 0) {
 412             context.setLocation(nextEventContext.getLocation().clone());
 413             context.increaseRank();
 414             event = readEvent(nextEventContext);
 415         }
 416         return context;
 417     }
 418
 419     // ------------------------------------------------------------------------
 420     // ITmfTrace - Read operations (returning an actual event)
 421     // ------------------------------------------------------------------------
 422
 423     /* (non-Javadoc)
 424      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#readEvent(org.eclipse.linuxtools.tmf.core.trace.ITmfContext)
 425      */
 426     @Override
 427     public synchronized ITmfEvent readEvent(final ITmfContext context) {
 428         // parseEvent() does not update the context
 429         final ITmfEvent event = fParser.parseEvent(context);
 430         if (event != null) {
 431             updateAttributes(context, event.getTimestamp());
 432             context.setLocation(getCurrentLocation());
 433             context.increaseRank();
 434             processEvent(event);
 435         }
 436         return event;
 437     }
 438
 439     /**
 440      * Hook for special event processing by the concrete class
 441      * (called by TmfTrace.getEvent())
 442      *
 443      * @param event the event
 444      */
 445     protected void processEvent(final ITmfEvent event) {
 446         // Do nothing
 447     }
 448
 449     /**
 450      * Update the trace attributes
 451      *
 452      * @param context the current trace context
 453      * @param rank
 454      * @param timestamp
 455      */
 456     protected synchronized void updateAttributes(final ITmfContext context, final ITmfTimestamp timestamp) {
 457         if (fStartTime.compareTo(timestamp, false) > 0) {
 458             fStartTime = timestamp;
 459         }
 460         if (fEndTime.compareTo(timestamp, false) < 0) {
 461             fEndTime = timestamp;
 462         }
 463         if (context.hasValidRank()) {
 464             long rank = context.getRank();
 465             if (fNbEvents <= rank) {
 466                 fNbEvents = rank + 1;
 467             }
 468             fIndexer.updateIndex(context, timestamp);
 469         }
 470     }
 471
 472     // ------------------------------------------------------------------------
 473     // TmfDataProvider
 474     // ------------------------------------------------------------------------
 475
 476     /* (non-Javadoc)
 477      * @see org.eclipse.linuxtools.tmf.core.component.TmfDataProvider#armRequest(org.eclipse.linuxtools.tmf.core.request.ITmfDataRequest)
 478      */
 479     @Override
 480     public ITmfContext armRequest(final ITmfDataRequest<T> request) {
 481         if (request instanceof ITmfEventRequest<?>
 482         && !TmfTimestamp.BIG_BANG.equals(((ITmfEventRequest<T>) request).getRange().getStartTime())
 483         && request.getIndex() == 0) {
 484             final ITmfContext context = seekEvent(((ITmfEventRequest<T>) request).getRange().getStartTime());
 485             ((ITmfEventRequest<T>) request).setStartIndex((int) context.getRank());
 486             return context;
 487
 488         }
 489         return seekEvent(request.getIndex());
 490     }
 491
 492     /* (non-Javadoc)
 493      * @see org.eclipse.linuxtools.tmf.core.component.TmfDataProvider#getNext(org.eclipse.linuxtools.tmf.core.trace.ITmfContext)
 494      */
 495     @Override
 496     @SuppressWarnings("unchecked")
 497     public T getNext(final ITmfContext context) {
 498         if (context instanceof TmfContext)
 499             return (T) readEvent(context);
 500         return null;
 501     }
 502
 503
 504     // ------------------------------------------------------------------------
 505     // toString
 506     // ------------------------------------------------------------------------
 507
 508     /* (non-Javadoc)
 509      * @see java.lang.Object#toString()
 510      */
 511     @Override
 512     @SuppressWarnings("nls")
 513     public String toString() {
 514         return "TmfTrace [fPath=" + fPath + ", fCacheSize=" + fCacheSize
 515                 + ", fNbEvents=" + fNbEvents + ", fStartTime=" + fStartTime
 516                 + ", fEndTime=" + fEndTime + ", fStreamingInterval=" + fStreamingInterval + "]";
 517     }
 518
 519 }