/*******************************************************************************
- * Copyright (c) 2009, 2010 Ericsson
- *
+ * Copyright (c) 2009, 2013 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
+ * Francois Chouinard - Updated as per TMF Trace Model 1.0
+ * Patrick Tasse - Updated for removal of context clone
*******************************************************************************/
package org.eclipse.linuxtools.tmf.core.trace;
+import org.eclipse.linuxtools.tmf.core.trace.location.ITmfLocation;
+
/**
- * <b><u>ITmfContext</u></b>
+ * The basic trace context structure in TMF. The purpose of the context is to
+ * associate a trace location to an event at a specific rank (order).
* <p>
- * This is a place-holder for the context objects.
+ * The context should be sufficient to allow the trace to position itself so
+ * that performing a trace read operation will yield the corresponding 'nth'
+ * event.
+ *
+ * @version 1.0
+ * @author Francois Chouinard
+ *
+ * @see ITmfLocation
*/
-public interface ITmfContext extends Cloneable {
+public interface ITmfContext {
+
+ // ------------------------------------------------------------------------
+ // Constants
+ // ------------------------------------------------------------------------
+
+ /**
+ * The unknown event rank
+ */
+ public long UNKNOWN_RANK = -1L;
- public long UNKNOWN_RANK = -2L;
- public long INITIAL_RANK = -1L;
+ // ------------------------------------------------------------------------
+ // Getters
+ // ------------------------------------------------------------------------
- public void dispose();
+ /**
+ * @return the rank of the event at the context location
+ */
+ long getRank();
- public void setLocation(ITmfLocation<?> location);
+ /**
+ * @return the location of the event at the context rank
+ * @since 3.0
+ */
+ ITmfLocation getLocation();
- @SuppressWarnings("rawtypes")
- public ITmfLocation<? extends Comparable> getLocation();
+ /**
+ * @return indicates if the context rank is valid (!= UNKNOWN_RANK)
+ */
+ boolean hasValidRank();
- public void setRank(long rank);
+ // ------------------------------------------------------------------------
+ // Operations
+ // ------------------------------------------------------------------------
- public long getRank();
+ /**
+ * @param location the new location
+ * @since 3.0
+ */
+ void setLocation(ITmfLocation location);
- public void updateRank(int rank);
+ /**
+ * @param rank the new rank
+ */
+ void setRank(long rank);
- public boolean isValidRank();
+ /**
+ * Increment the context rank
+ */
+ void increaseRank();
- public ITmfContext clone();
+ /**
+ * Cleanup hook
+ */
+ void dispose();
}