Commit | Line | Data |
---|---|---|
8c8bf09f | 1 | /******************************************************************************* |
8636b448 | 2 | * Copyright (c) 2009, 2011, 2012 Ericsson |
8c8bf09f ASL |
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 | |
8636b448 | 11 | * Francois Chouinard - Updated as per TMF Trace Model 1.0 |
8c8bf09f ASL |
12 | *******************************************************************************/ |
13 | ||
6c13869b | 14 | package org.eclipse.linuxtools.tmf.core.trace; |
8c8bf09f | 15 | |
12c155f5 FC |
16 | import java.io.FileNotFoundException; |
17 | ||
18 | import org.eclipse.core.resources.IProject; | |
a1091415 | 19 | import org.eclipse.core.resources.IResource; |
6c13869b | 20 | import org.eclipse.linuxtools.tmf.core.component.ITmfComponent; |
72f1e62a | 21 | import org.eclipse.linuxtools.tmf.core.event.ITmfEvent; |
4df4581d | 22 | import org.eclipse.linuxtools.tmf.core.event.ITmfTimestamp; |
6c13869b | 23 | import org.eclipse.linuxtools.tmf.core.event.TmfTimeRange; |
8c8bf09f ASL |
24 | |
25 | /** | |
146a887c | 26 | * <b><u>ITmfTrace</u></b> |
8c8bf09f | 27 | * <p> |
3118edf1 | 28 | * The basic event trace structure in TMF. |
8c8bf09f | 29 | */ |
3791b5df | 30 | public interface ITmfTrace<T extends ITmfEvent> extends ITmfComponent, Cloneable { |
12c155f5 | 31 | |
8636b448 FC |
32 | // ------------------------------------------------------------------------ |
33 | // Initializers | |
34 | // ------------------------------------------------------------------------ | |
085d898f | 35 | |
3118edf1 FC |
36 | /** |
37 | * Initialize a newly instantiated "empty" trace object. This is used to | |
38 | * parameterize an ITmfTrace instantiated with its parameterless constructor. | |
39 | * | |
40 | * @param name the trace name | |
41 | * @param path the trace path | |
3791b5df | 42 | * @param type the trace event type |
3118edf1 FC |
43 | * @throws FileNotFoundException |
44 | */ | |
3791b5df | 45 | public void initTrace(String name, String path, Class<T> type) throws FileNotFoundException; |
12c155f5 | 46 | |
3118edf1 FC |
47 | /** |
48 | * Validate that the trace is of the correct type. | |
49 | * | |
50 | * @param project the eclipse project | |
51 | * @param path the trace path | |
52 | * | |
53 | * @return true if trace is valid | |
54 | */ | |
55 | public boolean validate(IProject project, String path); | |
12c155f5 | 56 | |
3118edf1 FC |
57 | /** |
58 | * Set the resource used for persistent properties on this trace | |
59 | * | |
60 | * @param resource the properties resource | |
61 | */ | |
62 | public void setResource(IResource resource); | |
96c6806f | 63 | |
8636b448 | 64 | // ------------------------------------------------------------------------ |
3118edf1 | 65 | // Basic getters |
8636b448 | 66 | // ------------------------------------------------------------------------ |
b0a282fb | 67 | |
abfad0aa | 68 | /** |
12c155f5 FC |
69 | * @return the trace path |
70 | */ | |
71 | public String getPath(); | |
72 | ||
73 | /** | |
3791b5df | 74 | * @return the properties resource or null if none is set |
12c155f5 | 75 | */ |
3791b5df | 76 | public IResource getResource(); |
12c155f5 | 77 | |
12c155f5 FC |
78 | /** |
79 | * @return the number of events in the trace | |
80 | */ | |
81 | public long getNbEvents(); | |
82 | ||
83 | /** | |
3118edf1 | 84 | * @return the trace time range |
12c155f5 FC |
85 | */ |
86 | public TmfTimeRange getTimeRange(); | |
87 | ||
3118edf1 FC |
88 | /** |
89 | * @return the timestamp of the first trace event | |
90 | */ | |
4df4581d | 91 | public ITmfTimestamp getStartTime(); |
12c155f5 | 92 | |
3118edf1 FC |
93 | /** |
94 | * @return the timestamp of the last trace event | |
95 | */ | |
4df4581d | 96 | public ITmfTimestamp getEndTime(); |
62d1696a | 97 | |
1b70b6dc PT |
98 | /** |
99 | * @return the streaming interval in ms (0 if not streaming) | |
100 | */ | |
101 | public long getStreamingInterval(); | |
102 | ||
3118edf1 FC |
103 | /** |
104 | * @return the trace index page size | |
105 | */ | |
106 | public int getIndexPageSize(); | |
107 | ||
3791b5df FC |
108 | // ------------------------------------------------------------------------ |
109 | // Indexing | |
110 | // ------------------------------------------------------------------------ | |
111 | ||
112 | /** | |
113 | * Start the trace indexing, optionally wait for the index to be fully | |
114 | * built before returning. | |
115 | * | |
116 | * @param waitForCompletion true for synchronous indexing | |
117 | */ | |
118 | public void indexTrace(boolean waitForCompletion); | |
119 | ||
8636b448 FC |
120 | // ------------------------------------------------------------------------ |
121 | // Seek operations | |
122 | // ------------------------------------------------------------------------ | |
123 | ||
12c155f5 | 124 | /** |
3118edf1 | 125 | * Position the trace at the specified location. The null location |
085d898f | 126 | * is used to indicate that the first trace event. |
4e3aa37d | 127 | * |
3118edf1 FC |
128 | * @param location the trace specific location (null for 1st event) |
129 | * @return a context which can later be used to read the corresponding event | |
8c8bf09f | 130 | */ |
34ccf9a9 | 131 | public ITmfContext seekLocation(ITmfLocation<?> location); |
12c155f5 | 132 | |
c76c54bb | 133 | /** |
3118edf1 FC |
134 | * Position the trace at the event located at the specified ratio in the |
135 | * trace file. | |
c76c54bb | 136 | * |
3118edf1 FC |
137 | * The notion of ratio (0.0 <= r <= 1.0) is trace specific and left |
138 | * voluntarily vague. Typically, it would refer to the event proportional | |
085d898f | 139 | * rank or timestamp in the trace file. |
c76c54bb | 140 | * |
3118edf1 FC |
141 | * @param ratio the proportional 'rank' in the trace |
142 | * @return a context which can later be used to read the corresponding event | |
c76c54bb | 143 | */ |
34ccf9a9 | 144 | public ITmfContext seekLocation(double ratio); |
12c155f5 | 145 | |
3118edf1 FC |
146 | /** |
147 | * Position the trace at the first event with the specified timestamp. If | |
148 | * there is no event with the requested timestamp, a context pointing to | |
149 | * the chronologically next event is returned. | |
150 | * | |
151 | * @param timestamp the timestamp of desired event | |
152 | * @return a context which can later be used to read the corresponding event | |
153 | */ | |
154 | public ITmfContext seekEvent(ITmfTimestamp timestamp); | |
155 | ||
156 | /** | |
157 | * Position the trace at the Nth event in the trace. | |
158 | * | |
159 | * @param rank the event rank | |
160 | * @return a context which can later be used to read the corresponding event | |
161 | */ | |
162 | public ITmfContext seekEvent(long rank); | |
163 | ||
8636b448 FC |
164 | // ------------------------------------------------------------------------ |
165 | // Read operations | |
166 | // ------------------------------------------------------------------------ | |
167 | ||
168 | /** | |
3118edf1 FC |
169 | * Return the event pointed by the supplied context (or null if no event |
170 | * left) and updates the context to point the next event. | |
8636b448 | 171 | * |
3118edf1 | 172 | * @param context the read context |
8636b448 FC |
173 | * @return the next event in the stream |
174 | */ | |
175 | public ITmfEvent getNextEvent(ITmfContext context); | |
176 | ||
177 | /** | |
3118edf1 FC |
178 | * Return the event pointed by the supplied context (or null if no event |
179 | * left) and *does not* update the context. | |
8636b448 | 180 | * |
3118edf1 | 181 | * @param context the read context |
8636b448 FC |
182 | * @return the next event in the stream |
183 | */ | |
184 | public ITmfEvent parseEvent(ITmfContext context); | |
185 | ||
186 | ||
187 | // ------------------------------------------------------------------------ | |
3791b5df | 188 | // Location operations |
8636b448 FC |
189 | // ------------------------------------------------------------------------ |
190 | ||
3791b5df FC |
191 | /** |
192 | * @return the current trace location | |
193 | */ | |
194 | public ITmfLocation<?> getCurrentLocation(); | |
195 | ||
c76c54bb | 196 | /** |
3118edf1 | 197 | * Returns the ratio (proportion) corresponding to the specified location. |
c76c54bb | 198 | * |
3118edf1 | 199 | * @param location a trace specific location |
c76c54bb FC |
200 | * @return a floating-point number between 0.0 (beginning) and 1.0 (end) |
201 | */ | |
202 | public double getLocationRatio(ITmfLocation<?> location); | |
12c155f5 | 203 | |
abfad0aa | 204 | /** |
3118edf1 FC |
205 | * Returns the rank of the first event with the requested timestamp. |
206 | * If none, returns the index of the subsequent event (if any). | |
12c155f5 | 207 | * |
0d9a6d76 FC |
208 | * @param timestamp the requested event timestamp |
209 | * @return the corresponding event rank | |
abfad0aa | 210 | */ |
4df4581d | 211 | public long getRank(ITmfTimestamp timestamp); |
12c155f5 | 212 | |
3791b5df FC |
213 | // ------------------------------------------------------------------------ |
214 | // Cloneable | |
215 | // ------------------------------------------------------------------------ | |
216 | ||
217 | /** | |
218 | * @return a clone of the trace | |
219 | */ | |
220 | public ITmfTrace<T> clone() throws CloneNotSupportedException; | |
085d898f | 221 | |
8c8bf09f | 222 | } |