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
.IPath
;
20 import org
.eclipse
.linuxtools
.tmf
.core
.component
.TmfEventProvider
;
21 import org
.eclipse
.linuxtools
.tmf
.core
.event
.ITmfEvent
;
22 import org
.eclipse
.linuxtools
.tmf
.core
.event
.ITmfTimestamp
;
23 import org
.eclipse
.linuxtools
.tmf
.core
.event
.TmfTimeRange
;
24 import org
.eclipse
.linuxtools
.tmf
.core
.event
.TmfTimestamp
;
25 import org
.eclipse
.linuxtools
.tmf
.core
.exceptions
.TmfTraceException
;
26 import org
.eclipse
.linuxtools
.tmf
.core
.request
.ITmfDataRequest
;
27 import org
.eclipse
.linuxtools
.tmf
.core
.request
.ITmfEventRequest
;
28 import org
.eclipse
.linuxtools
.tmf
.core
.statesystem
.ITmfStateSystem
;
29 import org
.eclipse
.linuxtools
.tmf
.core
.statistics
.ITmfStatistics
;
30 import org
.eclipse
.linuxtools
.tmf
.core
.statistics
.TmfStateStatistics
;
33 * Abstract implementation of ITmfTrace.
35 * Since the concept of 'location' is trace specific, the concrete classes have
36 * to provide the related methods, namely:
38 * <li> public ITmfLocation<?> getCurrentLocation()
39 * <li> public double getLocationRatio(ITmfLocation<?> location)
40 * <li> public ITmfContext seekEvent(ITmfLocation<?> location)
41 * <li> public ITmfContext seekEvent(double ratio)
42 * <li> public boolean validate(IProject project, String path)
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.
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.
53 * @author Francois Chouinard
56 * @see ITmfTraceIndexer
57 * @see ITmfEventParser
59 public abstract class TmfTrace
extends TmfEventProvider
implements ITmfTrace
{
61 // ------------------------------------------------------------------------
63 // ------------------------------------------------------------------------
65 // The resource used for persistent properties for this trace
66 private IResource fResource
;
71 // The trace cache page size
72 private int fCacheSize
= ITmfTrace
.DEFAULT_TRACE_CACHE_SIZE
;
74 // The number of events collected (so far)
75 private long fNbEvents
= 0;
77 // The time span of the event stream
78 private ITmfTimestamp fStartTime
= TmfTimestamp
.BIG_CRUNCH
;
79 private ITmfTimestamp fEndTime
= TmfTimestamp
.BIG_BANG
;
81 // The trace streaming interval (0 = no streaming)
82 private long fStreamingInterval
= 0;
85 private ITmfTraceIndexer fIndexer
;
88 private ITmfEventParser fParser
;
90 // The trace's statistics
91 private ITmfStatistics fStatistics
;
93 // ------------------------------------------------------------------------
95 // ------------------------------------------------------------------------
98 * The default, parameterless, constructor
105 * The standard constructor (non-live trace). Applicable when the trace
106 * implements its own parser and if at checkpoint-based index is OK.
108 * @param resource the resource associated to the trace
109 * @param type the trace event type
110 * @param path the trace path
111 * @param cacheSize the trace cache size
112 * @throws TmfTraceException If something failed during the opening
114 protected TmfTrace(final IResource resource
, final Class
<?
extends ITmfEvent
> type
, final String path
, final int cacheSize
) throws TmfTraceException
{
115 this(resource
, type
, path
, cacheSize
, 0);
119 * The standard constructor (live trace). Applicable when the trace
120 * implements its own parser and if at checkpoint-based index is OK.
122 * @param resource the resource associated to the trace
123 * @param type the trace event type
124 * @param path the trace path
125 * @param cacheSize the trace cache size
126 * @param interval the trace streaming interval
127 * @throws TmfTraceException If something failed during the opening
129 protected TmfTrace(final IResource resource
, final Class
<?
extends ITmfEvent
> type
, final String path
, final int cacheSize
, final long interval
) throws TmfTraceException
{
130 this(resource
, type
, path
, cacheSize
, interval
, null);
134 * The 'non-default indexer' constructor. Allows to provide a trace
137 * @param resource the resource associated to the trace
138 * @param type the trace event type
139 * @param path the trace path
140 * @param cacheSize the trace cache size
141 * @param interval the trace streaming interval
142 * @param indexer the trace indexer
143 * @throws TmfTraceException If something failed during the opening
145 protected TmfTrace(final IResource resource
, final Class
<?
extends ITmfEvent
> type
, final String path
, final int cacheSize
,
146 final long interval
, final ITmfTraceIndexer indexer
) throws TmfTraceException
{
147 this(resource
, type
, path
, cacheSize
, interval
, indexer
, null);
151 * The full constructor where trace specific indexer/parser are provided.
153 * @param resource the resource associated to the trace
154 * @param type the trace event type
155 * @param path the trace path
156 * @param cacheSize the trace cache size
157 * @param interval the trace streaming interval
158 * @param indexer the trace indexer
159 * @param parser the trace event parser
160 * @throws TmfTraceException If something failed during the opening
162 protected TmfTrace(final IResource resource
, final Class
<?
extends ITmfEvent
> type
, final String path
, final int cacheSize
,
163 final long interval
, final ITmfTraceIndexer indexer
, final ITmfEventParser parser
) throws TmfTraceException
{
165 fCacheSize
= (cacheSize
> 0) ? cacheSize
: ITmfTrace
.DEFAULT_TRACE_CACHE_SIZE
;
166 fStreamingInterval
= interval
;
167 fIndexer
= (indexer
!= null) ? indexer
: new TmfCheckpointIndexer(this, fCacheSize
);
169 initialize(resource
, path
, type
);
175 * @param trace the original trace
176 * @throws TmfTraceException Should not happen usually
178 public TmfTrace(final TmfTrace trace
) throws TmfTraceException
{
181 throw new IllegalArgumentException();
183 fCacheSize
= trace
.getCacheSize();
184 fStreamingInterval
= trace
.getStreamingInterval();
185 fIndexer
= new TmfCheckpointIndexer(this);
186 fParser
= trace
.fParser
;
187 initialize(trace
.getResource(), trace
.getPath(), trace
.getEventType());
190 // ------------------------------------------------------------------------
191 // ITmfTrace - Initializers
192 // ------------------------------------------------------------------------
195 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#initTrace(org.eclipse.core.resources.IResource, java.lang.String, java.lang.Class)
198 public void initTrace(final IResource resource
, final String path
, final Class
<?
extends ITmfEvent
> type
) throws TmfTraceException
{
199 fIndexer
= new TmfCheckpointIndexer(this, fCacheSize
);
200 initialize(resource
, path
, type
);
204 * Initialize the trace common attributes and the base component.
206 * @param resource the Eclipse resource (trace)
207 * @param path the trace path
208 * @param type the trace event type
210 * @throws TmfTraceException If something failed during the initialization
212 protected void initialize(final IResource resource
, final String path
, final Class
<?
extends ITmfEvent
> type
) throws TmfTraceException
{
214 throw new TmfTraceException("Invalid trace path"); //$NON-NLS-1$
217 fResource
= resource
;
218 String traceName
= (resource
!= null) ? resource
.getName() : null;
219 // If no resource was provided, extract the display name the trace path
220 if (traceName
== null) {
221 final int sep
= path
.lastIndexOf(IPath
.SEPARATOR
);
222 traceName
= (sep
>= 0) ? path
.substring(sep
+ 1) : path
;
224 if (fParser
== null) {
225 if (this instanceof ITmfEventParser
) {
226 fParser
= (ITmfEventParser
) this;
228 throw new TmfTraceException("Invalid trace parser"); //$NON-NLS-1$
231 super.init(traceName
, type
);
237 * Indicates if the path points to an existing file/directory
239 * @param path the path to test
240 * @return true if the file/directory exists
242 protected boolean fileExists(final String path
) {
243 final File file
= new File(path
);
244 return file
.exists();
250 * @param waitForCompletion index synchronously (true) or not (false)
252 protected void indexTrace(boolean waitForCompletion
) {
253 getIndexer().buildIndex(0, TmfTimeRange
.ETERNITY
, waitForCompletion
);
257 * The default implementation of TmfTrace uses a TmfStatistics back-end.
258 * Override this if you want to specify another type (or none at all).
260 * @throws TmfTraceException
261 * If there was a problem setting up the statistics
264 protected void buildStatistics() throws TmfTraceException
{
266 * Initialize the statistics provider, but only if a Resource has been
267 * set (so we don't build it for experiments, for unit tests, etc.)
269 fStatistics
= (fResource
== null ?
null : new TmfStateStatistics(this) );
276 public synchronized void dispose() {
277 /* Clean up the index if applicable */
278 if (getIndexer() != null) {
279 getIndexer().dispose();
282 /* Clean up the statistics */
283 if (fStatistics
!= null) {
284 fStatistics
.dispose();
289 // ------------------------------------------------------------------------
290 // ITmfTrace - Basic getters
291 // ------------------------------------------------------------------------
294 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getEventType()
297 public Class
<ITmfEvent
> getEventType() {
298 return (Class
<ITmfEvent
>) super.getType();
302 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getResource()
305 public IResource
getResource() {
310 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getPath()
313 public String
getPath() {
318 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getIndexPageSize()
321 public int getCacheSize() {
326 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getStreamingInterval()
329 public long getStreamingInterval() {
330 return fStreamingInterval
;
334 * @return the trace indexer
336 protected ITmfTraceIndexer
getIndexer() {
341 * @return the trace parser
343 protected ITmfEventParser
getParser() {
351 public ITmfStatistics
getStatistics() {
359 public ITmfStateSystem
getStateSystem() {
361 * By default, no state system is used. Sub-classes can specify their
367 // ------------------------------------------------------------------------
368 // ITmfTrace - Trace characteristics getters
369 // ------------------------------------------------------------------------
372 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getNbEvents()
375 public synchronized long getNbEvents() {
380 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getTimeRange()
383 public TmfTimeRange
getTimeRange() {
384 return new TmfTimeRange(fStartTime
, fEndTime
);
388 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getStartTime()
391 public ITmfTimestamp
getStartTime() {
396 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getEndTime()
399 public ITmfTimestamp
getEndTime() {
403 // ------------------------------------------------------------------------
404 // Convenience setters/getters
405 // ------------------------------------------------------------------------
408 * Set the trace cache size. Must be done at initialization time.
410 * @param cacheSize The trace cache size
412 protected void setCacheSize(final int cacheSize
) {
413 fCacheSize
= cacheSize
;
417 * Set the trace known number of events. This can be quite dynamic
418 * during indexing or for live traces.
420 * @param nbEvents The number of events
422 protected synchronized void setNbEvents(final long nbEvents
) {
423 fNbEvents
= (nbEvents
> 0) ? nbEvents
: 0;
427 * Update the trace events time range
429 * @param range the new time range
431 protected void setTimeRange(final TmfTimeRange range
) {
432 fStartTime
= range
.getStartTime();
433 fEndTime
= range
.getEndTime();
437 * Update the trace chronologically first event timestamp
439 * @param startTime the new first event timestamp
441 protected void setStartTime(final ITmfTimestamp startTime
) {
442 fStartTime
= startTime
;
446 * Update the trace chronologically last event timestamp
448 * @param endTime the new last event timestamp
450 protected void setEndTime(final ITmfTimestamp endTime
) {
455 * Set the polling interval for live traces (default = 0 = no streaming).
457 * @param interval the new trace streaming interval
459 protected void setStreamingInterval(final long interval
) {
460 fStreamingInterval
= (interval
> 0) ? interval
: 0;
464 * Set the trace indexer. Must be done at initialization time.
466 * @param indexer the trace indexer
468 protected void setIndexer(final ITmfTraceIndexer indexer
) {
473 * Set the trace parser. Must be done at initialization time.
475 * @param parser the new trace parser
477 protected void setParser(final ITmfEventParser parser
) {
481 // ------------------------------------------------------------------------
482 // ITmfTrace - SeekEvent operations (returning a trace context)
483 // ------------------------------------------------------------------------
486 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#seekEvent(long)
489 public synchronized ITmfContext
seekEvent(final long rank
) {
491 // A rank <= 0 indicates to seek the first event
493 ITmfContext context
= seekEvent((ITmfLocation
) null);
498 // Position the trace at the checkpoint
499 final ITmfContext context
= fIndexer
.seekIndex(rank
);
501 // And locate the requested event context
502 long pos
= context
.getRank();
504 ITmfEvent event
= getNext(context
);
505 while ((event
!= null) && (++pos
< rank
)) {
506 event
= getNext(context
);
513 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#seekEvent(org.eclipse.linuxtools.tmf.core.event.ITmfTimestamp)
516 public synchronized ITmfContext
seekEvent(final ITmfTimestamp timestamp
) {
518 // A null timestamp indicates to seek the first event
519 if (timestamp
== null) {
520 ITmfContext context
= seekEvent((ITmfLocation
) null);
525 // Position the trace at the checkpoint
526 ITmfContext context
= fIndexer
.seekIndex(timestamp
);
528 // And locate the requested event context
529 final ITmfContext nextEventContext
= context
.clone(); // Must use clone() to get the right subtype...
530 ITmfEvent event
= getNext(nextEventContext
);
531 while (event
!= null && event
.getTimestamp().compareTo(timestamp
, false) < 0) {
533 context
= nextEventContext
.clone();
534 event
= getNext(nextEventContext
);
536 nextEventContext
.dispose();
538 context
.setLocation(null);
539 context
.setRank(ITmfContext
.UNKNOWN_RANK
);
544 // ------------------------------------------------------------------------
545 // ITmfTrace - Read operations (returning an actual event)
546 // ------------------------------------------------------------------------
549 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#readNextEvent(org.eclipse.linuxtools.tmf.core.trace.ITmfContext)
552 public synchronized ITmfEvent
getNext(final ITmfContext context
) {
553 // parseEvent() does not update the context
554 final ITmfEvent event
= fParser
.parseEvent(context
);
556 updateAttributes(context
, event
.getTimestamp());
557 context
.setLocation(getCurrentLocation());
558 context
.increaseRank();
565 * Hook for special event processing by the concrete class
566 * (called by TmfTrace.getEvent())
568 * @param event the event
570 protected void processEvent(final ITmfEvent event
) {
575 * Update the trace attributes
577 * @param context the current trace context
578 * @param timestamp the corresponding timestamp
580 protected synchronized void updateAttributes(final ITmfContext context
, final ITmfTimestamp timestamp
) {
581 if (fStartTime
.equals(TmfTimestamp
.BIG_BANG
) || (fStartTime
.compareTo(timestamp
, false) > 0)) {
582 fStartTime
= timestamp
;
584 if (fEndTime
.equals(TmfTimestamp
.BIG_CRUNCH
) || (fEndTime
.compareTo(timestamp
, false) < 0)) {
585 fEndTime
= timestamp
;
587 if (context
.hasValidRank()) {
588 long rank
= context
.getRank();
589 if (fNbEvents
<= rank
) {
590 fNbEvents
= rank
+ 1;
592 if (fIndexer
!= null) {
593 fIndexer
.updateIndex(context
, timestamp
);
598 // ------------------------------------------------------------------------
600 // ------------------------------------------------------------------------
603 * @see org.eclipse.linuxtools.tmf.core.component.TmfDataProvider#armRequest(org.eclipse.linuxtools.tmf.core.request.ITmfDataRequest)
606 protected ITmfContext
armRequest(final ITmfDataRequest request
) {
607 if ((request
instanceof ITmfEventRequest
)
608 && !TmfTimestamp
.BIG_BANG
.equals(((ITmfEventRequest
) request
).getRange().getStartTime())
609 && (request
.getIndex() == 0))
611 final ITmfContext context
= seekEvent(((ITmfEventRequest
) request
).getRange().getStartTime());
612 ((ITmfEventRequest
) request
).setStartIndex((int) context
.getRank());
616 return seekEvent(request
.getIndex());
619 // ------------------------------------------------------------------------
621 // ------------------------------------------------------------------------
624 * @see java.lang.Object#toString()
627 @SuppressWarnings("nls")
628 public synchronized String
toString() {
629 return "TmfTrace [fPath=" + fPath
+ ", fCacheSize=" + fCacheSize
630 + ", fNbEvents=" + fNbEvents
+ ", fStartTime=" + fStartTime
631 + ", fEndTime=" + fEndTime
+ ", fStreamingInterval=" + fStreamingInterval
+ "]";