[deliverable/tracecompass.git] / org.eclipse.linuxtools.tmf / src / org / eclipse / linuxtools / tmf / trace / ITmfTrace.java

/*******************************************************************************
 * Copyright (c) 2009 Ericsson
 * 
 * All rights reserved. This program and the accompanying materials are
 * made available under the terms of the Eclipse Public License v1.0 which
 * accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 * 
 * Contributors:
 *   Francois Chouinard - Initial API and implementation
 *******************************************************************************/

package org.eclipse.linuxtools.tmf.trace;

import org.eclipse.linuxtools.tmf.event.TmfEvent;
import org.eclipse.linuxtools.tmf.event.TmfTimeRange;
import org.eclipse.linuxtools.tmf.event.TmfTimestamp;

/**
 * <b><u>ITmfTrace</u></b>
 * <p>
 * TODO: Implement me. Please.
 */
public interface ITmfTrace {

	/**
	 * <b><u>StreamContext</u></b>
	 * <p>
	 * Stream context keeper. Used to prevent conflicting, concurrent accesses
	 * to the underlying trace. 
	 */
	public class TmfTraceContext {
		public Object location;
		public int    index;

		public TmfTraceContext(Object loc, int ind) {
			location = loc;
			index = ind;
		}

		public TmfTraceContext(TmfTraceContext other) {
			if (other != null) {
				location = other.location;
				index = other.index;
			}
		}
	}
    
	/**
	 * @return the trace name 
	 */
	public String getName();
    
	/**
	 * @return the number of events in the trace
	 */
	public int getNbEvents();
    
	/**
	 * Trace time range handlers
	 */
	public void setTimeRange(TmfTimeRange range);
	public void setStartTime(TmfTimestamp startTime);
	public void setEndTime(TmfTimestamp endTime);

	public TmfTimeRange getTimeRange();
    public TmfTimestamp getStartTime();
    public TmfTimestamp getEndTime();

    /**
     * Positions the trace at the first event with the specified
     * timestamp or index (i.e. the nth event in the trace)
     * 
     * @param timestamp
     * @param index
     * @return a context object for subsequent reads
     */
    public TmfTraceContext seekEvent(TmfTimestamp timestamp);
    public TmfTraceContext seekEvent(int index);

    /**
     * These functions handle the mapping between an abstract trace
     * and the actual implementation.
     * 
     * <code>parseEvent()</code> parses the event at the current
     * trace location.
     * 
     * <code>processEvent()</code> is a hook for application
     * specific processing once the event has been read.
     */
    public Object getCurrentLocation();
    public TmfTraceContext seekLocation(Object location);
    public TmfEvent parseNextEvent();
	public void processEvent(TmfEvent event);

    /**
     * These functions return the event pointed by the supplied context
     * (or null if no event left).
     * 
     * The context is updated to point to the next trace event, expect
     * for tpeekEvent() which doesn't update the context.
     * 
     * @return the next event in the stream
     */
    public TmfEvent peekEvent(TmfTraceContext context);
    public TmfEvent getEvent(TmfTraceContext context, TmfTimestamp timestamp);
    public TmfEvent getEvent(TmfTraceContext context, int index);
    public TmfEvent getNextEvent(TmfTraceContext context);

    /**
     * Index the stream and creates the checkpoint structure.
     * Normally invoked once at the creation of the event stream.
     */
    public void indexStream();

    /**
     * Returns the index of the first event at the supplied timestamp.
     * If there is no such event, return the next one (null if none left).
     * 
     * @param timestamp
     * @return
     */
	public int getIndex(TmfTimestamp timestamp); 

