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 import java.io.FileNotFoundException;
  18
  19 import org.eclipse.core.resources.IResource;
  20 import org.eclipse.core.runtime.Path;
  21 import org.eclipse.linuxtools.tmf.core.component.TmfEventProvider;
  22 import org.eclipse.linuxtools.tmf.core.event.ITmfEvent;
  23 import org.eclipse.linuxtools.tmf.core.event.ITmfTimestamp;
  24 import org.eclipse.linuxtools.tmf.core.event.TmfTimeRange;
  25 import org.eclipse.linuxtools.tmf.core.event.TmfTimestamp;
  26 import org.eclipse.linuxtools.tmf.core.exceptions.TmfTraceException;
  27 import org.eclipse.linuxtools.tmf.core.request.ITmfDataRequest;
  28 import org.eclipse.linuxtools.tmf.core.request.ITmfEventRequest;
  29
  30 /**
  31  * Abstract implementation of ITmfTrace.
  32  * <p>
  33  * Since the concept of 'location' is trace specific, the concrete classes have
  34  * to provide the related methods, namely:
  35  * <ul>
  36  * <li> public ITmfLocation<?> getCurrentLocation()
  37  * <li> public double getLocationRatio(ITmfLocation<?> location)
  38  * <li> public ITmfContext seekEvent(ITmfLocation<?> location)
  39  * <li> public ITmfContext seekEvent(double ratio)
  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  * @since 1.0
  50  * @version 1.0
  51  * @author Francois Chouinard
  52  *
  53  * @see ITmfTrace
  54  * @see TmfEventProvider
  55  * @see ITmfEvent
  56  * @see ITmfTraceIndexer
  57  * @see ITmfEventParser
  58  */
  59 public abstract class TmfTrace<T extends ITmfEvent> extends TmfEventProvider<T> implements ITmfTrace<T> {
  60
  61     // ------------------------------------------------------------------------
  62     // Constants
  63     // ------------------------------------------------------------------------
  64
  65     /**
  66      * The default trace cache size
  67      */
  68     public static final int DEFAULT_TRACE_CACHE_SIZE = 10000;
  69
  70     // ------------------------------------------------------------------------
  71     // Attributes
  72     // ------------------------------------------------------------------------
  73
  74     // The resource used for persistent properties for this trace
  75     private IResource fResource;
  76
  77     // The trace path
  78     private String fPath;
  79
  80     /**
  81      * The cache page size
  82      */
  83     protected int fCacheSize = DEFAULT_TRACE_CACHE_SIZE;
  84
  85     /**
  86      * The number of events collected so far
  87      */
  88     protected long fNbEvents = 0;
  89
  90     // The time span of the event stream
  91     private ITmfTimestamp fStartTime = TmfTimestamp.BIG_CRUNCH;
  92     private ITmfTimestamp fEndTime = TmfTimestamp.BIG_BANG;
  93
  94     /**
  95      * The trace streaming interval (0 = no streaming)
  96      */
  97     protected long fStreamingInterval = 0;
  98
  99     /**
 100      * The trace indexer
 101      */
 102     protected ITmfTraceIndexer<ITmfTrace<ITmfEvent>> fIndexer;
 103
 104     /**
 105      * The trace parser
 106      */
 107     protected ITmfEventParser<T> fParser;
 108
 109     // ------------------------------------------------------------------------
 110     // Construction
 111     // ------------------------------------------------------------------------
 112
 113     /**
 114      * The default, parameterless, constructor
 115      */
 116     @SuppressWarnings({ "unchecked", "rawtypes" })
 117     public TmfTrace() {
 118         super();
 119         fIndexer = new TmfCheckpointIndexer(this);
 120     }
 121
 122     /**
 123      * The standard constructor (non-live trace). Applicable when the trace
 124      * implements its own parser and if at checkpoint-based index is OK.
 125      *
 126      * @param resource the resource associated to the trace
 127      * @param type the trace event type
 128      * @param path the trace path
 129      * @param cacheSize the trace cache size
 130      * @throws TmfTraceException
 131      */
 132     protected TmfTrace(final IResource resource, final Class<T> type, final String path, final int cacheSize) throws TmfTraceException {
 133         this(resource, type, path, cacheSize, 0, null);
 134     }
 135
 136     /**
 137      * The standard constructor (live trace). Applicable when the trace
 138      * implements its own parser and if at checkpoint-based index is OK.
 139      *
 140      * @param resource the resource associated to the trace
 141      * @param type the trace event type
 142      * @param path the trace path
 143      * @param cacheSize the trace cache size
 144      * @param interval the trace streaming interval
 145      * @throws TmfTraceException
 146      */
 147     protected TmfTrace(final IResource resource, final Class<T> type, final String path, final int cacheSize, final long interval) throws TmfTraceException {
 148         this(resource, type, path, cacheSize, interval, null);
 149     }
 150
 151     /**
 152      * The 'non-default indexer' constructor. Allows to provide a trace
 153      * specific indexer.
 154      *
 155      * @param resource the resource associated to the trace
 156      * @param type the trace event type
 157      * @param path the trace path
 158      * @param cacheSize the trace cache size
 159      * @param indexer the trace indexer
 160      * @throws TmfTraceException
 161      */
 162     protected TmfTrace(final IResource resource, final Class<T> type, final String path, final int cacheSize,
 163             final long interval, final ITmfTraceIndexer<?> indexer) throws TmfTraceException {
 164         this(resource, type, path, cacheSize, interval, null, null);
 165     }
 166
 167     /**
 168      * The full constructor where trace specific indexer/parser are provided.
 169      *
 170      * @param resource the resource associated to the trace
 171      * @param type the trace event type
 172      * @param path the trace path
 173      * @param cacheSize the trace cache size
 174      * @param indexer the trace indexer
 175      * @param parser the trace event parser
 176      * @throws TmfTraceException
 177      */
 178     @SuppressWarnings({ "unchecked", "rawtypes" })
 179     protected TmfTrace(final IResource resource, final Class<T> type, final String path, final int cacheSize,
 180             final long interval, final ITmfTraceIndexer<?> indexer, final ITmfEventParser<T> parser) throws TmfTraceException {
 181         super();
 182         fCacheSize = (cacheSize > 0) ? cacheSize : DEFAULT_TRACE_CACHE_SIZE;
 183         fStreamingInterval = interval;
 184         fIndexer = (indexer != null) ? indexer : new TmfCheckpointIndexer(this, fCacheSize);
 185         fParser = parser;
 186         initialize(resource, path, type);
 187     }
 188
 189     /**
 190      * Copy constructor
 191      *
 192      * @param trace the original trace
 193      */
 194     @SuppressWarnings({ "unchecked", "rawtypes" })
 195     public TmfTrace(final TmfTrace<T> trace) throws TmfTraceException {
 196         super();
 197         if (trace == null)
 198             throw new IllegalArgumentException();
 199         fCacheSize = trace.getCacheSize();
 200         fStreamingInterval = trace.getStreamingInterval();
 201         fIndexer = new TmfCheckpointIndexer(this);
 202         fParser = trace.fParser;
 203         initialize(trace.getResource(), trace.getPath(), trace.getEventType());
 204     }
 205
 206     // ------------------------------------------------------------------------
 207     // ITmfTrace - Initializers
 208     // ------------------------------------------------------------------------
 209
 210     /* (non-Javadoc)
 211      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#initTrace(org.eclipse.core.resources.IResource, java.lang.String, java.lang.Class)
 212      */
 213     @Override
 214     public void initTrace(final IResource resource, final String path, final Class<T> type) throws TmfTraceException {
 215         initialize(resource, path, type);
 216         fIndexer.buildIndex(false);
 217     }
 218
 219     /**
 220      * Initialize the trace common attributes and the base component.
 221      *
 222      * @param resource the Eclipse resource (trace)
 223      * @param path the trace path
 224      * @param type the trace event type
 225      *
 226      * @throws FileNotFoundException
 227      */
 228     @SuppressWarnings("unchecked")
 229     protected void initialize(final IResource resource, final String path, final Class<T> type) throws TmfTraceException {
 230         if (path == null)
 231             throw new TmfTraceException("Invalid trace path"); //$NON-NLS-1$
 232         fPath = path;
 233         fResource = resource;
 234         String traceName = (resource != null) ? resource.getName() : null;
 235         // If no resource was provided, extract the display name the trace path
 236         if (traceName == null) {
 237             final int sep = path.lastIndexOf(Path.SEPARATOR);
 238             traceName = (sep >= 0) ? path.substring(sep + 1) : path;
 239         }
 240         if (fParser == null) {
 241             if (this instanceof ITmfEventParser) {
 242                 fParser = (ITmfEventParser<T>) this;
 243             } else {
 244                 throw new TmfTraceException("Invalid trace parser"); //$NON-NLS-1$
 245             }
 246         }
 247         super.init(traceName, type);
 248     }
 249
 250     /**
 251      * Indicates if the path points to an existing file/directory
 252      *
 253      * @param path the path to test
 254      * @return true if the file/directory exists
 255      */
 256     protected boolean fileExists(final String path) {
 257         final File file = new File(path);
 258         return file.exists();
 259     }
 260
 261     // ------------------------------------------------------------------------
 262     // ITmfTrace - Basic getters
 263     // ------------------------------------------------------------------------
 264
 265     /* (non-Javadoc)
 266      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getEventType()
 267      */
 268     @Override
 269     @SuppressWarnings("unchecked")
 270     public Class<T> getEventType() {
 271         return (Class<T>) super.getType();
 272     }
 273
 274     /* (non-Javadoc)
 275      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getResource()
 276      */
 277     @Override
 278     public IResource getResource() {
 279         return fResource;
 280     }
 281
 282     /* (non-Javadoc)
 283      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getPath()
 284      */
 285     @Override
 286     public String getPath() {
 287         return fPath;
 288     }
 289
 290     /* (non-Javadoc)
 291      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getIndexPageSize()
 292      */
 293     @Override
 294     public int getCacheSize() {
 295         return fCacheSize;
 296     }
 297
 298     /* (non-Javadoc)
 299      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getStreamingInterval()
 300      */
 301     @Override
 302     public long getStreamingInterval() {
 303         return fStreamingInterval;
 304     }
 305
 306     // ------------------------------------------------------------------------
 307     // ITmfTrace - Trace characteristics getters
 308     // ------------------------------------------------------------------------
 309
 310     /* (non-Javadoc)
 311      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getNbEvents()
 312      */
 313     @Override
 314     public synchronized long getNbEvents() {
 315         return fNbEvents;
 316     }
 317
 318     /* (non-Javadoc)
 319      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getTimeRange()
 320      */
 321     @Override
 322     public TmfTimeRange getTimeRange() {
 323         return new TmfTimeRange(fStartTime, fEndTime);
 324     }
 325
 326     /* (non-Javadoc)
 327      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getStartTime()
 328      */
 329     @Override
 330     public ITmfTimestamp getStartTime() {
 331         return fStartTime.clone();
 332     }
 333
 334     /* (non-Javadoc)
 335      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getEndTime()
 336      */
 337     @Override
 338     public ITmfTimestamp getEndTime() {
 339         return fEndTime.clone();
 340     }
 341
 342     // ------------------------------------------------------------------------
 343     // Convenience setters
 344     // ------------------------------------------------------------------------
 345
 346     /**
 347      * Update the trace events time range
 348      *
 349      * @param range the new time range
 350      */
 351     protected void setTimeRange(final TmfTimeRange range) {
 352         fStartTime = range.getStartTime().clone();
 353         fEndTime = range.getEndTime().clone();
 354     }
 355
 356     /**
 357      * Update the trace chronologically first event timestamp
 358      *
 359      * @param startTime the new first event timestamp
 360      */
 361     protected void setStartTime(final ITmfTimestamp startTime) {
 362         fStartTime = startTime.clone();
 363     }
 364
 365     /**
 366      * Update the trace chronologically last event timestamp
 367      *
 368      * @param endTime the new last event timestamp
 369      */
 370     protected void setEndTime(final ITmfTimestamp endTime) {
 371         fEndTime = endTime.clone();
 372     }
 373
 374     /**
 375      * Update the trace streaming interval
 376      *
 377      * @param interval the new trace streaming interval
 378      */
 379     protected void setStreamingInterval(final long interval) {
 380         fStreamingInterval = (interval > 0) ? interval : 0;
 381     }
 382
 383     // ------------------------------------------------------------------------
 384     // ITmfTrace - SeekEvent operations (returning a trace context)
 385     // ------------------------------------------------------------------------
 386
 387     /* (non-Javadoc)
 388      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#seekEvent(long)
 389      */
 390     @Override
 391     public synchronized ITmfContext seekEvent(final long rank) {
 392
 393         // A rank <= 0 indicates to seek the first event
 394         if (rank <= 0) {
 395             ITmfContext context = seekEvent((ITmfLocation<?>) null);
 396             context.setRank(0);
 397             return context;
 398         }
 399
 400         // Position the trace at the checkpoint
 401         final ITmfContext context = fIndexer.seekIndex(rank);
 402
 403         // And locate the requested event context
 404         long pos = context.getRank();
 405         if (pos < rank) {
 406             ITmfEvent event = readNextEvent(context);
 407             while (event != null && ++pos < rank) {
 408                 event = readNextEvent(context);
 409             }
 410         }
 411         return context;
 412     }
 413
 414     /* (non-Javadoc)
 415      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#seekEvent(org.eclipse.linuxtools.tmf.core.event.ITmfTimestamp)
 416      */
 417     @Override
 418     public synchronized ITmfContext seekEvent(final ITmfTimestamp timestamp) {
 419
 420         // A null timestamp indicates to seek the first event
 421         if (timestamp == null) {
 422             ITmfContext context = seekEvent((ITmfLocation<?>) null);
 423             context.setRank(0);
 424             return context;
 425         }
 426
 427         // Position the trace at the checkpoint
 428         final ITmfContext context = fIndexer.seekIndex(timestamp);
 429
 430         // And locate the requested event context
 431         final ITmfContext nextEventContext = context.clone(); // Must use clone() to get the right subtype...
 432         ITmfEvent event = readNextEvent(nextEventContext);
 433         while (event != null && event.getTimestamp().compareTo(timestamp, false) < 0) {
 434             context.setLocation(nextEventContext.getLocation().clone());
 435             context.increaseRank();
 436             event = readNextEvent(nextEventContext);
 437         }
 438         return context;
 439     }
 440
 441     // ------------------------------------------------------------------------
 442     // ITmfTrace - Read operations (returning an actual event)
 443     // ------------------------------------------------------------------------
 444
 445     /* (non-Javadoc)
 446      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#readNextEvent(org.eclipse.linuxtools.tmf.core.trace.ITmfContext)
 447      */
 448     @Override
 449     public synchronized ITmfEvent readNextEvent(final ITmfContext context) {
 450         // parseEvent() does not update the context
 451         final ITmfEvent event = fParser.parseEvent(context);
 452         if (event != null) {
 453             updateAttributes(context, event.getTimestamp());
 454             context.setLocation(getCurrentLocation());
 455             context.increaseRank();
 456             processEvent(event);
 457         }
 458         return event;
 459     }
 460
 461     /**
 462      * Hook for special event processing by the concrete class
 463      * (called by TmfTrace.getEvent())
 464      *
 465      * @param event the event
 466      */
 467     protected void processEvent(final ITmfEvent event) {
 468         // Do nothing
 469     }
 470
 471     /**
 472      * Update the trace attributes
 473      *
 474      * @param context the current trace context
 475      * @param rank
 476      * @param timestamp
 477      */
 478     protected synchronized void updateAttributes(final ITmfContext context, final ITmfTimestamp timestamp) {
 479         if (fStartTime.compareTo(timestamp, false) > 0) {
 480             fStartTime = timestamp;
 481         }
 482         if (fEndTime.compareTo(timestamp, false) < 0) {
 483             fEndTime = timestamp;
 484         }
 485         if (context.hasValidRank()) {
 486             long rank = context.getRank();
 487             if (fNbEvents <= rank) {
 488                 fNbEvents = rank + 1;
 489             }
 490             fIndexer.updateIndex(context, timestamp);
 491         }
 492     }
 493
 494     // ------------------------------------------------------------------------
 495     // TmfDataProvider
 496     // ------------------------------------------------------------------------
 497
 498     /* (non-Javadoc)
 499      * @see org.eclipse.linuxtools.tmf.core.component.TmfDataProvider#armRequest(org.eclipse.linuxtools.tmf.core.request.ITmfDataRequest)
 500      */
 501     @Override
 502     public ITmfContext armRequest(final ITmfDataRequest<T> request) {
 503         if (request instanceof ITmfEventRequest<?>
 504         && !TmfTimestamp.BIG_BANG.equals(((ITmfEventRequest<T>) request).getRange().getStartTime())
 505         && request.getIndex() == 0) {
 506             final ITmfContext context = seekEvent(((ITmfEventRequest<T>) request).getRange().getStartTime());
 507             ((ITmfEventRequest<T>) request).setStartIndex((int) context.getRank());
 508             return context;
 509
 510         }
 511         return seekEvent(request.getIndex());
 512     }
 513
 514     /* (non-Javadoc)
 515      * @see org.eclipse.linuxtools.tmf.core.component.TmfDataProvider#getNext(org.eclipse.linuxtools.tmf.core.trace.ITmfContext)
 516      */
 517     @Override
 518     @SuppressWarnings("unchecked")
 519     public T getNext(final ITmfContext context) {
 520         if (context instanceof TmfContext)
 521             return (T) readNextEvent(context);
 522         return null;
 523     }
 524
 525
 526     // ------------------------------------------------------------------------
 527     // toString
 528     // ------------------------------------------------------------------------
 529
 530     /* (non-Javadoc)
 531      * @see java.lang.Object#toString()
 532      */
 533     @Override
 534     @SuppressWarnings("nls")
 535     public synchronized String toString() {
 536         return "TmfTrace [fPath=" + fPath + ", fCacheSize=" + fCacheSize
 537                 + ", fNbEvents=" + fNbEvents + ", fStartTime=" + fStartTime
 538                 + ", fEndTime=" + fEndTime + ", fStreamingInterval=" + fStreamingInterval + "]";
 539     }
 540
 541 }