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
;
17 import java
.io
.FileNotFoundException
;
19 import org
.eclipse
.core
.resources
.IResource
;
20 import org
.eclipse
.core
.runtime
.Path
;
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
;
31 * Abstract implementation of ITmfTrace.
33 * Since the concept of 'location' is trace specific, the concrete classes have
34 * to provide the related methods, namely:
36 * <li> public ITmfLocation<?> getCurrentLocation()
37 * <li> public double getLocationRatio(ITmfLocation<?> location)
38 * <li> public ITmfContext seekEvent(ITmfLocation<?> location)
39 * <li> public ITmfContext seekEvent(double ratio)
40 * <li> public boolean validate(IProject project, String path)
42 * A concrete trace must provide its corresponding parser. A common way to
43 * accomplish this is by making the concrete class extend TmfTrace and
44 * implement ITmfEventParser.
46 * The concrete class can either specify its own indexer or use the provided
47 * TmfCheckpointIndexer (default). In this case, the trace cache size will be
48 * used as checkpoint interval.
52 * @author Francois Chouinard
55 * @see ITmfTraceIndexer
56 * @see ITmfEventParser
58 public abstract class TmfTrace
<T
extends ITmfEvent
> extends TmfEventProvider
<T
> implements ITmfTrace
<T
> {
60 // ------------------------------------------------------------------------
62 // ------------------------------------------------------------------------
65 * The default trace cache size
67 public static final int DEFAULT_TRACE_CACHE_SIZE
= 10000;
69 // ------------------------------------------------------------------------
71 // ------------------------------------------------------------------------
73 // The resource used for persistent properties for this trace
74 private IResource fResource
;
80 * The trace cache page size
82 protected int fCacheSize
= DEFAULT_TRACE_CACHE_SIZE
;
85 * The number of events collected (so far)
87 protected long fNbEvents
= 0;
89 // The time span of the event stream
90 private ITmfTimestamp fStartTime
= TmfTimestamp
.BIG_CRUNCH
;
91 private ITmfTimestamp fEndTime
= TmfTimestamp
.BIG_BANG
;
94 * The trace streaming interval (0 = no streaming)
96 protected long fStreamingInterval
= 0;
101 protected ITmfTraceIndexer
<ITmfTrace
<ITmfEvent
>> fIndexer
;
106 protected ITmfEventParser
<T
> fParser
;
108 // ------------------------------------------------------------------------
110 // ------------------------------------------------------------------------
113 * The default, parameterless, constructor
115 @SuppressWarnings({ "unchecked", "rawtypes" })
118 fIndexer
= new TmfCheckpointIndexer(this);
122 * The standard constructor (non-live trace). Applicable when the trace
123 * implements its own parser and if at checkpoint-based index is OK.
125 * @param resource the resource associated to the trace
126 * @param type the trace event type
127 * @param path the trace path
128 * @param cacheSize the trace cache size
129 * @throws TmfTraceException
131 protected TmfTrace(final IResource resource
, final Class
<T
> type
, final String path
, final int cacheSize
) throws TmfTraceException
{
132 this(resource
, type
, path
, cacheSize
, 0, null);
136 * The standard constructor (live trace). Applicable when the trace
137 * implements its own parser and if at checkpoint-based index is OK.
139 * @param resource the resource associated to the trace
140 * @param type the trace event type
141 * @param path the trace path
142 * @param cacheSize the trace cache size
143 * @param interval the trace streaming interval
144 * @throws TmfTraceException
146 protected TmfTrace(final IResource resource
, final Class
<T
> type
, final String path
, final int cacheSize
, final long interval
) throws TmfTraceException
{
147 this(resource
, type
, path
, cacheSize
, interval
, null);
151 * The 'non-default indexer' constructor. Allows to provide a trace
154 * @param resource the resource associated to the trace
155 * @param type the trace event type
156 * @param path the trace path
157 * @param cacheSize the trace cache size
158 * @param indexer the trace indexer
159 * @throws TmfTraceException
161 protected TmfTrace(final IResource resource
, final Class
<T
> type
, final String path
, final int cacheSize
,
162 final long interval
, final ITmfTraceIndexer
<?
> indexer
) throws TmfTraceException
{
163 this(resource
, type
, path
, cacheSize
, interval
, null, null);
167 * The full constructor where trace specific indexer/parser are provided.
169 * @param resource the resource associated to the trace
170 * @param type the trace event type
171 * @param path the trace path
172 * @param cacheSize the trace cache size
173 * @param indexer the trace indexer
174 * @param parser the trace event parser
175 * @throws TmfTraceException
177 @SuppressWarnings({ "unchecked", "rawtypes" })
178 protected TmfTrace(final IResource resource
, final Class
<T
> type
, final String path
, final int cacheSize
,
179 final long interval
, final ITmfTraceIndexer
<?
> indexer
, final ITmfEventParser
<T
> parser
) throws TmfTraceException
{
181 fCacheSize
= (cacheSize
> 0) ? cacheSize
: DEFAULT_TRACE_CACHE_SIZE
;
182 fStreamingInterval
= interval
;
183 fIndexer
= (indexer
!= null) ? indexer
: new TmfCheckpointIndexer(this, fCacheSize
);
185 initialize(resource
, path
, type
);
191 * @param trace the original trace
193 @SuppressWarnings({ "unchecked", "rawtypes" })
194 public TmfTrace(final TmfTrace
<T
> trace
) throws TmfTraceException
{
197 throw new IllegalArgumentException();
198 fCacheSize
= trace
.getCacheSize();
199 fStreamingInterval
= trace
.getStreamingInterval();
200 fIndexer
= new TmfCheckpointIndexer(this);
201 fParser
= trace
.fParser
;
202 initialize(trace
.getResource(), trace
.getPath(), trace
.getEventType());
205 // ------------------------------------------------------------------------
206 // ITmfTrace - Initializers
207 // ------------------------------------------------------------------------
210 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#initTrace(org.eclipse.core.resources.IResource, java.lang.String, java.lang.Class)
213 public void initTrace(final IResource resource
, final String path
, final Class
<T
> type
) throws TmfTraceException
{
214 initialize(resource
, path
, type
);
215 fIndexer
.buildIndex(false);
219 * Initialize the trace common attributes and the base component.
221 * @param resource the Eclipse resource (trace)
222 * @param path the trace path
223 * @param type the trace event type
225 * @throws FileNotFoundException
227 @SuppressWarnings("unchecked")
228 protected void initialize(final IResource resource
, final String path
, final Class
<T
> type
) throws TmfTraceException
{
230 throw new TmfTraceException("Invalid trace path"); //$NON-NLS-1$
232 fResource
= resource
;
233 String traceName
= (resource
!= null) ? resource
.getName() : null;
234 // If no resource was provided, extract the display name the trace path
235 if (traceName
== null) {
236 final int sep
= path
.lastIndexOf(Path
.SEPARATOR
);
237 traceName
= (sep
>= 0) ? path
.substring(sep
+ 1) : path
;
239 if (fParser
== null) {
240 if (this instanceof ITmfEventParser
) {
241 fParser
= (ITmfEventParser
<T
>) this;
243 throw new TmfTraceException("Invalid trace parser"); //$NON-NLS-1$
246 super.init(traceName
, type
);
250 * Indicates if the path points to an existing file/directory
252 * @param path the path to test
253 * @return true if the file/directory exists
255 protected boolean fileExists(final String path
) {
256 final File file
= new File(path
);
257 return file
.exists();
260 // ------------------------------------------------------------------------
261 // ITmfTrace - Basic getters
262 // ------------------------------------------------------------------------
265 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getEventType()
268 @SuppressWarnings("unchecked")
269 public Class
<T
> getEventType() {
270 return (Class
<T
>) super.getType();
274 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getResource()
277 public IResource
getResource() {
282 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getPath()
285 public String
getPath() {
290 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getIndexPageSize()
293 public int getCacheSize() {
298 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getStreamingInterval()
301 public long getStreamingInterval() {
302 return fStreamingInterval
;
305 // ------------------------------------------------------------------------
306 // ITmfTrace - Trace characteristics getters
307 // ------------------------------------------------------------------------
310 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getNbEvents()
313 public synchronized long getNbEvents() {
318 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getTimeRange()
321 public TmfTimeRange
getTimeRange() {
322 return new TmfTimeRange(fStartTime
, fEndTime
);
326 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getStartTime()
329 public ITmfTimestamp
getStartTime() {
330 return fStartTime
.clone();
334 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getEndTime()
337 public ITmfTimestamp
getEndTime() {
338 return fEndTime
.clone();
341 // ------------------------------------------------------------------------
342 // Convenience setters
343 // ------------------------------------------------------------------------
346 * Update the trace events time range
348 * @param range the new time range
350 protected void setTimeRange(final TmfTimeRange range
) {
351 fStartTime
= range
.getStartTime().clone();
352 fEndTime
= range
.getEndTime().clone();
356 * Update the trace chronologically first event timestamp
358 * @param startTime the new first event timestamp
360 protected void setStartTime(final ITmfTimestamp startTime
) {
361 fStartTime
= startTime
.clone();
365 * Update the trace chronologically last event timestamp
367 * @param endTime the new last event timestamp
369 protected void setEndTime(final ITmfTimestamp endTime
) {
370 fEndTime
= endTime
.clone();
374 * Update the trace streaming interval
376 * @param interval the new trace streaming interval
378 protected void setStreamingInterval(final long interval
) {
379 fStreamingInterval
= (interval
> 0) ? interval
: 0;
382 // ------------------------------------------------------------------------
383 // ITmfTrace - SeekEvent operations (returning a trace context)
384 // ------------------------------------------------------------------------
387 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#seekEvent(long)
390 public synchronized ITmfContext
seekEvent(final long rank
) {
392 // A rank <= 0 indicates to seek the first event
394 ITmfContext context
= seekEvent((ITmfLocation
<?
>) null);
399 // Position the trace at the checkpoint
400 final ITmfContext context
= fIndexer
.seekIndex(rank
);
402 // And locate the requested event context
403 long pos
= context
.getRank();
405 ITmfEvent event
= readNextEvent(context
);
406 while (event
!= null && ++pos
< rank
) {
407 event
= readNextEvent(context
);
414 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#seekEvent(org.eclipse.linuxtools.tmf.core.event.ITmfTimestamp)
417 public synchronized ITmfContext
seekEvent(final ITmfTimestamp timestamp
) {
419 // A null timestamp indicates to seek the first event
420 if (timestamp
== null) {
421 ITmfContext context
= seekEvent((ITmfLocation
<?
>) null);
426 // Position the trace at the checkpoint
427 final ITmfContext context
= fIndexer
.seekIndex(timestamp
);
429 // And locate the requested event context
430 final ITmfContext nextEventContext
= context
.clone(); // Must use clone() to get the right subtype...
431 ITmfEvent event
= readNextEvent(nextEventContext
);
432 while (event
!= null && event
.getTimestamp().compareTo(timestamp
, false) < 0) {
433 context
.setLocation(nextEventContext
.getLocation().clone());
434 context
.increaseRank();
435 event
= readNextEvent(nextEventContext
);
440 // ------------------------------------------------------------------------
441 // ITmfTrace - Read operations (returning an actual event)
442 // ------------------------------------------------------------------------
445 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#readNextEvent(org.eclipse.linuxtools.tmf.core.trace.ITmfContext)
448 public synchronized ITmfEvent
readNextEvent(final ITmfContext context
) {
449 // parseEvent() does not update the context
450 final ITmfEvent event
= fParser
.parseEvent(context
);
452 updateAttributes(context
, event
.getTimestamp());
453 context
.setLocation(getCurrentLocation());
454 context
.increaseRank();
461 * Hook for special event processing by the concrete class
462 * (called by TmfTrace.getEvent())
464 * @param event the event
466 protected void processEvent(final ITmfEvent event
) {
471 * Update the trace attributes
473 * @param context the current trace context
474 * @param timestamp the corresponding timestamp
476 protected synchronized void updateAttributes(final ITmfContext context
, final ITmfTimestamp timestamp
) {
477 if (fStartTime
.compareTo(timestamp
, false) > 0) {
478 fStartTime
= timestamp
;
480 if (fEndTime
.compareTo(timestamp
, false) < 0) {
481 fEndTime
= timestamp
;
483 if (context
.hasValidRank()) {
484 long rank
= context
.getRank();
485 if (fNbEvents
<= rank
) {
486 fNbEvents
= rank
+ 1;
488 fIndexer
.updateIndex(context
, timestamp
);
492 // ------------------------------------------------------------------------
494 // ------------------------------------------------------------------------
497 * @see org.eclipse.linuxtools.tmf.core.component.TmfDataProvider#armRequest(org.eclipse.linuxtools.tmf.core.request.ITmfDataRequest)
500 public ITmfContext
armRequest(final ITmfDataRequest
<T
> request
) {
501 if (request
instanceof ITmfEventRequest
<?
>
502 && !TmfTimestamp
.BIG_BANG
.equals(((ITmfEventRequest
<T
>) request
).getRange().getStartTime())
503 && request
.getIndex() == 0) {
504 final ITmfContext context
= seekEvent(((ITmfEventRequest
<T
>) request
).getRange().getStartTime());
505 ((ITmfEventRequest
<T
>) request
).setStartIndex((int) context
.getRank());
509 return seekEvent(request
.getIndex());
513 * @see org.eclipse.linuxtools.tmf.core.component.TmfDataProvider#getNext(org.eclipse.linuxtools.tmf.core.trace.ITmfContext)
516 @SuppressWarnings("unchecked")
517 public T
getNext(final ITmfContext context
) {
518 if (context
instanceof TmfContext
)
519 return (T
) readNextEvent(context
);
524 // ------------------------------------------------------------------------
526 // ------------------------------------------------------------------------
529 * @see java.lang.Object#toString()
532 @SuppressWarnings("nls")
533 public synchronized String
toString() {
534 return "TmfTrace [fPath=" + fPath
+ ", fCacheSize=" + fCacheSize
535 + ", fNbEvents=" + fNbEvents
+ ", fStartTime=" + fStartTime
536 + ", fEndTime=" + fEndTime
+ ", fStreamingInterval=" + fStreamingInterval
+ "]";