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