org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/timestamp/ITmfTimestamp.java

   1 /*******************************************************************************
   2  * Copyright (c) 2012, 2013 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.core.timestamp;
  14
  15 import org.eclipse.linuxtools.tmf.core.event.ITmfEvent;
  16
  17 /**
  18  * The fundamental time reference in the TMF.
  19  * <p>
  20  * It defines a generic timestamp interface in its most basic form:
  21  * <ul>
  22  * <li>timestamp = [value] * 10**[scale] +/- [precision]
  23  * </ul>
  24  * Where:
  25  * <ul>
  26  * <li>[value] is an unstructured integer value
  27  * <li>[scale] is the magnitude of the value wrt some application-specific
  28  * base unit (e.g. the second)
  29  * <li>[precision] indicates the error on the value (useful for comparing
  30  * timestamps in different scales). Default: 0.
  31  * </ul>
  32  *
  33  * @author Francois Chouinard
  34  * @version 2.0
  35  * @since 2.0
  36  *
  37  * @see ITmfEvent
  38  * @see TmfTimeRange
  39  */
  40 public interface ITmfTimestamp extends Comparable<ITmfTimestamp> {
  41
  42     // ------------------------------------------------------------------------
  43     // Constants
  44     // ------------------------------------------------------------------------
  45
  46     /**
  47      * The millisecond scale factor (10e0)
  48      */
  49     public static final int SECOND_SCALE = 0;
  50
  51     /**
  52      * The millisecond scale factor (10e-3)
  53      */
  54     public static final int MILLISECOND_SCALE = -3;
  55
  56     /**
  57      * The microsecond scale factor (10e-6)
  58      */
  59     public static final int MICROSECOND_SCALE = -6;
  60
  61     /**
  62      * The nanosecond scale factor (10e-9)
  63      */
  64     public static final int NANOSECOND_SCALE = -9;
  65
  66     // ------------------------------------------------------------------------
  67     // Getters
  68     // ------------------------------------------------------------------------
  69
  70     /**
  71      * @return the timestamp value (magnitude)
  72      */
  73     long getValue();
  74
  75     /**
  76      * @return the timestamp scale (exponent)
  77      */
  78     int getScale();
  79
  80     /**
  81      * @return the timestamp precision (measurement tolerance)
  82      */
  83     int getPrecision();
  84
  85     // ------------------------------------------------------------------------
  86     // Operations
  87     // ------------------------------------------------------------------------
  88
  89     /**
  90      * Normalize (adjust scale and offset) of the timestamp
  91      *
  92      * @param offset the offset to apply to the timestamp value (after scaling)
  93      * @param scale the new timestamp scale
  94      * @return a new 'adjusted' ITmfTimestamp
  95      */
  96     ITmfTimestamp normalize(long offset, int scale);
  97
  98     /**
  99      * Compares [this] and [ts] within timestamp precision
 100      *
 101      * @param ts the other timestamp
 102      * @param withinPrecision consider the precision when testing for equality
 103      * @return -1, 0 or 1 (less than, equals, greater than)
 104      */
 105     int compareTo(ITmfTimestamp ts, boolean withinPrecision);
 106
 107     /**
 108      * Returns the difference between [this] and [ts] as a timestamp
 109      *
 110      * @param ts the other timestamp
 111      * @return the time difference (this - other) as an ITmfTimestamp
 112      */
 113     ITmfTimestamp getDelta(ITmfTimestamp ts);
 114
 115     /**
 116      * Returns if this timestamp intersects the given time range. Borders are
 117      * inclusive (for more fine-grained behavior, you can use
 118      * {@link #compareTo(ITmfTimestamp)}.
 119      *
 120      * @param range
 121      *            The time range to compare to
 122      * @return True if this timestamp is part of the time range, false if not
 123      */
 124     boolean intersects(TmfTimeRange range);
 125
 126     // ------------------------------------------------------------------------
 127     // Comparable
 128     // ------------------------------------------------------------------------
 129
 130     @Override
 131     int compareTo(ITmfTimestamp ts);
 132
 133     /**
 134      * Format the timestamp as per the format provided
 135      *
 136      * @param format the timestamp formatter
 137      * @return the formatted timestamp
 138      * @since 2.0
 139      */
 140     String toString(final TmfTimestampFormat format);
 141
 142 }