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 extends TmfEventProvider implements ITmfTrace {
  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 fIndexer;
  83
  84     // The trace parser
  85     private ITmfEventParser 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<? extends ITmfEvent> 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<? extends ITmfEvent> 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<? extends ITmfEvent> 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     protected TmfTrace(final IResource resource, final Class<? extends ITmfEvent> type, final String path, final int cacheSize,
 155             final long interval, final ITmfTraceIndexer indexer, final ITmfEventParser parser) throws TmfTraceException {
 156         super();
 157         fCacheSize = (cacheSize > 0) ? cacheSize : ITmfTrace.DEFAULT_TRACE_CACHE_SIZE;
 158         fStreamingInterval = interval;
 159         fIndexer = (indexer != null) ? indexer : new TmfCheckpointIndexer(this, fCacheSize);
 160         fParser = parser;
 161         initialize(resource, path, type);
 162     }
 163
 164     /**
 165      * Copy constructor
 166      *
 167      * @param trace the original trace
 168      * @throws TmfTraceException Should not happen usually
 169      */
 170     public TmfTrace(final TmfTrace trace) throws TmfTraceException {
 171         super();
 172         if (trace == null) {
 173             throw new IllegalArgumentException();
 174         }
 175         fCacheSize = trace.getCacheSize();
 176         fStreamingInterval = trace.getStreamingInterval();
 177         fIndexer = new TmfCheckpointIndexer(this);
 178         fParser = trace.fParser;
 179         initialize(trace.getResource(), trace.getPath(), trace.getEventType());
 180     }
 181
 182     // ------------------------------------------------------------------------
 183     // ITmfTrace - Initializers
 184     // ------------------------------------------------------------------------
 185
 186     /* (non-Javadoc)
 187      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#initTrace(org.eclipse.core.resources.IResource, java.lang.String, java.lang.Class)
 188      */
 189     @Override
 190     public void initTrace(final IResource resource, final String path, final Class<? extends ITmfEvent> type) throws TmfTraceException {
 191         fIndexer = new TmfCheckpointIndexer(this, fCacheSize);
 192         initialize(resource, path, type);
 193     }
 194
 195     /**
 196      * Initialize the trace common attributes and the base component.
 197      *
 198      * @param resource the Eclipse resource (trace)
 199      * @param path the trace path
 200      * @param type the trace event type
 201      *
 202      * @throws TmfTraceException
 203      */
 204     protected void initialize(final IResource resource, final String path, final Class<? extends ITmfEvent> type) throws TmfTraceException {
 205         if (path == null) {
 206             throw new TmfTraceException("Invalid trace path"); //$NON-NLS-1$
 207         }
 208         fPath = path;
 209         fResource = resource;
 210         String traceName = (resource != null) ? resource.getName() : null;
 211         // If no resource was provided, extract the display name the trace path
 212         if (traceName == null) {
 213             final int sep = path.lastIndexOf(IPath.SEPARATOR);
 214             traceName = (sep >= 0) ? path.substring(sep + 1) : path;
 215         }
 216         if (fParser == null) {
 217             if (this instanceof ITmfEventParser) {
 218                 fParser = (ITmfEventParser) this;
 219             } else {
 220                 throw new TmfTraceException("Invalid trace parser"); //$NON-NLS-1$
 221             }
 222         }
 223         super.init(traceName, type);
 224     }
 225
 226     /**
 227      * Indicates if the path points to an existing file/directory
 228      *
 229      * @param path the path to test
 230      * @return true if the file/directory exists
 231      */
 232     protected boolean fileExists(final String path) {
 233         final File file = new File(path);
 234         return file.exists();
 235     }
 236
 237     /**
 238      * Index the trace
 239      *
 240      * @param waitForCompletion index synchronously (true) or not (false)
 241      */
 242     protected void indexTrace(boolean waitForCompletion) {
 243         getIndexer().buildIndex(0, TmfTimeRange.ETERNITY, waitForCompletion);
 244     }
 245
 246     /**
 247      * Clears the trace
 248      */
 249     @Override
 250     public synchronized void dispose() {
 251         // Clean up the index if applicable
 252         if (getIndexer() != null) {
 253             getIndexer().dispose();
 254         }
 255         super.dispose();
 256     }
 257
 258     // ------------------------------------------------------------------------
 259     // ITmfTrace - Basic getters
 260     // ------------------------------------------------------------------------
 261
 262     /* (non-Javadoc)
 263      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getEventType()
 264      */
 265     @Override
 266     public Class<ITmfEvent> getEventType() {
 267         return (Class<ITmfEvent>) super.getType();
 268     }
 269
 270     /* (non-Javadoc)
 271      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getResource()
 272      */
 273     @Override
 274     public IResource getResource() {
 275         return fResource;
 276     }
 277
 278     /* (non-Javadoc)
 279      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getPath()
 280      */
 281     @Override
 282     public String getPath() {
 283         return fPath;
 284     }
 285
 286     /* (non-Javadoc)
 287      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getIndexPageSize()
 288      */
 289     @Override
 290     public int getCacheSize() {
 291         return fCacheSize;
 292     }
 293
 294     /* (non-Javadoc)
 295      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getStreamingInterval()
 296      */
 297     @Override
 298     public long getStreamingInterval() {
 299         return fStreamingInterval;
 300     }
 301
 302     /**
 303      * @return the trace indexer
 304      */
 305     protected ITmfTraceIndexer getIndexer() {
 306         return fIndexer;
 307     }
 308
 309     /**
 310      * @return the trace parser
 311      */
 312     protected ITmfEventParser getParser() {
 313         return fParser;
 314     }
 315
 316     // ------------------------------------------------------------------------
 317     // ITmfTrace - Trace characteristics getters
 318     // ------------------------------------------------------------------------
 319
 320     /* (non-Javadoc)
 321      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getNbEvents()
 322      */
 323     @Override
 324     public synchronized long getNbEvents() {
 325         return fNbEvents;
 326     }
 327
 328     /* (non-Javadoc)
 329      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getTimeRange()
 330      */
 331     @Override
 332     public TmfTimeRange getTimeRange() {
 333         return new TmfTimeRange(fStartTime, fEndTime);
 334     }
 335
 336     /* (non-Javadoc)
 337      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getStartTime()
 338      */
 339     @Override
 340     public ITmfTimestamp getStartTime() {
 341         return fStartTime.clone();
 342     }
 343
 344     /* (non-Javadoc)
 345      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getEndTime()
 346      */
 347     @Override
 348     public ITmfTimestamp getEndTime() {
 349         return fEndTime.clone();
 350     }
 351
 352     // ------------------------------------------------------------------------
 353     // Convenience setters/getters
 354     // ------------------------------------------------------------------------
 355
 356     /**
 357      * Set the trace cache size. Must be done at initialization time.
 358      *
 359      * @param cacheSize The trace cache size
 360      */
 361     protected void setCacheSize(final int cacheSize) {
 362         fCacheSize = cacheSize;
 363     }
 364
 365     /**
 366      * Set the trace known number of events. This can be quite dynamic
 367      * during indexing or for live traces.
 368      *
 369      * @param nbEvents The number of events
 370      */
 371     protected synchronized void setNbEvents(final long nbEvents) {
 372         fNbEvents = (nbEvents > 0) ? nbEvents : 0;
 373     }
 374
 375     /**
 376      * Update the trace events time range
 377      *
 378      * @param range the new time range
 379      */
 380     protected void setTimeRange(final TmfTimeRange range) {
 381         fStartTime = range.getStartTime().clone();
 382         fEndTime = range.getEndTime().clone();
 383     }
 384
 385     /**
 386      * Update the trace chronologically first event timestamp
 387      *
 388      * @param startTime the new first event timestamp
 389      */
 390     protected void setStartTime(final ITmfTimestamp startTime) {
 391         fStartTime = startTime.clone();
 392     }
 393
 394     /**
 395      * Update the trace chronologically last event timestamp
 396      *
 397      * @param endTime the new last event timestamp
 398      */
 399     protected void setEndTime(final ITmfTimestamp endTime) {
 400         fEndTime = endTime.clone();
 401     }
 402
 403     /**
 404      * Set the polling interval for live traces (default = 0 = no streaming).
 405      *
 406      * @param interval the new trace streaming interval
 407      */
 408     protected void setStreamingInterval(final long interval) {
 409         fStreamingInterval = (interval > 0) ? interval : 0;
 410     }
 411
 412     /**
 413      * Set the trace indexer. Must be done at initialization time.
 414      *
 415      * @param indexer the trace indexer
 416      */
 417     protected void setIndexer(final ITmfTraceIndexer indexer) {
 418         fIndexer = indexer;
 419     }
 420
 421     /**
 422      * Set the trace parser. Must be done at initialization time.
 423      *
 424      * @param parser the new trace parser
 425      */
 426     protected void setParser(final ITmfEventParser parser) {
 427         fParser = parser;
 428     }
 429
 430     // ------------------------------------------------------------------------
 431     // ITmfTrace - SeekEvent operations (returning a trace context)
 432     // ------------------------------------------------------------------------
 433
 434     /* (non-Javadoc)
 435      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#seekEvent(long)
 436      */
 437     @Override
 438     public synchronized ITmfContext seekEvent(final long rank) {
 439
 440         // A rank <= 0 indicates to seek the first event
 441         if (rank <= 0) {
 442             ITmfContext context = seekEvent((ITmfLocation<?>) null);
 443             context.setRank(0);
 444             return context;
 445         }
 446
 447         // Position the trace at the checkpoint
 448         final ITmfContext context = fIndexer.seekIndex(rank);
 449
 450         // And locate the requested event context
 451         long pos = context.getRank();
 452         if (pos < rank) {
 453             ITmfEvent event = getNext(context);
 454             while ((event != null) && (++pos < rank)) {
 455                 event = getNext(context);
 456             }
 457         }
 458         return context;
 459     }
 460
 461     /* (non-Javadoc)
 462      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#seekEvent(org.eclipse.linuxtools.tmf.core.event.ITmfTimestamp)
 463      */
 464     @Override
 465     public synchronized ITmfContext seekEvent(final ITmfTimestamp timestamp) {
 466
 467         // A null timestamp indicates to seek the first event
 468         if (timestamp == null) {
 469             ITmfContext context = seekEvent((ITmfLocation<?>) null);
 470             context.setRank(0);
 471             return context;
 472         }
 473
 474         // Position the trace at the checkpoint
 475         ITmfContext context = fIndexer.seekIndex(timestamp);
 476
 477         // And locate the requested event context
 478         final ITmfContext nextEventContext = context.clone(); // Must use clone() to get the right subtype...
 479         ITmfEvent event = getNext(nextEventContext);
 480         while (event != null && event.getTimestamp().compareTo(timestamp, false) < 0) {
 481             context = nextEventContext.clone();
 482             event = getNext(nextEventContext);
 483         }
 484         if (event == null) {
 485             context.setLocation(null);
 486             context.setRank(ITmfContext.UNKNOWN_RANK);
 487         }
 488         return context;
 489     }
 490
 491     // ------------------------------------------------------------------------
 492     // ITmfTrace - Read operations (returning an actual event)
 493     // ------------------------------------------------------------------------
 494
 495     /* (non-Javadoc)
 496      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#readNextEvent(org.eclipse.linuxtools.tmf.core.trace.ITmfContext)
 497      */
 498     @Override
 499     public synchronized ITmfEvent getNext(final ITmfContext context) {
 500         // parseEvent() does not update the context
 501         final ITmfEvent event = fParser.parseEvent(context);
 502         if (event != null) {
 503             updateAttributes(context, event.getTimestamp());
 504             context.setLocation(getCurrentLocation());
 505             context.increaseRank();
 506             processEvent(event);
 507         }
 508         return event;
 509     }
 510
 511     /**
 512      * Hook for special event processing by the concrete class
 513      * (called by TmfTrace.getEvent())
 514      *
 515      * @param event the event
 516      */
 517     protected void processEvent(final ITmfEvent event) {
 518         // Do nothing
 519     }
 520
 521     /**
 522      * Update the trace attributes
 523      *
 524      * @param context the current trace context
 525      * @param timestamp the corresponding timestamp
 526      */
 527     protected synchronized void updateAttributes(final ITmfContext context, final ITmfTimestamp timestamp) {
 528         if (fStartTime.equals(TmfTimestamp.BIG_BANG) || (fStartTime.compareTo(timestamp, false) > 0)) {
 529             fStartTime = timestamp.clone();
 530         }
 531         if (fEndTime.equals(TmfTimestamp.BIG_CRUNCH) || (fEndTime.compareTo(timestamp, false) < 0)) {
 532             fEndTime = timestamp.clone();
 533         }
 534         if (context.hasValidRank()) {
 535             long rank = context.getRank();
 536             if (fNbEvents <= rank) {
 537                 fNbEvents = rank + 1;
 538             }
 539             fIndexer.updateIndex(context, timestamp);
 540         }
 541     }
 542
 543     // ------------------------------------------------------------------------
 544     // TmfDataProvider
 545     // ------------------------------------------------------------------------
 546
 547     /* (non-Javadoc)
 548      * @see org.eclipse.linuxtools.tmf.core.component.TmfDataProvider#armRequest(org.eclipse.linuxtools.tmf.core.request.ITmfDataRequest)
 549      */
 550     @Override
 551     protected ITmfContext armRequest(final ITmfDataRequest request) {
 552         if ((request instanceof ITmfEventRequest)
 553             && !TmfTimestamp.BIG_BANG.equals(((ITmfEventRequest) request).getRange().getStartTime())
 554             && (request.getIndex() == 0))
 555         {
 556             final ITmfContext context = seekEvent(((ITmfEventRequest) request).getRange().getStartTime());
 557             ((ITmfEventRequest) request).setStartIndex((int) context.getRank());
 558             return context;
 559
 560         }
 561         return seekEvent(request.getIndex());
 562     }
 563
 564     // ------------------------------------------------------------------------
 565     // toString
 566     // ------------------------------------------------------------------------
 567
 568     /* (non-Javadoc)
 569      * @see java.lang.Object#toString()
 570      */
 571     @Override
 572     @SuppressWarnings("nls")
 573     public synchronized String toString() {
 574         return "TmfTrace [fPath=" + fPath + ", fCacheSize=" + fCacheSize
 575                 + ", fNbEvents=" + fNbEvents + ", fStartTime=" + fStartTime
 576                 + ", fEndTime=" + fEndTime + ", fStreamingInterval=" + fStreamingInterval + "]";
 577     }
 578
 579 }