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.Path;
  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     @SuppressWarnings({ "unchecked", "rawtypes" })
  95     public TmfTrace() {
  96         super();
  97         fIndexer = new TmfCheckpointIndexer(this);
  98     }
  99
 100     /**
 101      * The standard constructor (non-live trace). Applicable when the trace
 102      * implements its own parser and if at checkpoint-based index is OK.
 103      *
 104      * @param resource the resource associated to the trace
 105      * @param type the trace event type
 106      * @param path the trace path
 107      * @param cacheSize the trace cache size
 108      * @throws TmfTraceException
 109      */
 110     protected TmfTrace(final IResource resource, final Class<T> type, final String path, final int cacheSize) throws TmfTraceException {
 111         this(resource, type, path, cacheSize, 0, null);
 112     }
 113
 114     /**
 115      * The standard constructor (live trace). Applicable when the trace
 116      * implements its own parser and if at checkpoint-based index is OK.
 117      *
 118      * @param resource the resource associated to the trace
 119      * @param type the trace event type
 120      * @param path the trace path
 121      * @param cacheSize the trace cache size
 122      * @param interval the trace streaming interval
 123      * @throws TmfTraceException
 124      */
 125     protected TmfTrace(final IResource resource, final Class<T> type, final String path, final int cacheSize, final long interval) throws TmfTraceException {
 126         this(resource, type, path, cacheSize, interval, null);
 127     }
 128
 129     /**
 130      * The 'non-default indexer' constructor. Allows to provide a trace
 131      * specific indexer.
 132      *
 133      * @param resource the resource associated to the trace
 134      * @param type the trace event type
 135      * @param path the trace path
 136      * @param cacheSize the trace cache size
 137      * @param indexer the trace indexer
 138      * @throws TmfTraceException
 139      */
 140     protected TmfTrace(final IResource resource, final Class<T> type, final String path, final int cacheSize,
 141             final long interval, final ITmfTraceIndexer<?> indexer) throws TmfTraceException {
 142         this(resource, type, path, cacheSize, interval, indexer, null);
 143     }
 144
 145     /**
 146      * The full constructor where trace specific indexer/parser are provided.
 147      *
 148      * @param resource the resource associated to the trace
 149      * @param type the trace event type
 150      * @param path the trace path
 151      * @param cacheSize the trace cache size
 152      * @param indexer the trace indexer
 153      * @param parser the trace event parser
 154      * @throws TmfTraceException
 155      */
 156     @SuppressWarnings({ "unchecked", "rawtypes" })
 157     protected TmfTrace(final IResource resource, final Class<T> type, final String path, final int cacheSize,
 158             final long interval, final ITmfTraceIndexer<?> indexer, final ITmfEventParser<T> parser) throws TmfTraceException {
 159         super();
 160         fCacheSize = (cacheSize > 0) ? cacheSize : ITmfTrace.DEFAULT_TRACE_CACHE_SIZE;
 161         fStreamingInterval = interval;
 162         fIndexer = (indexer != null) ? indexer : new TmfCheckpointIndexer(this, fCacheSize);
 163         fParser = parser;
 164         initialize(resource, path, type);
 165     }
 166
 167     /**
 168      * Copy constructor
 169      *
 170      * @param trace the original trace
 171      */
 172     @SuppressWarnings({ "unchecked", "rawtypes" })
 173     public TmfTrace(final TmfTrace<T> trace) throws TmfTraceException {
 174         super();
 175         if (trace == null) {
 176             throw new IllegalArgumentException();
 177         }
 178         fCacheSize = trace.getCacheSize();
 179         fStreamingInterval = trace.getStreamingInterval();
 180         fIndexer = new TmfCheckpointIndexer(this);
 181         fParser = trace.fParser;
 182         initialize(trace.getResource(), trace.getPath(), trace.getEventType());
 183     }
 184
 185     // ------------------------------------------------------------------------
 186     // ITmfTrace - Initializers
 187     // ------------------------------------------------------------------------
 188
 189     /* (non-Javadoc)
 190      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#initTrace(org.eclipse.core.resources.IResource, java.lang.String, java.lang.Class)
 191      */
 192     @Override
 193     public void initTrace(final IResource resource, final String path, final Class<T> type) throws TmfTraceException {
 194         initialize(resource, path, type);
 195         fIndexer.buildIndex(false);
 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(Path.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     // ITmfTrace - Basic getters
 243     // ------------------------------------------------------------------------
 244
 245     /* (non-Javadoc)
 246      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getEventType()
 247      */
 248     @Override
 249     @SuppressWarnings("unchecked")
 250     public Class<T> getEventType() {
 251         return (Class<T>) super.getType();
 252     }
 253
 254     /* (non-Javadoc)
 255      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getResource()
 256      */
 257     @Override
 258     public IResource getResource() {
 259         return fResource;
 260     }
 261
 262     /* (non-Javadoc)
 263      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getPath()
 264      */
 265     @Override
 266     public String getPath() {
 267         return fPath;
 268     }
 269
 270     /* (non-Javadoc)
 271      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getIndexPageSize()
 272      */
 273     @Override
 274     public int getCacheSize() {
 275         return fCacheSize;
 276     }
 277
 278     /* (non-Javadoc)
 279      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getStreamingInterval()
 280      */
 281     @Override
 282     public long getStreamingInterval() {
 283         return fStreamingInterval;
 284     }
 285
 286     /**
 287      * @return the trace indexer
 288      */
 289     protected ITmfTraceIndexer<ITmfTrace<ITmfEvent>> getIndexer() {
 290         return fIndexer;
 291     }
 292
 293     /**
 294      * @return the trace parser
 295      */
 296     protected ITmfEventParser<T> getParser() {
 297         return fParser;
 298     }
 299
 300     // ------------------------------------------------------------------------
 301     // ITmfTrace - Trace characteristics getters
 302     // ------------------------------------------------------------------------
 303
 304     /* (non-Javadoc)
 305      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getNbEvents()
 306      */
 307     @Override
 308     public synchronized long getNbEvents() {
 309         return fNbEvents;
 310     }
 311
 312     /* (non-Javadoc)
 313      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getTimeRange()
 314      */
 315     @Override
 316     public TmfTimeRange getTimeRange() {
 317         return new TmfTimeRange(fStartTime, fEndTime);
 318     }
 319
 320     /* (non-Javadoc)
 321      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getStartTime()
 322      */
 323     @Override
 324     public ITmfTimestamp getStartTime() {
 325         return fStartTime.clone();
 326     }
 327
 328     /* (non-Javadoc)
 329      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getEndTime()
 330      */
 331     @Override
 332     public ITmfTimestamp getEndTime() {
 333         return fEndTime.clone();
 334     }
 335
 336     // ------------------------------------------------------------------------
 337     // Convenience setters/getters
 338     // ------------------------------------------------------------------------
 339
 340     /**
 341      * Set the trace cache size. Must be done at initialization time.
 342      *
 343      * @param cacheSize The trace cache size
 344      */
 345     protected void setCacheSize(final int cacheSize) {
 346         fCacheSize = cacheSize;
 347     }
 348
 349     /**
 350      * Set the trace known number of events. This can be quite dynamic
 351      * during indexing or for live traces.
 352      *
 353      * @param nbEvents The number of events
 354      */
 355     protected synchronized void setNbEvents(final long nbEvents) {
 356         fNbEvents = (nbEvents > 0) ? nbEvents : 0;
 357     }
 358
 359     /**
 360      * Update the trace events time range
 361      *
 362      * @param range the new time range
 363      */
 364     protected void setTimeRange(final TmfTimeRange range) {
 365         fStartTime = range.getStartTime().clone();
 366         fEndTime = range.getEndTime().clone();
 367     }
 368
 369     /**
 370      * Update the trace chronologically first event timestamp
 371      *
 372      * @param startTime the new first event timestamp
 373      */
 374     protected void setStartTime(final ITmfTimestamp startTime) {
 375         fStartTime = startTime.clone();
 376     }
 377
 378     /**
 379      * Update the trace chronologically last event timestamp
 380      *
 381      * @param endTime the new last event timestamp
 382      */
 383     protected void setEndTime(final ITmfTimestamp endTime) {
 384         fEndTime = endTime.clone();
 385     }
 386
 387     /**
 388      * Set the polling interval for live traces (default = 0 = no streaming).
 389      *
 390      * @param interval the new trace streaming interval
 391      */
 392     protected void setStreamingInterval(final long interval) {
 393         fStreamingInterval = (interval > 0) ? interval : 0;
 394     }
 395
 396     /**
 397      * Set the trace indexer. Must be done at initialization time.
 398      *
 399      * @param indexer the trace indexer
 400      */
 401     protected void setIndexer(final ITmfTraceIndexer<ITmfTrace<ITmfEvent>> indexer) {
 402         fIndexer = indexer;
 403     }
 404
 405     /**
 406      * Set the trace parser. Must be done at initialization time.
 407      *
 408      * @param parser the new trace parser
 409      */
 410     protected void setParser(final ITmfEventParser<T> parser) {
 411         fParser = parser;
 412     }
 413
 414     // ------------------------------------------------------------------------
 415     // ITmfTrace - SeekEvent operations (returning a trace context)
 416     // ------------------------------------------------------------------------
 417
 418     /* (non-Javadoc)
 419      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#seekEvent(long)
 420      */
 421     @Override
 422     public synchronized ITmfContext seekEvent(final long rank) {
 423
 424         // A rank <= 0 indicates to seek the first event
 425         if (rank <= 0) {
 426             ITmfContext context = seekEvent((ITmfLocation<?>) null);
 427             context.setRank(0);
 428             return context;
 429         }
 430
 431         // Position the trace at the checkpoint
 432         final ITmfContext context = fIndexer.seekIndex(rank);
 433
 434         // And locate the requested event context
 435         long pos = context.getRank();
 436         if (pos < rank) {
 437             ITmfEvent event = readNextEvent(context);
 438             while (event != null && ++pos < rank) {
 439                 event = readNextEvent(context);
 440             }
 441         }
 442         return context;
 443     }
 444
 445     /* (non-Javadoc)
 446      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#seekEvent(org.eclipse.linuxtools.tmf.core.event.ITmfTimestamp)
 447      */
 448     @Override
 449     public synchronized ITmfContext seekEvent(final ITmfTimestamp timestamp) {
 450
 451         // A null timestamp indicates to seek the first event
 452         if (timestamp == null) {
 453             ITmfContext context = seekEvent((ITmfLocation<?>) null);
 454             context.setRank(0);
 455             return context;
 456         }
 457
 458         // Position the trace at the checkpoint
 459         final ITmfContext context = fIndexer.seekIndex(timestamp);
 460
 461         // And locate the requested event context
 462         final ITmfContext nextEventContext = context.clone(); // Must use clone() to get the right subtype...
 463         ITmfEvent event = readNextEvent(nextEventContext);
 464         while (event != null && event.getTimestamp().compareTo(timestamp, false) < 0) {
 465             context.setLocation(nextEventContext.getLocation().clone());
 466             context.increaseRank();
 467             event = readNextEvent(nextEventContext);
 468         }
 469         if (event == null) {
 470             context.setLocation(null);
 471             context.setRank(ITmfContext.UNKNOWN_RANK);
 472         }
 473         return context;
 474     }
 475
 476     // ------------------------------------------------------------------------
 477     // ITmfTrace - Read operations (returning an actual event)
 478     // ------------------------------------------------------------------------
 479
 480     /* (non-Javadoc)
 481      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#readNextEvent(org.eclipse.linuxtools.tmf.core.trace.ITmfContext)
 482      */
 483     @Override
 484     public synchronized ITmfEvent readNextEvent(final ITmfContext context) {
 485         // parseEvent() does not update the context
 486         final ITmfEvent event = fParser.parseEvent(context);
 487         if (event != null) {
 488             updateAttributes(context, event.getTimestamp());
 489             context.setLocation(getCurrentLocation());
 490             context.increaseRank();
 491             processEvent(event);
 492         }
 493         return event;
 494     }
 495
 496     /**
 497      * Hook for special event processing by the concrete class
 498      * (called by TmfTrace.getEvent())
 499      *
 500      * @param event the event
 501      */
 502     protected void processEvent(final ITmfEvent event) {
 503         // Do nothing
 504     }
 505
 506     /**
 507      * Update the trace attributes
 508      *
 509      * @param context the current trace context
 510      * @param timestamp the corresponding timestamp
 511      */
 512     protected synchronized void updateAttributes(final ITmfContext context, final ITmfTimestamp timestamp) {
 513         if (fStartTime.compareTo(timestamp, false) > 0) {
 514             fStartTime = timestamp;
 515         }
 516         if (fEndTime.compareTo(timestamp, false) < 0) {
 517             fEndTime = timestamp;
 518         }
 519         if (context.hasValidRank()) {
 520             long rank = context.getRank();
 521             if (fNbEvents <= rank) {
 522                 fNbEvents = rank + 1;
 523             }
 524             fIndexer.updateIndex(context, timestamp);
 525         }
 526     }
 527
 528     // ------------------------------------------------------------------------
 529     // TmfDataProvider
 530     // ------------------------------------------------------------------------
 531
 532     /* (non-Javadoc)
 533      * @see org.eclipse.linuxtools.tmf.core.component.TmfDataProvider#armRequest(org.eclipse.linuxtools.tmf.core.request.ITmfDataRequest)
 534      */
 535     @Override
 536     public ITmfContext armRequest(final ITmfDataRequest<T> request) {
 537         if (request instanceof ITmfEventRequest<?>
 538             && !TmfTimestamp.BIG_BANG.equals(((ITmfEventRequest<T>) request).getRange().getStartTime())
 539             && request.getIndex() == 0)
 540         {
 541             final ITmfContext context = seekEvent(((ITmfEventRequest<T>) request).getRange().getStartTime());
 542             ((ITmfEventRequest<T>) request).setStartIndex((int) context.getRank());
 543             return context;
 544
 545         }
 546         return seekEvent(request.getIndex());
 547     }
 548
 549     /* (non-Javadoc)
 550      * @see org.eclipse.linuxtools.tmf.core.component.TmfDataProvider#getNext(org.eclipse.linuxtools.tmf.core.trace.ITmfContext)
 551      */
 552     @Override
 553     @SuppressWarnings("unchecked")
 554     public T getNext(final ITmfContext context) {
 555         if (context instanceof TmfContext) {
 556             return (T) readNextEvent(context);
 557         }
 558         return null;
 559     }
 560
 561
 562     // ------------------------------------------------------------------------
 563     // toString
 564     // ------------------------------------------------------------------------
 565
 566     /* (non-Javadoc)
 567      * @see java.lang.Object#toString()
 568      */
 569     @Override
 570     @SuppressWarnings("nls")
 571     public synchronized String toString() {
 572         return "TmfTrace [fPath=" + fPath + ", fCacheSize=" + fCacheSize
 573                 + ", fNbEvents=" + fNbEvents + ", fStartTime=" + fStartTime
 574                 + ", fEndTime=" + fEndTime + ", fStreamingInterval=" + fStreamingInterval + "]";
 575     }
 576
 577 }