+ * A trace can be accessed simultaneously from multiple threads by various + * application components. To avoid obvious multi-threading issues, the trace + * uses an ITmfContext as a synchronization aid for its read operations. + *
+ * A proper ITmfContext can be obtained by performing a seek operation on the + * trace. Seek operations can be performed for a particular event (by rank or + * timestamp) or for a plain trace location. + *
+ * Example 1: Process a whole trace + *
+ * ITmfContext context = trace.seekEvent(0);
+ * ITmfEvent event = trace.getNext(context);
+ * while (event != null) {
+ * processEvent(event);
+ * event = trace.getNext(context);
+ * }
+ *
+ * Example 2: Process 50 events starting from the 1000th event
+ *
+ * int nbEventsRead = 0;
+ * ITmfContext context = trace.seekEvent(1000);
+ * ITmfEvent event = trace.getNext(context);
+ * while (event != null && nbEventsRead < 50) {
+ * nbEventsRead++;
+ * processEvent(event);
+ * event = trace.getNext(context);
+ * }
+ *
+ * Example 3: Process the events between 2 timestamps (inclusive)
+ *
+ * ITmfTimestamp startTime = ...;
+ * ITmfTimestamp endTime = ...;
+ * ITmfContext context = trace.seekEvent(startTime);
+ * ITmfEvent event = trace.getNext(context);
+ * while (event != null && event.getTimestamp().compareTo(endTime) <= 0) {
+ * processEvent(event);
+ * event = trace.getNext(context);
+ * }
+ *
+ * A trace is also an event provider so it can process event requests
+ * asynchronously (and coalesce compatible, concurrent requests).
+ * + * + * Example 4: Process a whole trace (see ITmfEventRequest for variants) + *
+ * ITmfRequest request = new TmfEventRequest<MyEventType>(MyEventType.class) {
+ * @Override
+ * public void handleData(MyEventType event) {
+ * super.handleData(event);
+ * processEvent(event);
+ * }
+ * @Override
+ * public void handleCompleted() {
+ * finish();
+ * super.handleCompleted();
+ * }
+ * };
+ *
+ * fTrace.handleRequest(request);
+ * if (youWant) {
+ * request.waitForCompletion();
+ * }
+ *
+ *
+ * @version 1.0
+ * @author Francois Chouinard
+ *
+ * @see ITmfContext
+ * @see ITmfEvent
+ * @see ITmfTraceIndexer
+ * @see ITmfEventParser
*/
-public interface ITmfTrace
+ * Typically, the parameterless constructor will provide the block size
+ * and its associated parser and indexer.
+ *
+ * @param resource the trace resource
+ * @param path the trace path
+ * @param type the trace event type
+ * @throws TmfTraceException If we couldn't open the trace
+ */
+ void initTrace(IResource resource, String path, Class type) throws TmfTraceException;
- public void initTrace(String name, String path, Class
+ * A null location is interpreted as seeking for the first event of the
+ * trace.
+ *
+ * If not null, the location requested must be valid otherwise the returned
+ * context is undefined (up to the implementation to recover if possible).
+ *
+ * @param location the trace specific location
+ * @return a context which can later be used to read the corresponding event
+ */
+ ITmfContext seekEvent(ITmfLocation location);
+
+ /**
+ * Position the trace at the 'rank'th event in the trace.
+ *
+ * A rank <= 0 is interpreted as seeking for the first event of the
+ * trace.
+ *
+ * If the requested rank is beyond the last trace event, the context
+ * returned will yield a null event if used in a subsequent read.
+ *
+ * @param rank the event rank
+ * @return a context which can later be used to read the corresponding event
+ */
+ ITmfContext seekEvent(long rank);
+
+ /**
+ * Position the trace at the first event with the specified timestamp. If
+ * there is no event with the requested timestamp, a context pointing to
+ * the next chronological event is returned.
+ *
+ * A null timestamp is interpreted as seeking for the first event of the
+ * trace.
+ *
+ * If the requested timestamp is beyond the last trace event, the context
+ * returned will yield a null event if used in a subsequent read.
+ *
+ * @param timestamp the timestamp of desired event
+ * @return a context which can later be used to read the corresponding event
+ * @since 2.0
+ */
+ ITmfContext seekEvent(ITmfTimestamp timestamp);
/**
- * Returns the rank of the first event with the requested timestamp. If none, returns the index of the next event
- * (if any).
- *
- * @param timestamp
- * @return
+ * Position the trace at the event located at the specified ratio in the
+ * trace file.
+ *
+ * The notion of ratio (0.0 <= r <= 1.0) is trace specific and left
+ * voluntarily vague. Typically, it would refer to the event proportional
+ * rank (arguably more intuitive) or timestamp in the trace file.
+ *
+ * @param ratio the proportional 'rank' in the trace
+ * @return a context which can later be used to read the corresponding event
*/
- public long getRank(ITmfTimestamp timestamp);
+ ITmfContext seekEvent(double ratio);
/**
- * Return the event pointed by the supplied context (or null if no event left) and updates the context to the next
- * event.
- *
- * @return the next event in the stream
+ * Returns the initial range offset
+ *
+ * @return the initial range offset
+ * @since 2.0
*/
- public ITmfEvent getNextEvent(TmfContext context);
+ ITmfTimestamp getInitialRangeOffset();
/**
- * Return the event pointed by the supplied context (or null if no event left) and *does not* update the context.
- *
- * @return the next event in the stream
+ * Returns the ID of the host this trace is from. The host ID is not
+ * necessarily the hostname, but should be a unique identifier for the
+ * machine on which the trace was taken. It can be used to determine if two
+ * traces were taken on the exact same machine (timestamp are already
+ * synchronized, resources with same id are the same if taken at the same
+ * time, etc).
+ *
+ * @return The host id of this trace
+ * @since 3.0
*/
- public ITmfEvent parseEvent(TmfContext context);
+ String getHostId();
}