[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.component.ITmfComponent;
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>
 */
public interface ITmfTrace extends ITmfComponent {
	
	public ITmfTrace createTraceCopy();
	
	/**
	 * @return the trace path 
	 */
	public String getPath();
    
	/**
	 * @return the trace name 
	 */
	@Override
	public String getName();

    /**
     * @return the cache size 
     */
    public int getCacheSize();

	/**
	 * @return the number of events in the trace
	 */
	public long getNbEvents();
    
	/**
	 * Trace time range accessors
	 */
	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).
     * 
     * Returns a context which can later be used to read the event.
     * 
     * @param data.timestamp
     * @param data.index
     * @return a context object for subsequent reads
     */
    public TmfContext seekLocation(ITmfLocation<?> location);
    public TmfContext seekEvent(TmfTimestamp timestamp);
    public TmfContext seekEvent(long rank);

    /**
     * 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
     */
    public long getRank(TmfTimestamp timestamp);
    
    /**
     * 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
     */
    public TmfEvent getNextEvent(TmfContext context);

    /**
     * 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
     */
    public TmfEvent parseEvent(TmfContext context);

}
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.component.ITmfComponent;
	16	import org.eclipse.linuxtools.tmf.event.TmfEvent;
	17	import org.eclipse.linuxtools.tmf.event.TmfTimeRange;
	18	import org.eclipse.linuxtools.tmf.event.TmfTimestamp;
	19
	20	/**
	21	* <b><u>ITmfTrace</u></b>
	22	* <p>
	23	*/
	24	public interface ITmfTrace extends ITmfComponent {
	25
	26	public ITmfTrace createTraceCopy();
	27
	28	/**
	29	* @return the trace path
	30	*/
	31	public String getPath();
	32
	33	/**
	34	* @return the trace name
	35	*/
	36	@Override
	37	public String getName();
	38
	39	/**
	40	* @return the cache size
	41	*/
	42	public int getCacheSize();
	43
	44	/**
	45	* @return the number of events in the trace
	46	*/
	47	public long getNbEvents();
	48
	49	/**
	50	* Trace time range accessors
	51	*/
	52	public TmfTimeRange getTimeRange();
	53	public TmfTimestamp getStartTime();
	54	public TmfTimestamp getEndTime();
	55
	56	/**
	57	* Positions the trace at the first event with the specified
	58	* timestamp or index (i.e. the nth event in the trace).
	59	*
	60	* Returns a context which can later be used to read the event.
	61	*
	62	* @param data.timestamp
	63	* @param data.index
	64	* @return a context object for subsequent reads
	65	*/
	66	public TmfContext seekLocation(ITmfLocation<?> location);
	67	public TmfContext seekEvent(TmfTimestamp timestamp);
	68	public TmfContext seekEvent(long rank);
	69
	70	/**
	71	* Returns the rank of the first event with the requested timestamp.
	72	* If none, returns the index of the next event (if any).
	73	*
	74	* @param timestamp
	75	* @return
	76	*/
	77	public long getRank(TmfTimestamp timestamp);
	78
	79	/**
	80	* Return the event pointed by the supplied context (or null if
	81	* no event left) and updates the context to the next event.
	82	*
	83	* @return the next event in the stream
	84	*/
	85	public TmfEvent getNextEvent(TmfContext context);
	86
	87	/**
	88	* Return the event pointed by the supplied context (or null if
	89	* no event left) and does not update the context.
	90	*
	91	* @return the next event in the stream
	92	*/
	93	public TmfEvent parseEvent(TmfContext context);
	94
	95	}