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