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