- * This is a place-holder for the context objects. + * The basic trace context structure in TMF. The purpose of the context is to + * associate a trace location to an event of a specific rank (order). + *
+ * The context should be sufficient to allow the trace to position itself so + * that performing a trace read operation will yield the corresponding event. */ public interface ITmfContext extends Cloneable { - public long UNKNOWN_RANK = -2L; + // ------------------------------------------------------------------------ + // Constants + // ------------------------------------------------------------------------ + + /** + * The initial context event rank, before anything is read from the trace + */ public long INITIAL_RANK = -1L; - public void dispose(); + /** + * The unknown event rank + */ + public long UNKNOWN_RANK = -2L; + + // ------------------------------------------------------------------------ + // Getters + // ------------------------------------------------------------------------ - public void setLocation(ITmfLocation location); + /** + * @return the rank of the event referred to by the context + */ + public long getRank(); + + /** + * @return the location of the event referred to by the context + */ + public ITmfLocation> getLocation(); + + /** + * @return indicates if the context rank is valid (!= UNKNOWN_RANK) + */ + public boolean hasValidRank(); - @SuppressWarnings("rawtypes") - public ITmfLocation getLocation(); + // ------------------------------------------------------------------------ + // Operations + // ------------------------------------------------------------------------ + /** + * @param location the new location + */ + public void setLocation(ITmfLocation> location); + + /** + * @param rank the new rank + */ public void setRank(long rank); - public long getRank(); + /** + * Increment the context rank + */ + public void increaseRank(); - public void updateRank(int rank); + /** + * Cleanup hook + */ + public void dispose(); - public boolean isValidRank(); + // ------------------------------------------------------------------------ + // Cloneable + // ------------------------------------------------------------------------ + /** + * @return a clone of the context + */ public ITmfContext clone(); }