1 /*******************************************************************************
2 * Copyright (c) 2012 Ericsson
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
10 * Francois Chouinard - Initial API and implementation
11 *******************************************************************************/
13 package org
.eclipse
.linuxtools
.tmf
.core
.event
;
16 * The fundamental time reference in the TMF.
18 * It defines a generic timestamp interface in its most basic form:
20 * <li>timestamp = [value] * 10**[scale] +/- [precision]
24 * <li>[value] is an unstructured integer value
25 * <li>[scale] is the magnitude of the value wrt some application-specific
26 * base unit (e.g. the second)
27 * <li>[precision] indicates the error on the value (useful for comparing
28 * timestamps in different scales). Default: 0.
32 * @author Francois Chouinard
37 public interface ITmfTimestamp
extends Comparable
<ITmfTimestamp
> {
39 // ------------------------------------------------------------------------
41 // ------------------------------------------------------------------------
44 * The millisecond scale factor (10e0)
47 public static final int SECOND_SCALE
= 0;
50 * The millisecond scale factor (10e-3)
53 public static final int MILLISECOND_SCALE
= -3;
56 * The microsecond scale factor (10e-6)
59 public static final int MICROSECOND_SCALE
= -6;
62 * The nanosecond scale factor (10e-9)
65 public static final int NANOSECOND_SCALE
= -9;
67 // ------------------------------------------------------------------------
69 // ------------------------------------------------------------------------
72 * @return the timestamp value (magnitude)
74 public long getValue();
77 * @return the timestamp scale (exponent)
79 public int getScale();
82 * @return the timestamp precision (measurement tolerance)
84 public int getPrecision();
86 // ------------------------------------------------------------------------
88 // ------------------------------------------------------------------------
91 * Normalize (adjust scale and offset) of the timestamp
93 * @param offset the offset to apply to the timestamp value (after scaling)
94 * @param scale the new timestamp scale
95 * @return a new 'adjusted' ITmfTimestamp
97 public ITmfTimestamp
normalize(long offset
, int scale
);
100 * Compares [this] and [ts] within timestamp precision
102 * @param ts the other timestamp
103 * @param withinPrecision consider the precision when testing for equality
104 * @return -1, 0 or 1 (less than, equals, greater than)
106 public int compareTo(ITmfTimestamp ts
, boolean withinPrecision
);
109 * Returns the difference between [this] and [ts] as a timestamp
111 * @param ts the other timestamp
112 * @return the time difference (this - other) as an ITmfTimestamp
114 public ITmfTimestamp
getDelta(ITmfTimestamp ts
);
117 * @return a clone of the timestamp
119 public ITmfTimestamp
clone();
121 // ------------------------------------------------------------------------
123 // ------------------------------------------------------------------------
126 * @see java.lang.Comparable#compareTo(java.lang.Object)
129 int compareTo(ITmfTimestamp ts
);
132 * Format the timestamp as per the format provided
134 * @param format the timestamp formatter
135 * @return the formatted timestamp
138 public String
toString(final TmfTimestampFormat format
);