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
.IProject
;
20 import org
.eclipse
.core
.resources
.IResource
;
21 import org
.eclipse
.core
.runtime
.Path
;
22 import org
.eclipse
.linuxtools
.tmf
.core
.component
.TmfEventProvider
;
23 import org
.eclipse
.linuxtools
.tmf
.core
.event
.ITmfEvent
;
24 import org
.eclipse
.linuxtools
.tmf
.core
.event
.ITmfTimestamp
;
25 import org
.eclipse
.linuxtools
.tmf
.core
.event
.TmfTimeRange
;
26 import org
.eclipse
.linuxtools
.tmf
.core
.event
.TmfTimestamp
;
27 import org
.eclipse
.linuxtools
.tmf
.core
.exceptions
.TmfTraceException
;
28 import org
.eclipse
.linuxtools
.tmf
.core
.request
.ITmfDataRequest
;
29 import org
.eclipse
.linuxtools
.tmf
.core
.request
.ITmfEventRequest
;
32 * <b><u>TmfTrace</u></b>
34 * Abstract implementation of ITmfTrace.
36 * Since the concept of 'location' is trace specific, the concrete classes have
37 * to provide the related methods, namely:
39 * <li> public ITmfLocation<?> getCurrentLocation()
40 * <li> public double getLocationRatio(ITmfLocation<?> location)
41 * <li> public ITmfContext seekEvent(ITmfLocation<?> location)
42 * <li> public ITmfContext seekEvent(double ratio)
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.
52 public abstract class TmfTrace
<T
extends ITmfEvent
> extends TmfEventProvider
<T
> implements ITmfTrace
<T
> {
54 // ------------------------------------------------------------------------
56 // ------------------------------------------------------------------------
59 * The default trace cache size
61 public static final int DEFAULT_TRACE_CACHE_SIZE
= 10000;
63 // ------------------------------------------------------------------------
65 // ------------------------------------------------------------------------
67 // The resource used for persistent properties for this trace
68 private IResource fResource
;
76 protected int fCacheSize
= DEFAULT_TRACE_CACHE_SIZE
;
79 * The number of events collected so far
81 protected long fNbEvents
= 0;
83 // The time span of the event stream
84 private ITmfTimestamp fStartTime
= TmfTimestamp
.BIG_CRUNCH
;
85 private ITmfTimestamp fEndTime
= TmfTimestamp
.BIG_BANG
;
88 * The trace streaming interval (0 = no streaming)
90 protected long fStreamingInterval
= 0;
95 protected ITmfTraceIndexer
<ITmfTrace
<ITmfEvent
>> fIndexer
;
100 protected ITmfEventParser
<ITmfEvent
> fParser
;
102 // ------------------------------------------------------------------------
104 // ------------------------------------------------------------------------
107 * The default, parameterless, constructor
109 @SuppressWarnings({ "unchecked", "rawtypes" })
112 fIndexer
= new TmfCheckpointIndexer(this);
116 * The standard constructor (non-live trace). Applicable when the trace
117 * implements its own parser and if at checkpoint-based index is OK.
119 * @param resource the resource associated to the trace
120 * @param type the trace event type
121 * @param path the trace path
122 * @param cacheSize the trace cache size
123 * @throws FileNotFoundException
125 protected TmfTrace(final IResource resource
, final Class
<T
> type
, final String path
, final int cacheSize
) throws TmfTraceException
{
126 this(resource
, type
, path
, cacheSize
, 0, null);
130 * The standard constructor (live trace). Applicable when the trace
131 * implements its own parser and if at checkpoint-based index is OK.
133 * @param resource the resource associated to the trace
134 * @param type the trace event type
135 * @param path the trace path
136 * @param cacheSize the trace cache size
137 * @param interval the trace streaming interval
138 * @throws FileNotFoundException
140 protected TmfTrace(final IResource resource
, final Class
<T
> type
, final String path
, final int cacheSize
, final long interval
) throws TmfTraceException
{
141 this(resource
, type
, path
, cacheSize
, interval
, null);
145 * The 'non-default indexer' constructor. Allows to provide a trace
148 * @param resource the resource associated to the trace
149 * @param type the trace event type
150 * @param path the trace path
151 * @param cacheSize the trace cache size
152 * @param indexer the trace indexer
153 * @throws FileNotFoundException
155 protected TmfTrace(final IResource resource
, final Class
<T
> type
, final String path
, final int cacheSize
,
156 final long interval
, final ITmfTraceIndexer
<?
> indexer
) throws TmfTraceException
{
157 this(resource
, type
, path
, cacheSize
, interval
, null, null);
161 * The full constructor where trace specific indexer/parser are provided.
163 * @param resource the resource associated to the trace
164 * @param type the trace event type
165 * @param path the trace path
166 * @param cacheSize the trace cache size
167 * @param indexer the trace indexer
168 * @param parser the trace event parser
169 * @throws FileNotFoundException
171 @SuppressWarnings({ "unchecked", "rawtypes" })
172 protected TmfTrace(final IResource resource
, final Class
<T
> type
, final String path
, final int cacheSize
,
173 final long interval
, final ITmfTraceIndexer
<?
> indexer
, final ITmfEventParser
<ITmfEvent
> parser
) throws TmfTraceException
{
175 fCacheSize
= (cacheSize
> 0) ? cacheSize
: DEFAULT_TRACE_CACHE_SIZE
;
176 fStreamingInterval
= interval
;
177 fIndexer
= (indexer
!= null) ? indexer
: new TmfCheckpointIndexer(this, fCacheSize
);
179 initialize(resource
, path
, type
);
185 * @param trace the original trace
187 @SuppressWarnings({ "unchecked", "rawtypes" })
188 public TmfTrace(final TmfTrace
<T
> trace
) throws TmfTraceException
{
191 throw new IllegalArgumentException();
192 fCacheSize
= trace
.getCacheSize();
193 fStreamingInterval
= trace
.getStreamingInterval();
194 fIndexer
= new TmfCheckpointIndexer(this);
195 fParser
= trace
.fParser
;
196 initialize(trace
.getResource(), trace
.getPath(), trace
.getEventType());
199 // ------------------------------------------------------------------------
200 // ITmfTrace - Initializers
201 // ------------------------------------------------------------------------
204 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#initTrace(org.eclipse.core.resources.IResource, java.lang.String, java.lang.Class)
207 public void initTrace(final IResource resource
, final String path
, final Class
<T
> type
) throws TmfTraceException
{
208 initialize(resource
, path
, type
);
209 fIndexer
.buildIndex(false);
213 * Initialize the trace common attributes and the base component.
215 * @param resource the Eclipse resource (trace)
216 * @param path the trace path
217 * @param type the trace event type
219 * @throws FileNotFoundException
221 protected void initialize(final IResource resource
, final String path
, final Class
<T
> type
) throws TmfTraceException
{
223 throw new TmfTraceException("Invalid trace path"); //$NON-NLS-1$
225 fResource
= resource
;
226 String traceName
= (resource
!= null) ? resource
.getName() : null;
227 // If no resource was provided, extract the display name the trace path
228 if (traceName
== null) {
229 final int sep
= path
.lastIndexOf(Path
.SEPARATOR
);
230 traceName
= (sep
>= 0) ? path
.substring(sep
+ 1) : path
;
232 if (fParser
== null && !(this instanceof ITmfEventParser
))
233 throw new TmfTraceException("Invalid trace parser"); //$NON-NLS-1$
234 super.init(traceName
, type
);
238 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#validate(org.eclipse.core.resources.IProject, java.lang.String)
240 * Default validation: make sure the trace file exists.
243 public boolean validate(final IProject project
, final String path
) {
244 final File file
= new File(path
);
245 return file
.exists();
248 // ------------------------------------------------------------------------
249 // ITmfTrace - Basic getters
250 // ------------------------------------------------------------------------
253 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getEventType()
256 @SuppressWarnings("unchecked")
257 public Class
<T
> getEventType() {
258 return (Class
<T
>) super.getType();
262 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getResource()
265 public IResource
getResource() {
270 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getPath()
273 public String
getPath() {
278 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getIndexPageSize()
281 public int getCacheSize() {
286 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getStreamingInterval()
289 public long getStreamingInterval() {
290 return fStreamingInterval
;
293 // ------------------------------------------------------------------------
294 // ITmfTrace - Trace characteristics getters
295 // ------------------------------------------------------------------------
298 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getNbEvents()
301 public long getNbEvents() {
306 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getTimeRange()
309 public TmfTimeRange
getTimeRange() {
310 return new TmfTimeRange(fStartTime
, fEndTime
);
314 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getStartTime()
317 public ITmfTimestamp
getStartTime() {
318 return fStartTime
.clone();
322 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#getEndTime()
325 public ITmfTimestamp
getEndTime() {
326 return fEndTime
.clone();
329 // ------------------------------------------------------------------------
330 // Convenience setters
331 // ------------------------------------------------------------------------
334 * Update the trace events time range
336 * @param range the new time range
338 protected void setTimeRange(final TmfTimeRange range
) {
339 fStartTime
= range
.getStartTime().clone();
340 fEndTime
= range
.getEndTime().clone();
344 * Update the trace chronologically first event timestamp
346 * @param startTime the new first event timestamp
348 protected void setStartTime(final ITmfTimestamp startTime
) {
349 fStartTime
= startTime
.clone();
353 * Update the trace chronologically last event timestamp
355 * @param endTime the new last event timestamp
357 protected void setEndTime(final ITmfTimestamp endTime
) {
358 fEndTime
= endTime
.clone();
362 * Update the trace streaming interval
364 * @param interval the new trace streaming interval
366 protected void setStreamingInterval(final long interval
) {
367 fStreamingInterval
= (interval
> 0) ? interval
: 0;
370 // ------------------------------------------------------------------------
371 // ITmfTrace - SeekEvent operations (returning a trace context)
372 // ------------------------------------------------------------------------
375 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#seekEvent(long)
378 public synchronized ITmfContext
seekEvent(final long rank
) {
380 // A rank <= 0 indicates to seek the first event
382 return seekEvent((ITmfLocation
<?
>) null);
384 // Position the trace at the checkpoint
385 final ITmfContext context
= fIndexer
.seekIndex(rank
);
387 // And locate the requested event context
388 long pos
= context
.getRank();
390 ITmfEvent event
= readNextEvent(context
);
391 while (event
!= null && ++pos
< rank
) {
392 event
= readNextEvent(context
);
399 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#seekEvent(org.eclipse.linuxtools.tmf.core.event.ITmfTimestamp)
402 public synchronized ITmfContext
seekEvent(final ITmfTimestamp timestamp
) {
404 // A null timestamp indicates to seek the first event
405 if (timestamp
== null)
408 // Position the trace at the checkpoint
409 final ITmfContext context
= fIndexer
.seekIndex(timestamp
);
411 // And locate the requested event context
412 final ITmfContext nextEventContext
= context
.clone(); // Must use clone() to get the right subtype...
413 ITmfEvent event
= readNextEvent(nextEventContext
);
414 while (event
!= null && event
.getTimestamp().compareTo(timestamp
, false) < 0) {
415 context
.setLocation(nextEventContext
.getLocation().clone());
416 context
.increaseRank();
417 event
= readNextEvent(nextEventContext
);
422 // ------------------------------------------------------------------------
423 // ITmfTrace - Read operations (returning an actual event)
424 // ------------------------------------------------------------------------
427 * @see org.eclipse.linuxtools.tmf.core.trace.ITmfTrace#readNextEvent(org.eclipse.linuxtools.tmf.core.trace.ITmfContext)
430 public synchronized ITmfEvent
readNextEvent(final ITmfContext context
) {
431 // parseEvent() does not update the context
432 final ITmfEvent event
= fParser
.parseEvent(context
);
434 updateAttributes(context
, event
.getTimestamp());
435 context
.setLocation(getCurrentLocation());
436 context
.increaseRank();
443 * Hook for special event processing by the concrete class
444 * (called by TmfTrace.getEvent())
446 * @param event the event
448 protected void processEvent(final ITmfEvent event
) {
453 * Update the trace attributes
455 * @param context the current trace context
459 protected synchronized void updateAttributes(final ITmfContext context
, final ITmfTimestamp timestamp
) {
460 if (fStartTime
.compareTo(timestamp
, false) > 0) {
461 fStartTime
= timestamp
;
463 if (fEndTime
.compareTo(timestamp
, false) < 0) {
464 fEndTime
= timestamp
;
466 if (context
.hasValidRank()) {
467 long rank
= context
.getRank();
468 if (fNbEvents
<= rank
) {
469 fNbEvents
= rank
+ 1;
471 fIndexer
.updateIndex(context
, timestamp
);
475 // ------------------------------------------------------------------------
477 // ------------------------------------------------------------------------
480 * @see org.eclipse.linuxtools.tmf.core.component.TmfDataProvider#armRequest(org.eclipse.linuxtools.tmf.core.request.ITmfDataRequest)
483 public ITmfContext
armRequest(final ITmfDataRequest
<T
> request
) {
484 if (request
instanceof ITmfEventRequest
<?
>
485 && !TmfTimestamp
.BIG_BANG
.equals(((ITmfEventRequest
<T
>) request
).getRange().getStartTime())
486 && request
.getIndex() == 0) {
487 final ITmfContext context
= seekEvent(((ITmfEventRequest
<T
>) request
).getRange().getStartTime());
488 ((ITmfEventRequest
<T
>) request
).setStartIndex((int) context
.getRank());
492 return seekEvent(request
.getIndex());
496 * @see org.eclipse.linuxtools.tmf.core.component.TmfDataProvider#getNext(org.eclipse.linuxtools.tmf.core.trace.ITmfContext)
499 @SuppressWarnings("unchecked")
500 public T
getNext(final ITmfContext context
) {
501 if (context
instanceof TmfContext
)
502 return (T
) readNextEvent(context
);
507 // ------------------------------------------------------------------------
509 // ------------------------------------------------------------------------
512 * @see java.lang.Object#toString()
515 @SuppressWarnings("nls")
516 public String
toString() {
517 return "TmfTrace [fPath=" + fPath
+ ", fCacheSize=" + fCacheSize
518 + ", fNbEvents=" + fNbEvents
+ ", fStartTime=" + fStartTime
519 + ", fEndTime=" + fEndTime
+ ", fStreamingInterval=" + fStreamingInterval
+ "]";