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.Collections;
  19 import java.util.Vector;
  20
  21 import org.eclipse.core.resources.IProject;
  22 import org.eclipse.core.resources.IResource;
  23 import org.eclipse.core.runtime.Path;
  24 import org.eclipse.linuxtools.tmf.core.component.TmfEventProvider;
  25 import org.eclipse.linuxtools.tmf.core.event.ITmfEvent;
  26 import org.eclipse.linuxtools.tmf.core.event.ITmfTimestamp;
  27 import org.eclipse.linuxtools.tmf.core.event.TmfTimeRange;
  28 import org.eclipse.linuxtools.tmf.core.event.TmfTimestamp;
  29 import org.eclipse.linuxtools.tmf.core.request.ITmfDataRequest;
  30 import org.eclipse.linuxtools.tmf.core.request.ITmfEventRequest;
  31
  32 /**
  33  * <b><u>TmfTrace</u></b>
  34  * <p>
  35  * Abstract implementation of ITmfTrace.
  36  * <p>
  37  * Document me...
  38  */
  39 public abstract class TmfTrace<T extends ITmfEvent> extends TmfEventProvider<T> implements ITmfTrace<T> {
  40
  41     // ------------------------------------------------------------------------
  42     // Constants
  43     // ------------------------------------------------------------------------
  44
  45     /**
  46      * The default trace cache size
  47      */
  48     public static final int DEFAULT_TRACE_CACHE_SIZE = 1000;
  49
  50     // ------------------------------------------------------------------------
  51     // Attributes
  52     // ------------------------------------------------------------------------
  53
  54     // The resource used for persistent properties for this trace
  55     private IResource fResource;
  56
  57     // The trace path
  58     private String fPath;
  59
  60     /**
  61      * The cache page size AND trace checkpoints interval
  62      */
  63     protected int fCacheSize = DEFAULT_TRACE_CACHE_SIZE;
  64
  65     // The set of event stream checkpoints
  66     protected Vector<TmfCheckpoint> fCheckpoints = new Vector<TmfCheckpoint>();
  67
  68     // The number of events collected
  69     protected long fNbEvents = 0;
  70
  71     // The time span of the event stream
  72     private ITmfTimestamp fStartTime = TmfTimestamp.BIG_CRUNCH;
  73     private ITmfTimestamp fEndTime = TmfTimestamp.BIG_BANG;
  74
  75     /**
  76      * The trace streaming interval (0 = no streaming)
  77      */
  78     protected long fStreamingInterval = 0;
  79
  80     /**
  81      * The trace indexer
  82      */
  83     protected ITmfTraceIndexer<ITmfTrace<ITmfEvent>> fIndexer;
  84
  85     // ------------------------------------------------------------------------
  86     // Construction
  87     // ------------------------------------------------------------------------
  88
  89     /**
  90      * The default, parameterless, constructor
  91      */
  92     @SuppressWarnings({ "unchecked", "rawtypes" })
  93     public TmfTrace() {
  94         super();
  95         fIndexer = new TmfTraceIndexer(this);
  96     }
  97
  98     /**
  99      * The standard constructor (non-streaming trace)
 100      *
 101      * @param resource the resource associated to the trace
 102      * @param type the trace event type
 103      * @param path the trace path
 104      * @param cacheSize the trace cache size
 105      * @throws FileNotFoundException
 106      */
 107     protected TmfTrace(final IResource resource, final Class<T> type, final String path, final int cacheSize) throws FileNotFoundException {
 108         this(resource, type, path, cacheSize, 0, null);
 109     }
 110
 111     /**
 112      * The standard constructor (streaming trace)
 113      *
 114      * @param resource the resource associated to the trace
 115      * @param type the trace event type
 116      * @param path the trace path
 117      * @param cacheSize the trace cache size
 118      * @param interval the trace streaming interval
 119      * @throws FileNotFoundException
 120      */
 121     protected TmfTrace(final IResource resource, final Class<T> type, final String path, final int cacheSize, final long interval) throws FileNotFoundException {
 122         this(resource, type, path, cacheSize, interval, null);
 123     }
 124
 125     /**
 126      * The full constructor
 127      *
 128      * @param resource the resource associated to the trace
 129      * @param type the trace event type
 130      * @param path the trace path
 131      * @param cacheSize the trace cache size
 132      * @param indexer the trace indexer
 133      * @throws FileNotFoundException
 134      */
 135     @SuppressWarnings({ "unchecked", "rawtypes" })
 136     protected TmfTrace(final IResource resource, final Class<T> type, final String path, final int cacheSize,
 137             final long interval, final ITmfTraceIndexer<?> indexer) throws FileNotFoundException {
 138         super();
 139         fCacheSize = (cacheSize > 0) ? cacheSize : DEFAULT_TRACE_CACHE_SIZE;
 140         fStreamingInterval = interval;
 141         fIndexer = (indexer != null) ? indexer : new TmfTraceIndexer(this);
 142         initialize(resource, path, type);
 143     }
 144
 145     /**
 146      * Copy constructor
 147      *
 148      * @param trace the original trace
 149      */
 150     @SuppressWarnings({ "unchecked", "rawtypes" })
 151     public TmfTrace(final TmfTrace<T> trace) throws FileNotFoundException {
 152         super();
 153         if (trace == null)
 154             throw new IllegalArgumentException();
 155         fCacheSize = trace.getCacheSize();
 156         fStreamingInterval = trace.getStreamingInterval();
 157         fIndexer = new TmfTraceIndexer(this);
 158         initialize(trace.getResource(), trace.getPath(), trace.getType());
 159     }
 160
 161     /**
 162      * @param resource
 163      * @param path
 164      * @param type
 165      * @throws FileNotFoundException
 166      */
 167     protected void initialize(final IResource resource, final String path, final Class<T> type) throws FileNotFoundException {
 168         fResource = resource;
 169         fPath = path;
 170         String traceName = (resource != null) ? resource.getName() : null;
 171         // If no display name was provided, extract it from the trace path
 172         if (traceName == null)
 173             if (path != null) {
 174                 final int sep = path.lastIndexOf(Path.SEPARATOR);
 175                 traceName = (sep >= 0) ? path.substring(sep + 1) : path;
 176             }
 177             else {
 178                 traceName = ""; //$NON-NLS-1$
 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;
 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 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         // Find the checkpoint at or before the requested timestamp.
 344         // In the very likely event that the timestamp is not at a checkpoint
 345         // boundary, bsearch will return index = (- (insertion point + 1)).
 346         // It is then trivial to compute the index of the previous checkpoint.
 347         int index = Collections.binarySearch(fCheckpoints, new TmfCheckpoint(timestamp, null));
 348         if (index < 0) {
 349             index = Math.max(0, -(index + 2));
 350         }
 351
 352         // Position the trace at the checkpoint
 353         final ITmfContext context = seekCheckpoint(index);
 354
 355         // And locate the requested event context
 356         final ITmfContext nextEventContext = context.clone(); // Must use clone() to get the right subtype...
 357         ITmfEvent event = getNextEvent(nextEventContext);
 358         while (event != null && event.getTimestamp().compareTo(timestamp, false) < 0) {
 359             context.setLocation(nextEventContext.getLocation().clone());
 360             context.increaseRank();
 361             event = getNextEvent(nextEventContext);
 362         }
 363         return context;
 364     }
 365
 366     /* (non-Javadoc)
 367      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#seekEvent(long)
 368      */
 369     @Override
 370     public ITmfContext seekEvent(final long rank) {
 371
 372         // A rank <= 0 indicates to seek the first event
 373         if (rank <= 0)
 374             return seekLocation(null);
 375
 376         // Find the checkpoint at or before the requested rank.
 377         final int index = (int) rank / fCacheSize;
 378         final ITmfContext context = seekCheckpoint(index);
 379
 380         // And locate the requested event context
 381         long pos = context.getRank();
 382         if (pos < rank) {
 383             ITmfEvent event = getNextEvent(context);
 384             while (event != null && ++pos < rank) {
 385                 event = getNextEvent(context);
 386             }
 387         }
 388         return context;
 389     }
 390
 391
 392     /**
 393      * Position the trace at the given checkpoint
 394      *
 395      * @param index the checkpoint index
 396      * @return the corresponding context
 397      */
 398     private ITmfContext seekCheckpoint(int index) {
 399         ITmfLocation<?> location;
 400         synchronized (fCheckpoints) {
 401             if (!fCheckpoints.isEmpty()) {
 402                 if (index >= fCheckpoints.size()) {
 403                     index = fCheckpoints.size() - 1;
 404                 }
 405                 location = fCheckpoints.elementAt(index).getLocation();
 406             } else {
 407                 location = null;
 408             }
 409         }
 410         final ITmfContext context = seekLocation(location);
 411         context.setRank(index * fCacheSize);
 412         return context;
 413     }
 414
 415     // ------------------------------------------------------------------------
 416     // ITmfTrace - Read operations (returning an actual event)
 417     // ------------------------------------------------------------------------
 418
 419     /* (non-Javadoc)
 420      * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getNextEvent(org.eclipse.linuxtools.tmf.core.trace.ITmfContext)
 421      */
 422     @Override
 423     public synchronized ITmfEvent getNextEvent(final ITmfContext context) {
 424         // parseEvent() does not update the context
 425         final ITmfEvent event = parseEvent(context);
 426         if (event != null) {
 427             updateIndex(context, context.getRank(), event.getTimestamp());
 428             context.setLocation(getCurrentLocation());
 429             context.increaseRank();
 430             processEvent(event);
 431         }
 432         return event;
 433     }
 434
 435     /**
 436      * Hook for special processing by the concrete class (called by
 437      * getNextEvent())
 438      *
 439      * @param event
 440      */
 441     protected void processEvent(final ITmfEvent event) {
 442         // Do nothing by default
 443     }
 444
 445     protected synchronized void updateIndex(final ITmfContext context, final long rank, final ITmfTimestamp timestamp) {
 446         if (fStartTime.compareTo(timestamp, false) > 0) {
 447             fStartTime = timestamp;
 448         }
 449         if (fEndTime.compareTo(timestamp, false) < 0) {
 450             fEndTime = timestamp;
 451         }
 452         if (context.hasValidRank()) {
 453             if (fNbEvents <= rank) {
 454                 fNbEvents = rank + 1;
 455             }
 456             // Build the index as we go along
 457             if ((rank % fCacheSize) == 0) {
 458                 // Determine the table position
 459                 final long position = rank / fCacheSize;
 460                 // Add new entry at proper location (if empty)
 461                 if (fCheckpoints.size() == position) {
 462                     final ITmfLocation<?> location = context.getLocation().clone();
 463                     fCheckpoints.add(new TmfCheckpoint(timestamp.clone(), location));
 464                     // System.out.println(getName() + "[" + (fCheckpoints.size() + "] " + timestamp + ", " + location.toString());
 465                 }
 466             }
 467         }
 468     }
 469
 470 //    // ------------------------------------------------------------------------
 471 //    // ITmfTrace - indexing
 472 //    // ------------------------------------------------------------------------
 473 //
 474 //    /*
 475 //     * The index is a list of contexts that point to events at regular interval
 476 //     * (rank-wise) in the trace. After it is built, the index can be used to
 477 //     * quickly access any event by rank or timestamp.
 478 //     *
 479 //     * fIndexPageSize holds the event interval (default INDEX_PAGE_SIZE).
 480 //     */
 481 //
 482 //    @SuppressWarnings({ "unchecked" })
 483 //    protected void indexTrace(final boolean waitForCompletion) {
 484 //
 485 //        // The monitoring job
 486 //        final Job job = new Job("Indexing " + getName() + "...") { //$NON-NLS-1$ //$NON-NLS-2$
 487 //
 488 //            @Override
 489 //            protected IStatus run(final IProgressMonitor monitor) {
 490 //                while (!monitor.isCanceled()) {
 491 //                    try {
 492 //                        Thread.sleep(100);
 493 //                    } catch (final InterruptedException e) {
 494 //                        return Status.OK_STATUS;
 495 //                    }
 496 //                }
 497 //                monitor.done();
 498 //                return Status.OK_STATUS;
 499 //            }
 500 //        };
 501 //        job.schedule();
 502 //
 503 //        // Clear the checkpoints
 504 //        fCheckpoints.clear();
 505 //
 506 //        // Build a background request for all the trace data. The index is
 507 //        // updated as we go by getNextEvent().
 508 //        final ITmfEventRequest<ITmfEvent> request = new TmfEventRequest<ITmfEvent>(ITmfEvent.class,
 509 //                TmfTimeRange.ETERNITY,
 510 //                TmfDataRequest.ALL_DATA, fCacheSize, ITmfDataRequest.ExecutionType.BACKGROUND)
 511 //                {
 512 //
 513 //            ITmfTimestamp startTime = null;
 514 //            ITmfTimestamp lastTime = null;
 515 //
 516 //            @Override
 517 //            public void handleData(final ITmfEvent event) {
 518 //                super.handleData(event);
 519 //                if (event != null) {
 520 //                    final ITmfTimestamp timestamp = event.getTimestamp();
 521 //                    if (startTime == null) {
 522 //                        startTime = timestamp.clone();
 523 //                    }
 524 //                    lastTime = timestamp.clone();
 525 //
 526 //                    // Update the trace status at regular intervals
 527 //                    if ((getNbRead() % fCacheSize) == 0) {
 528 //                        updateTraceStatus();
 529 //                    }
 530 //                }
 531 //            }
 532 //
 533 //            @Override
 534 //            public void handleSuccess() {
 535 //                updateTraceStatus();
 536 //            }
 537 //
 538 //            @Override
 539 //            public void handleCompleted() {
 540 //                job.cancel();
 541 //                super.handleCompleted();
 542 //            }
 543 //
 544 //            private synchronized void updateTraceStatus() {
 545 //                final int nbRead = getNbRead();
 546 //                if (nbRead != 0) {
 547 //                    fStartTime = startTime;
 548 //                    fEndTime = lastTime;
 549 //                    fNbEvents = nbRead;
 550 //                    notifyListeners();
 551 //                }
 552 //            }
 553 //                };
 554 //
 555 //                // Submit the request and wait for completion if required
 556 //                sendRequest((ITmfDataRequest<T>) request);
 557 //                if (waitForCompletion) {
 558 //                    try {
 559 //                        request.waitForCompletion();
 560 //                    } catch (final InterruptedException e) {
 561 //                    }
 562 //                }
 563 //    }
 564 //
 565 //    private void notifyListeners() {
 566 //        broadcast(new TmfTraceUpdatedSignal(this, this, new TmfTimeRange(fStartTime, fEndTime)));
 567 //    }
 568
 569     // ------------------------------------------------------------------------
 570     // TmfProvider
 571     // ------------------------------------------------------------------------
 572
 573     @Override
 574     public ITmfContext armRequest(final ITmfDataRequest<T> request) {
 575         if (request instanceof ITmfEventRequest<?>
 576         && !TmfTimestamp.BIG_BANG.equals(((ITmfEventRequest<T>) request).getRange().getStartTime())
 577         && request.getIndex() == 0) {
 578             final ITmfContext context = seekEvent(((ITmfEventRequest<T>) request).getRange().getStartTime());
 579             ((ITmfEventRequest<T>) request).setStartIndex((int) context.getRank());
 580             return context;
 581
 582         }
 583         return seekEvent(request.getIndex());
 584     }
 585
 586     /**
 587      * Return the next piece of data based on the context supplied. The context
 588      * would typically be updated for the subsequent read.
 589      *
 590      * @param context
 591      * @return the event referred to by context
 592      */
 593     @Override
 594     @SuppressWarnings("unchecked")
 595     public T getNext(final ITmfContext context) {
 596         if (context instanceof TmfContext)
 597             return (T) getNextEvent(context);
 598         return null;
 599     }
 600
 601
 602     // ------------------------------------------------------------------------
 603     // toString
 604     // ------------------------------------------------------------------------
 605
 606     @Override
 607     @SuppressWarnings("nls")
 608     public String toString() {
 609         return "TmfTrace [fPath=" + fPath + ", fCacheSize=" + fCacheSize
 610                 + ", fNbEvents=" + fNbEvents + ", fStartTime=" + fStartTime
 611                 + ", fEndTime=" + fEndTime + ", fStreamingInterval=" + fStreamingInterval + "]";
 612     }
 613
 614 }