1 /*******************************************************************************
2 * Copyright (c) 2009, 2010, 2012 Ericsson
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
10 * Francois Chouinard - Initial API and implementation
11 * Francois Chouinard - Updated as per TMF Trace Model 1.0
12 *******************************************************************************/
14 package org
.eclipse
.linuxtools
.tmf
.core
.trace
;
18 import org
.eclipse
.core
.resources
.IResource
;
19 import org
.eclipse
.core
.runtime
.CoreException
;
20 import org
.eclipse
.core
.runtime
.IPath
;
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 import org
.eclipse
.linuxtools
.tmf
.core
.signal
.TmfRangeSynchSignal
;
30 import org
.eclipse
.linuxtools
.tmf
.core
.signal
.TmfSignalHandler
;
31 import org
.eclipse
.linuxtools
.tmf
.core
.signal
.TmfTimeSynchSignal
;
32 import org
.eclipse
.linuxtools
.tmf
.core
.signal
.TmfTraceOpenedSignal
;
33 import org
.eclipse
.linuxtools
.tmf
.core
.signal
.TmfTraceRangeUpdatedSignal
;
34 import org
.eclipse
.linuxtools
.tmf
.core
.statesystem
.ITmfStateSystem
;
35 import org
.eclipse
.linuxtools
.tmf
.core
.statistics
.ITmfStatistics
;
36 import org
.eclipse
.linuxtools
.tmf
.core
.statistics
.TmfStateStatistics
;
39 * Abstract implementation of ITmfTrace.
41 * Since the concept of 'location' is trace specific, the concrete classes have
42 * to provide the related methods, namely:
44 * <li> public ITmfLocation<?> getCurrentLocation()
45 * <li> public double getLocationRatio(ITmfLocation<?> location)
46 * <li> public ITmfContext seekEvent(ITmfLocation<?> location)
47 * <li> public ITmfContext seekEvent(double ratio)
48 * <li> public boolean validate(IProject project, String path)
50 * A concrete trace must provide its corresponding parser. A common way to
51 * accomplish this is by making the concrete class extend TmfTrace and
52 * implement ITmfEventParser.
54 * The concrete class can either specify its own indexer or use the provided
55 * TmfCheckpointIndexer (default). In this case, the trace cache size will be
56 * used as checkpoint interval.
59 * @author Francois Chouinard
62 * @see ITmfTraceIndexer
63 * @see ITmfEventParser
65 public abstract class TmfTrace
extends TmfEventProvider
implements ITmfTrace
{
67 // ------------------------------------------------------------------------
69 // ------------------------------------------------------------------------
71 // The resource used for persistent properties for this trace
72 private IResource fResource
;
77 // The trace cache page size
78 private int fCacheSize
= ITmfTrace
.DEFAULT_TRACE_CACHE_SIZE
;
80 // The number of events collected (so far)
81 private long fNbEvents
= 0;
83 // The time span of the event stream
84 private ITmfTimestamp fStartTime
= TmfTimestamp
.BIG_BANG
;
85 private ITmfTimestamp fEndTime
= TmfTimestamp
.BIG_BANG
;
87 // The trace streaming interval (0 = no streaming)
88 private long fStreamingInterval
= 0;
91 private ITmfTraceIndexer fIndexer
;
94 private ITmfEventParser fParser
;
96 // The trace's statistics
97 private ITmfStatistics fStatistics
;
99 // The current selected time
100 private ITmfTimestamp fCurrentTime
= TmfTimestamp
.ZERO
;
102 // The current selected range
103 private TmfTimeRange fCurrentRange
= TmfTimeRange
.NULL_RANGE
;
105 // ------------------------------------------------------------------------
107 // ------------------------------------------------------------------------
110 * The default, parameterless, constructor
117 * The standard constructor (non-live trace). Applicable when the trace
118 * implements its own parser and if at checkpoint-based index is OK.
120 * @param resource the resource associated to the trace
121 * @param type the trace event type
122 * @param path the trace path
123 * @param cacheSize the trace cache size
124 * @throws TmfTraceException If something failed during the opening
126 protected TmfTrace(final IResource resource
, final Class
<?
extends ITmfEvent
> type
, final String path
, final int cacheSize
) throws TmfTraceException
{
127 this(resource
, type
, path
, cacheSize
, 0);
131 * The standard constructor (live trace). Applicable when the trace
132 * implements its own parser and if at checkpoint-based index is OK.
134 * @param resource the resource associated to the trace
135 * @param type the trace event type
136 * @param path the trace path
137 * @param cacheSize the trace cache size
138 * @param interval the trace streaming interval
139 * @throws TmfTraceException If something failed during the opening
141 protected TmfTrace(final IResource resource
, final Class
<?
extends ITmfEvent
> type
, final String path
, final int cacheSize
, final long interval
) throws TmfTraceException
{
142 this(resource
, type
, path
, cacheSize
, interval
, null);
146 * The 'non-default indexer' constructor. Allows to provide a trace
149 * @param resource the resource associated to the trace
150 * @param type the trace event type
151 * @param path the trace path
152 * @param cacheSize the trace cache size
153 * @param interval the trace streaming interval
154 * @param indexer the trace indexer
155 * @throws TmfTraceException If something failed during the opening
157 protected TmfTrace(final IResource resource
, final Class
<?
extends ITmfEvent
> type
, final String path
, final int cacheSize
,
158 final long interval
, final ITmfTraceIndexer indexer
) throws TmfTraceException
{
159 this(resource
, type
, path
, cacheSize
, interval
, indexer
, null);
163 * The full constructor where trace specific indexer/parser are provided.
165 * @param resource the resource associated to the trace
166 * @param type the trace event type
167 * @param path the trace path
168 * @param cacheSize the trace cache size
169 * @param interval the trace streaming interval
170 * @param indexer the trace indexer
171 * @param parser the trace event parser
172 * @throws TmfTraceException If something failed during the opening
174 protected TmfTrace(final IResource resource
, final Class
<?
extends ITmfEvent
> type
, final String path
, final int cacheSize
,
175 final long interval
, final ITmfTraceIndexer indexer
, final ITmfEventParser parser
) throws TmfTraceException
{
177 fCacheSize
= (cacheSize
> 0) ? cacheSize
: ITmfTrace
.DEFAULT_TRACE_CACHE_SIZE
;
178 fStreamingInterval
= interval
;
179 fIndexer
= (indexer
!= null) ? indexer
: new TmfCheckpointIndexer(this, fCacheSize
);
181 initialize(resource
, path
, type
);
187 * @param trace the original trace
188 * @throws TmfTraceException Should not happen usually
190 public TmfTrace(final TmfTrace trace
) throws TmfTraceException
{
193 throw new IllegalArgumentException();
195 fCacheSize
= trace
.getCacheSize();
196 fStreamingInterval
= trace
.getStreamingInterval();
197 fIndexer
= new TmfCheckpointIndexer(this);
198 fParser
= trace
.fParser
;
199 initialize(trace
.getResource(), trace
.getPath(), trace
.getEventType());
202 // ------------------------------------------------------------------------
203 // ITmfTrace - Initializers
204 // ------------------------------------------------------------------------
207 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#initTrace(org.eclipse.core.resources.IResource, java.lang.String, java.lang.Class)
210 public void initTrace(final IResource resource
, final String path
, final Class
<?
extends ITmfEvent
> type
) throws TmfTraceException
{
211 fIndexer
= new TmfCheckpointIndexer(this, fCacheSize
);
212 initialize(resource
, path
, type
);
216 * Initialize the trace common attributes and the base component.
218 * @param resource the Eclipse resource (trace)
219 * @param path the trace path
220 * @param type the trace event type
222 * @throws TmfTraceException If something failed during the initialization
224 protected void initialize(final IResource resource
, final String path
, final Class
<?
extends ITmfEvent
> type
) throws TmfTraceException
{
226 throw new TmfTraceException("Invalid trace path"); //$NON-NLS-1$
229 fResource
= resource
;
230 String traceName
= (resource
!= null) ? resource
.getName() : null;
231 // If no resource was provided, extract the display name the trace path
232 if (traceName
== null) {
233 final int sep
= path
.lastIndexOf(IPath
.SEPARATOR
);
234 traceName
= (sep
>= 0) ? path
.substring(sep
+ 1) : path
;
236 if (fParser
== null) {
237 if (this instanceof ITmfEventParser
) {
238 fParser
= (ITmfEventParser
) this;
240 throw new TmfTraceException("Invalid trace parser"); //$NON-NLS-1$
243 super.init(traceName
, type
);
247 * Indicates if the path points to an existing file/directory
249 * @param path the path to test
250 * @return true if the file/directory exists
252 protected boolean fileExists(final String path
) {
253 final File file
= new File(path
);
254 return file
.exists();
260 * @param waitForCompletion index synchronously (true) or not (false)
262 protected void indexTrace(boolean waitForCompletion
) {
263 getIndexer().buildIndex(0, TmfTimeRange
.ETERNITY
, waitForCompletion
);
267 * The default implementation of TmfTrace uses a TmfStatistics back-end.
268 * Override this if you want to specify another type (or none at all).
270 * @throws TmfTraceException
271 * If there was a problem setting up the statistics
274 protected void buildStatistics() throws TmfTraceException
{
276 * Initialize the statistics provider, but only if a Resource has been
277 * set (so we don't build it for experiments, for unit tests, etc.)
279 fStatistics
= (fResource
== null ?
null : new TmfStateStatistics(this) );
283 * Build the state system(s) associated with this trace type.
285 * Suppressing the warning, because the 'throws' will usually happen in
288 * @throws TmfTraceException
289 * If there is a problem during the build
292 @SuppressWarnings("unused")
293 protected void buildStateSystem() throws TmfTraceException
{
295 * Nothing is done in the base implementation, please specify
296 * how/if to build a state system in derived classes.
305 public synchronized void dispose() {
306 /* Clean up the index if applicable */
307 if (getIndexer() != null) {
308 getIndexer().dispose();
311 /* Clean up the statistics */
312 if (fStatistics
!= null) {
313 fStatistics
.dispose();
318 // ------------------------------------------------------------------------
319 // ITmfTrace - Basic getters
320 // ------------------------------------------------------------------------
323 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getEventType()
326 public Class
<ITmfEvent
> getEventType() {
327 return (Class
<ITmfEvent
>) super.getType();
331 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getResource()
334 public IResource
getResource() {
339 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getPath()
342 public String
getPath() {
347 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getIndexPageSize()
350 public int getCacheSize() {
355 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getStreamingInterval()
358 public long getStreamingInterval() {
359 return fStreamingInterval
;
363 * @return the trace indexer
365 protected ITmfTraceIndexer
getIndexer() {
370 * @return the trace parser
372 protected ITmfEventParser
getParser() {
380 public ITmfStatistics
getStatistics() {
388 public ITmfStateSystem
getStateSystem() {
390 * By default, no state system is used. Sub-classes can specify their
396 // ------------------------------------------------------------------------
397 // ITmfTrace - Trace characteristics getters
398 // ------------------------------------------------------------------------
401 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getNbEvents()
404 public synchronized long getNbEvents() {
409 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getTimeRange()
412 public TmfTimeRange
getTimeRange() {
413 return new TmfTimeRange(fStartTime
, fEndTime
);
417 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getStartTime()
420 public ITmfTimestamp
getStartTime() {
425 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getEndTime()
428 public ITmfTimestamp
getEndTime() {
433 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getCurrentTime()
439 public ITmfTimestamp
getCurrentTime() {
444 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getCurrentRange()
450 public TmfTimeRange
getCurrentRange() {
451 return fCurrentRange
;
456 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getInitialRangeOffset()
462 public ITmfTimestamp
getInitialRangeOffset() {
463 final long DEFAULT_INITIAL_OFFSET_VALUE
= (1L * 100 * 1000 * 1000); // .1sec
464 return new TmfTimestamp(DEFAULT_INITIAL_OFFSET_VALUE
, ITmfTimestamp
.NANOSECOND_SCALE
);
467 // ------------------------------------------------------------------------
468 // Convenience setters
469 // ------------------------------------------------------------------------
472 * Set the trace cache size. Must be done at initialization time.
474 * @param cacheSize The trace cache size
476 protected void setCacheSize(final int cacheSize
) {
477 fCacheSize
= cacheSize
;
481 * Set the trace known number of events. This can be quite dynamic
482 * during indexing or for live traces.
484 * @param nbEvents The number of events
486 protected synchronized void setNbEvents(final long nbEvents
) {
487 fNbEvents
= (nbEvents
> 0) ? nbEvents
: 0;
491 * Update the trace events time range
493 * @param range the new time range
495 protected void setTimeRange(final TmfTimeRange range
) {
496 fStartTime
= range
.getStartTime();
497 fEndTime
= range
.getEndTime();
501 * Update the trace chronologically first event timestamp
503 * @param startTime the new first event timestamp
505 protected void setStartTime(final ITmfTimestamp startTime
) {
506 fStartTime
= startTime
;
510 * Update the trace chronologically last event timestamp
512 * @param endTime the new last event timestamp
514 protected void setEndTime(final ITmfTimestamp endTime
) {
519 * Set the polling interval for live traces (default = 0 = no streaming).
521 * @param interval the new trace streaming interval
523 protected void setStreamingInterval(final long interval
) {
524 fStreamingInterval
= (interval
> 0) ? interval
: 0;
528 * Set the trace indexer. Must be done at initialization time.
530 * @param indexer the trace indexer
532 protected void setIndexer(final ITmfTraceIndexer indexer
) {
537 * Set the trace parser. Must be done at initialization time.
539 * @param parser the new trace parser
541 protected void setParser(final ITmfEventParser parser
) {
545 // ------------------------------------------------------------------------
546 // ITmfTrace - SeekEvent operations (returning a trace context)
547 // ------------------------------------------------------------------------
550 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#seekEvent(long)
553 public synchronized ITmfContext
seekEvent(final long rank
) {
555 // A rank <= 0 indicates to seek the first event
557 ITmfContext context
= seekEvent((ITmfLocation
) null);
562 // Position the trace at the checkpoint
563 final ITmfContext context
= fIndexer
.seekIndex(rank
);
565 // And locate the requested event context
566 long pos
= context
.getRank();
568 ITmfEvent event
= getNext(context
);
569 while ((event
!= null) && (++pos
< rank
)) {
570 event
= getNext(context
);
577 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#seekEvent(org.eclipse.linuxtools.tmf.core.event.ITmfTimestamp)
580 public synchronized ITmfContext
seekEvent(final ITmfTimestamp timestamp
) {
582 // A null timestamp indicates to seek the first event
583 if (timestamp
== null) {
584 ITmfContext context
= seekEvent((ITmfLocation
) null);
589 // Position the trace at the checkpoint
590 ITmfContext context
= fIndexer
.seekIndex(timestamp
);
592 // And locate the requested event context
593 final ITmfContext nextEventContext
= context
.clone(); // Must use clone() to get the right subtype...
594 ITmfEvent event
= getNext(nextEventContext
);
595 while (event
!= null && event
.getTimestamp().compareTo(timestamp
, false) < 0) {
597 context
= nextEventContext
.clone();
598 event
= getNext(nextEventContext
);
600 nextEventContext
.dispose();
602 context
.setLocation(null);
603 context
.setRank(ITmfContext
.UNKNOWN_RANK
);
608 // ------------------------------------------------------------------------
609 // ITmfTrace - Read operations (returning an actual event)
610 // ------------------------------------------------------------------------
613 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#readNextEvent(org.eclipse.linuxtools.tmf.core.trace.ITmfContext)
616 public synchronized ITmfEvent
getNext(final ITmfContext context
) {
617 // parseEvent() does not update the context
618 final ITmfEvent event
= fParser
.parseEvent(context
);
620 updateAttributes(context
, event
.getTimestamp());
621 context
.setLocation(getCurrentLocation());
622 context
.increaseRank();
629 * Hook for special event processing by the concrete class
630 * (called by TmfTrace.getEvent())
632 * @param event the event
634 protected void processEvent(final ITmfEvent event
) {
639 * Update the trace attributes
641 * @param context the current trace context
642 * @param timestamp the corresponding timestamp
644 protected synchronized void updateAttributes(final ITmfContext context
, final ITmfTimestamp timestamp
) {
645 if (fStartTime
.equals(TmfTimestamp
.BIG_BANG
) || (fStartTime
.compareTo(timestamp
, false) > 0)) {
646 fStartTime
= timestamp
;
648 if (fEndTime
.equals(TmfTimestamp
.BIG_CRUNCH
) || (fEndTime
.compareTo(timestamp
, false) < 0)) {
649 fEndTime
= timestamp
;
651 if (fCurrentRange
== TmfTimeRange
.NULL_RANGE
) {
652 fCurrentTime
= timestamp
;
653 ITmfTimestamp initialOffset
= getInitialRangeOffset();
654 long endValue
= timestamp
.getValue() + initialOffset
.normalize(0, timestamp
.getScale()).getValue();
655 ITmfTimestamp endTimestamp
= new TmfTimestamp(endValue
, timestamp
.getScale());
656 fCurrentRange
= new TmfTimeRange(timestamp
, endTimestamp
);
658 if (context
.hasValidRank()) {
659 long rank
= context
.getRank();
660 if (fNbEvents
<= rank
) {
661 fNbEvents
= rank
+ 1;
663 if (fIndexer
!= null) {
664 fIndexer
.updateIndex(context
, timestamp
);
669 // ------------------------------------------------------------------------
671 // ------------------------------------------------------------------------
674 * @see org.eclipse.linuxtools.tmf.core.component.TmfDataProvider#armRequest(org.eclipse.linuxtools.tmf.core.request.ITmfDataRequest)
677 protected synchronized ITmfContext
armRequest(final ITmfDataRequest request
) {
678 if (executorIsShutdown()) {
681 if ((request
instanceof ITmfEventRequest
)
682 && !TmfTimestamp
.BIG_BANG
.equals(((ITmfEventRequest
) request
).getRange().getStartTime())
683 && (request
.getIndex() == 0))
685 final ITmfContext context
= seekEvent(((ITmfEventRequest
) request
).getRange().getStartTime());
686 ((ITmfEventRequest
) request
).setStartIndex((int) context
.getRank());
690 return seekEvent(request
.getIndex());
693 // ------------------------------------------------------------------------
695 // ------------------------------------------------------------------------
698 * Handler for the Trace Opened signal
701 * The incoming signal
705 public void traceOpened(TmfTraceOpenedSignal signal
) {
706 ITmfTrace trace
= signal
.getTrace();
707 if (signal
.getTrace() instanceof TmfExperiment
) {
708 TmfExperiment experiment
= (TmfExperiment
) signal
.getTrace();
709 for (ITmfTrace expTrace
: experiment
.getTraces()) {
710 if (expTrace
== this) {
717 /* the signal is for this trace or for an experiment containing this trace */
720 } catch (TmfTraceException e
) {
725 } catch (TmfTraceException e
) {
729 /* Refresh the project, so it can pick up new files that got created. */
731 if (fResource
!= null) {
732 fResource
.getProject().refreshLocal(IResource
.DEPTH_INFINITE
, null);
734 } catch (CoreException e
) {
738 if (signal
.getTrace() == this) {
739 /* the signal is for this trace or experiment */
740 if (getNbEvents() == 0) {
744 final TmfTimeRange timeRange
= new TmfTimeRange(getStartTime(), TmfTimestamp
.BIG_CRUNCH
);
745 final TmfTraceRangeUpdatedSignal rangeUpdatedsignal
= new TmfTraceRangeUpdatedSignal(this, this, timeRange
);
747 // Broadcast in separate thread to prevent deadlock
751 broadcast(rangeUpdatedsignal
);
759 * Signal handler for the TmfTraceRangeUpdatedSignal signal
761 * @param signal The incoming signal
765 public void traceRangeUpdated(final TmfTraceRangeUpdatedSignal signal
) {
766 if (signal
.getTrace() == this) {
767 getIndexer().buildIndex(getNbEvents(), signal
.getRange(), false);
772 * Signal handler for the TmfTimeSynchSignal signal
774 * @param signal The incoming signal
778 public void synchToTime(final TmfTimeSynchSignal signal
) {
779 if (signal
.getCurrentTime().compareTo(fStartTime
) >= 0 && signal
.getCurrentTime().compareTo(fEndTime
) <= 0) {
780 fCurrentTime
= signal
.getCurrentTime();
785 * Signal handler for the TmfRangeSynchSignal signal
787 * @param signal The incoming signal
791 public void synchToRange(final TmfRangeSynchSignal signal
) {
792 if (signal
.getCurrentTime().compareTo(fStartTime
) >= 0 && signal
.getCurrentTime().compareTo(fEndTime
) <= 0) {
793 fCurrentTime
= signal
.getCurrentTime();
795 if (signal
.getCurrentRange().getIntersection(getTimeRange()) != null) {
796 fCurrentRange
= signal
.getCurrentRange().getIntersection(getTimeRange());
800 // ------------------------------------------------------------------------
802 // ------------------------------------------------------------------------
805 * @see java.lang.Object#toString()
808 @SuppressWarnings("nls")
809 public synchronized String
toString() {
810 return "TmfTrace [fPath=" + fPath
+ ", fCacheSize=" + fCacheSize
811 + ", fNbEvents=" + fNbEvents
+ ", fStartTime=" + fStartTime
812 + ", fEndTime=" + fEndTime
+ ", fStreamingInterval=" + fStreamingInterval
+ "]";