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