	/**
	 * Returns the timestamp of the event at position [index]
	 * (null if none left). 
	 * 
	 * @param index the event index
	 * @return the corresponding timestamp
	 */
    public TmfTimestamp getTimestamp(int index);
}
Commit	Line	Data
	1	/*******************************************************************************
	2	* Copyright (c) 2009 Ericsson
	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
	11	*******************************************************************************/
	12
	13	package org.eclipse.linuxtools.tmf.trace;
	14
	15	import org.eclipse.linuxtools.tmf.event.TmfEvent;
	16	import org.eclipse.linuxtools.tmf.event.TmfTimeRange;
	17	import org.eclipse.linuxtools.tmf.event.TmfTimestamp;
	18
	19	/**
	20	* <b><u>ITmfTrace</u></b>
	21	* <p>
	22	* TODO: Implement me. Please.
	23	*/
	24	public interface ITmfTrace {
	25
	26	/**
	27	* <b><u>StreamContext</u></b>
	28	* <p>
	29	* Stream context keeper. Used to prevent conflicting, concurrent accesses
	30	* to the underlying trace.
	31	*/
	32	public class TmfTraceContext {
	33	public Object location;
	34	public int index;
	35
	36	public TmfTraceContext(Object loc, int ind) {
	37	location = loc;
	38	index = ind;
	39	}
	40
	41	public TmfTraceContext(TmfTraceContext other) {
	42	if (other != null) {
	43	location = other.location;
	44	index = other.index;
	45	}
	46	}
	47	}
	48
	49	/**
	50	* @return the trace name
	51	*/
	52	public String getName();
	53
	54	/**
	55	* @return the number of events in the trace
	56	*/
	57	public int getNbEvents();
	58
	59	/**
	60	* Trace time range handlers
	61	*/
	62	public void setTimeRange(TmfTimeRange range);
	63	public void setStartTime(TmfTimestamp startTime);
	64	public void setEndTime(TmfTimestamp endTime);
	65
	66	public TmfTimeRange getTimeRange();
	67	public TmfTimestamp getStartTime();
	68	public TmfTimestamp getEndTime();
	69
	70	/**
	71	* Positions the trace at the first event with the specified
	72	* timestamp or index (i.e. the nth event in the trace)
	73	*
	74	* @param timestamp
	75	* @param index
	76	* @return a context object for subsequent reads
	77	*/
	78	public TmfTraceContext seekEvent(TmfTimestamp timestamp);
	79	public TmfTraceContext seekEvent(int index);
	80
	81	/**
	82	* These functions handle the mapping between an abstract trace
	83	* and the actual implementation.
	84	*
	85	* <code>parseEvent()</code> parses the event at the current
	86	* trace location.
	87	*
	88	* <code>processEvent()</code> is a hook for application
	89	* specific processing once the event has been read.
	90	*/
	91	public Object getCurrentLocation();
	92	public TmfTraceContext seekLocation(Object location);
	93	public TmfEvent parseNextEvent();
	94	public void processEvent(TmfEvent event);
	95
	96	/**
	97	* These functions return the event pointed by the supplied context
	98	* (or null if no event left).
	99	*
	100	* The context is updated to point to the next trace event, expect
	101	* for tpeekEvent() which doesn't update the context.
	102	*
	103	* @return the next event in the stream
	104	*/
	105	public TmfEvent peekEvent(TmfTraceContext context);
	106	public TmfEvent getEvent(TmfTraceContext context, TmfTimestamp timestamp);
	107	public TmfEvent getEvent(TmfTraceContext context, int index);
	108	public TmfEvent getNextEvent(TmfTraceContext context);
	109
	110	/**
	111	* Index the stream and creates the checkpoint structure.
	112	* Normally invoked once at the creation of the event stream.
	113	*/
	114	public void indexStream();
	115
	116	/**
	117	* Returns the index of the first event at the supplied timestamp.
	118	* If there is no such event, return the next one (null if none left).
	119	*
	120	* @param timestamp
	121	* @return
	122	*/
	123	public int getIndex(TmfTimestamp timestamp);
	124
	125	/**
	126	* Returns the timestamp of the event at position [index]
	127	* (null if none left).
	128	*
	129	* @param index the event index
	130	* @return the corresponding timestamp
	131	*/
	132	public TmfTimestamp getTimestamp(int index);
	133	}