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
 278         /* Clean up the statistics */
 279         if (fStatistics != null) {
 280             fStatistics.dispose();
 281         }
 282         super.dispose();
 283     }
 284
 285     // ------------------------------------------------------------------------
 286     // ITmfTrace - Basic getters
 287     // ------------------------------------------------------------------------
 288
 289     /* (non-Javadoc)
 290      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getEventType()
 291      */
 292     @Override
 293     public Class<ITmfEvent> getEventType() {
 294         return (Class<ITmfEvent>) super.getType();
 295     }
 296
 297     /* (non-Javadoc)
 298      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getResource()
 299      */
 300     @Override
 301     public IResource getResource() {
 302         return fResource;
 303     }
 304
 305     /* (non-Javadoc)
 306      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getPath()
 307      */
 308     @Override
 309     public String getPath() {
 310         return fPath;
 311     }
 312
 313     /* (non-Javadoc)
 314      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getIndexPageSize()
 315      */
 316     @Override
 317     public int getCacheSize() {
 318         return fCacheSize;
 319     }
 320
 321     /* (non-Javadoc)
 322      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getStreamingInterval()
 323      */
 324     @Override
 325     public long getStreamingInterval() {
 326         return fStreamingInterval;
 327     }
 328
 329     /**
 330      * @return the trace indexer
 331      */
 332     protected ITmfTraceIndexer getIndexer() {
 333         return fIndexer;
 334     }
 335
 336     /**
 337      * @return the trace parser
 338      */
 339     protected ITmfEventParser getParser() {
 340         return fParser;
 341     }
 342
 343     /**
 344      * @since 2.0
 345      */
 346     @Override
 347     public ITmfStatistics getStatistics() {
 348         return fStatistics;
 349     }
 350
 351     /**
 352      * @since 2.0
 353      */
 354     @Override
 355     public ITmfStateSystem getStateSystem() {
 356         /*
 357          * By default, no state system is used. Sub-classes can specify their
 358          * own behaviour.
 359          */
 360         return null;
 361     }
 362
 363     // ------------------------------------------------------------------------
 364     // ITmfTrace - Trace characteristics getters
 365     // ------------------------------------------------------------------------
 366
 367     /* (non-Javadoc)
 368      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getNbEvents()
 369      */
 370     @Override
 371     public synchronized long getNbEvents() {
 372         return fNbEvents;
 373     }
 374
 375     /* (non-Javadoc)
 376      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getTimeRange()
 377      */
 378     @Override
 379     public TmfTimeRange getTimeRange() {
 380         return new TmfTimeRange(fStartTime, fEndTime);
 381     }
 382
 383     /* (non-Javadoc)
 384      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getStartTime()
 385      */
 386     @Override
 387     public ITmfTimestamp getStartTime() {
 388         return fStartTime;
 389     }
 390
 391     /* (non-Javadoc)
 392      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getEndTime()
 393      */
 394     @Override
 395     public ITmfTimestamp getEndTime() {
 396         return fEndTime;
 397     }
 398
 399     // ------------------------------------------------------------------------
 400     // Convenience setters/getters
 401     // ------------------------------------------------------------------------
 402
 403     /**
 404      * Set the trace cache size. Must be done at initialization time.
 405      *
 406      * @param cacheSize The trace cache size
 407      */
 408     protected void setCacheSize(final int cacheSize) {
 409         fCacheSize = cacheSize;
 410     }
 411
 412     /**
 413      * Set the trace known number of events. This can be quite dynamic
 414      * during indexing or for live traces.
 415      *
 416      * @param nbEvents The number of events
 417      */
 418     protected synchronized void setNbEvents(final long nbEvents) {
 419         fNbEvents = (nbEvents > 0) ? nbEvents : 0;
 420     }
 421
 422     /**
 423      * Update the trace events time range
 424      *
 425      * @param range the new time range
 426      */
 427     protected void setTimeRange(final TmfTimeRange range) {
 428         fStartTime = range.getStartTime();
 429         fEndTime = range.getEndTime();
 430     }
 431
 432     /**
 433      * Update the trace chronologically first event timestamp
 434      *
 435      * @param startTime the new first event timestamp
 436      */
 437     protected void setStartTime(final ITmfTimestamp startTime) {
 438         fStartTime = startTime;
 439     }
 440
 441     /**
 442      * Update the trace chronologically last event timestamp
 443      *
 444      * @param endTime the new last event timestamp
 445      */
 446     protected void setEndTime(final ITmfTimestamp endTime) {
 447         fEndTime = endTime;
 448     }
 449
 450     /**
 451      * Set the polling interval for live traces (default = 0 = no streaming).
 452      *
 453      * @param interval the new trace streaming interval
 454      */
 455     protected void setStreamingInterval(final long interval) {
 456         fStreamingInterval = (interval > 0) ? interval : 0;
 457     }
 458
 459     /**
 460      * Set the trace indexer. Must be done at initialization time.
 461      *
 462      * @param indexer the trace indexer
 463      */
 464     protected void setIndexer(final ITmfTraceIndexer indexer) {
 465         fIndexer = indexer;
 466     }
 467
 468     /**
 469      * Set the trace parser. Must be done at initialization time.
 470      *
 471      * @param parser the new trace parser
 472      */
 473     protected void setParser(final ITmfEventParser parser) {
 474         fParser = parser;
 475     }
 476
 477     // ------------------------------------------------------------------------
 478     // ITmfTrace - SeekEvent operations (returning a trace context)
 479     // ------------------------------------------------------------------------
 480
 481     /* (non-Javadoc)
 482      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#seekEvent(long)
 483      */
 484     @Override
 485     public synchronized ITmfContext seekEvent(final long rank) {
 486
 487         // A rank <= 0 indicates to seek the first event
 488         if (rank <= 0) {
 489             ITmfContext context = seekEvent((ITmfLocation) null);
 490             context.setRank(0);
 491             return context;
 492         }
 493
 494         // Position the trace at the checkpoint
 495         final ITmfContext context = fIndexer.seekIndex(rank);
 496
 497         // And locate the requested event context
 498         long pos = context.getRank();
 499         if (pos < rank) {
 500             ITmfEvent event = getNext(context);
 501             while ((event != null) && (++pos < rank)) {
 502                 event = getNext(context);
 503             }
 504         }
 505         return context;
 506     }
 507
 508     /* (non-Javadoc)
 509      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#seekEvent(org.eclipse.linuxtools.tmf.core.event.ITmfTimestamp)
 510      */
 511     @Override
 512     public synchronized ITmfContext seekEvent(final ITmfTimestamp timestamp) {
 513
 514         // A null timestamp indicates to seek the first event
 515         if (timestamp == null) {
 516             ITmfContext context = seekEvent((ITmfLocation) null);
 517             context.setRank(0);
 518             return context;
 519         }
 520
 521         // Position the trace at the checkpoint
 522         ITmfContext context = fIndexer.seekIndex(timestamp);
 523
 524         // And locate the requested event context
 525         final ITmfContext nextEventContext = context.clone(); // Must use clone() to get the right subtype...
 526         ITmfEvent event = getNext(nextEventContext);
 527         while (event != null && event.getTimestamp().compareTo(timestamp, false) < 0) {
 528             context.dispose();
 529             context = nextEventContext.clone();
 530             event = getNext(nextEventContext);
 531         }
 532         nextEventContext.dispose();
 533         if (event == null) {
 534             context.setLocation(null);
 535             context.setRank(ITmfContext.UNKNOWN_RANK);
 536         }
 537         return context;
 538     }
 539
 540     // ------------------------------------------------------------------------
 541     // ITmfTrace - Read operations (returning an actual event)
 542     // ------------------------------------------------------------------------
 543
 544     /* (non-Javadoc)
 545      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#readNextEvent(org.eclipse.linuxtools.tmf.core.trace.ITmfContext)
 546      */
 547     @Override
 548     public synchronized ITmfEvent getNext(final ITmfContext context) {
 549         // parseEvent() does not update the context
 550         final ITmfEvent event = fParser.parseEvent(context);
 551         if (event != null) {
 552             updateAttributes(context, event.getTimestamp());
 553             context.setLocation(getCurrentLocation());
 554             context.increaseRank();
 555             processEvent(event);
 556         }
 557         return event;
 558     }
 559
 560     /**
 561      * Hook for special event processing by the concrete class
 562      * (called by TmfTrace.getEvent())
 563      *
 564      * @param event the event
 565      */
 566     protected void processEvent(final ITmfEvent event) {
 567         // Do nothing
 568     }
 569
 570     /**
 571      * Update the trace attributes
 572      *
 573      * @param context the current trace context
 574      * @param timestamp the corresponding timestamp
 575      */
 576     protected synchronized void updateAttributes(final ITmfContext context, final ITmfTimestamp timestamp) {
 577         if (fStartTime.equals(TmfTimestamp.BIG_BANG) || (fStartTime.compareTo(timestamp, false) > 0)) {
 578             fStartTime = timestamp;
 579         }
 580         if (fEndTime.equals(TmfTimestamp.BIG_CRUNCH) || (fEndTime.compareTo(timestamp, false) < 0)) {
 581             fEndTime = timestamp;
 582         }
 583         if (context.hasValidRank()) {
 584             long rank = context.getRank();
 585             if (fNbEvents <= rank) {
 586                 fNbEvents = rank + 1;
 587             }
 588             if (fIndexer != null) {
 589                 fIndexer.updateIndex(context, timestamp);
 590             }
 591         }
 592     }
 593
 594     // ------------------------------------------------------------------------
 595     // TmfDataProvider
 596     // ------------------------------------------------------------------------
 597
 598     /* (non-Javadoc)
 599      * @see org.eclipse.linuxtools.tmf.core.component.TmfDataProvider#armRequest(org.eclipse.linuxtools.tmf.core.request.ITmfDataRequest)
 600      */
 601     @Override
 602     protected ITmfContext armRequest(final ITmfDataRequest request) {
 603         if ((request instanceof ITmfEventRequest)
 604             && !TmfTimestamp.BIG_BANG.equals(((ITmfEventRequest) request).getRange().getStartTime())
 605             && (request.getIndex() == 0))
 606         {
 607             final ITmfContext context = seekEvent(((ITmfEventRequest) request).getRange().getStartTime());
 608             ((ITmfEventRequest) request).setStartIndex((int) context.getRank());
 609             return context;
 610
 611         }
 612         return seekEvent(request.getIndex());
 613     }
 614
 615     // ------------------------------------------------------------------------
 616     // toString
 617     // ------------------------------------------------------------------------
 618
 619     /* (non-Javadoc)
 620      * @see java.lang.Object#toString()
 621      */
 622     @Override
 623     @SuppressWarnings("nls")
 624     public synchronized String toString() {
 625         return "TmfTrace [fPath=" + fPath + ", fCacheSize=" + fCacheSize
 626                 + ", fNbEvents=" + fNbEvents + ", fStartTime=" + fStartTime
 627                 + ", fEndTime=" + fEndTime + ", fStreamingInterval=" + fStreamingInterval + "]";
 628     }
 629
 630 }