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