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