001 package org.apache.commons.net.ntp;
002 /*
003 * Licensed to the Apache Software Foundation (ASF) under one or more
004 * contributor license agreements. See the NOTICE file distributed with
005 * this work for additional information regarding copyright ownership.
006 * The ASF licenses this file to You under the Apache License, Version 2.0
007 * (the "License"); you may not use this file except in compliance with
008 * the License. You may obtain a copy of the License at
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018
019
020
021 import java.text.DateFormat;
022 import java.text.SimpleDateFormat;
023 import java.util.Date;
024 import java.util.Locale;
025 import java.util.TimeZone;
026
027 /***
028 * TimeStamp class represents the Network Time Protocol (NTP) timestamp
029 * as defined in RFC-1305 and SNTP (RFC-2030). It is represented as a
030 * 64-bit unsigned fixed-point number in seconds relative to 0-hour on 1-January-1900.
031 * The 32-bit low-order bits are the fractional seconds whose precision is
032 * about 200 picoseconds. Assumes overflow date when date passes MAX_LONG
033 * and reverts back to 0 is 2036 and not 1900. Test for most significant
034 * bit: if MSB=0 then 2036 basis is used otherwise 1900 if MSB=1.
035 * <p>
036 * Methods exist to convert NTP timestamps to and from the equivalent Java date
037 * representation, which is the number of milliseconds since the standard base
038 * time known as "the epoch", namely January 1, 1970, 00:00:00 GMT.
039 * </p>
040 *
041 * @author Jason Mathews, MITRE Corp
042 * @version $Revision: 1299238 $
043 * @see java.util.Date
044 */
045 public class TimeStamp implements java.io.Serializable, Comparable<TimeStamp>
046 {
047 private static final long serialVersionUID = 8139806907588338737L;
048
049 /**
050 * baseline NTP time if bit-0=0 -> 7-Feb-2036 @ 06:28:16 UTC
051 */
052 protected static final long msb0baseTime = 2085978496000L;
053
054 /**
055 * baseline NTP time if bit-0=1 -> 1-Jan-1900 @ 01:00:00 UTC
056 */
057 protected static final long msb1baseTime = -2208988800000L;
058
059 /**
060 * Default NTP date string format. E.g. Fri, Sep 12 2003 21:06:23.860.
061 * See <code>java.text.SimpleDateFormat</code> for code descriptions.
062 */
063 public final static String NTP_DATE_FORMAT = "EEE, MMM dd yyyy HH:mm:ss.SSS";
064
065 /**
066 * NTP timestamp value: 64-bit unsigned fixed-point number as defined in RFC-1305
067 * with high-order 32 bits the seconds field and the low-order 32-bits the
068 * fractional field.
069 */
070 private final long ntpTime;
071
072 private DateFormat simpleFormatter;
073 private DateFormat utcFormatter;
074
075 // initialization of static time bases
076 /*
077 static {
078 TimeZone utcZone = TimeZone.getTimeZone("UTC");
079 Calendar calendar = Calendar.getInstance(utcZone);
080 calendar.set(1900, Calendar.JANUARY, 1, 0, 0, 0);
081 calendar.set(Calendar.MILLISECOND, 0);
082 msb1baseTime = calendar.getTime().getTime();
083 calendar.set(2036, Calendar.FEBRUARY, 7, 6, 28, 16);
084 calendar.set(Calendar.MILLISECOND, 0);
085 msb0baseTime = calendar.getTime().getTime();
086 }
087 */
088
089 /***
090 * Constructs a newly allocated NTP timestamp object
091 * that represents the native 64-bit long argument.
092 */
093 public TimeStamp(long ntpTime)
094 {
095 this.ntpTime = ntpTime;
096 }
097
098 /***
099 * Constructs a newly allocated NTP timestamp object
100 * that represents the value represented by the string
101 * in hexdecimal form (e.g. "c1a089bd.fc904f6d").
102 *
103 * @throws NumberFormatException - if the string does not contain a parsable timestamp.
104 */
105 public TimeStamp(String s) throws NumberFormatException
106 {
107 ntpTime = decodeNtpHexString(s);
108 }
109
110 /***
111 * Constructs a newly allocated NTP timestamp object
112 * that represents the Java Date argument.
113 *
114 * @param d - the Date to be represented by the Timestamp object.
115 */
116 public TimeStamp(Date d)
117 {
118 ntpTime = (d == null) ? 0 : toNtpTime(d.getTime());
119 }
120
121 /***
122 * Returns the value of this Timestamp as a long value.
123 *
124 * @return the 64-bit long value represented by this object.
125 */
126 public long ntpValue()
127 {
128 return ntpTime;
129 }
130
131 /***
132 * Returns high-order 32-bits representing the seconds of this NTP timestamp.
133 *
134 * @return seconds represented by this NTP timestamp.
135 */
136 public long getSeconds()
137 {
138 return (ntpTime >>> 32) & 0xffffffffL;
139 }
140
141 /***
142 * Returns low-order 32-bits representing the fractional seconds.
143 *
144 * @return fractional seconds represented by this NTP timestamp.
145 */
146 public long getFraction()
147 {
148 return ntpTime & 0xffffffffL;
149 }
150
151 /***
152 * Convert NTP timestamp to Java standard time.
153 *
154 * @return NTP Timestamp in Java time
155 */
156 public long getTime()
157 {
158 return getTime(ntpTime);
159 }
160
161 /***
162 * Convert NTP timestamp to Java Date object.
163 *
164 * @return NTP Timestamp in Java Date
165 */
166 public Date getDate()
167 {
168 long time = getTime(ntpTime);
169 return new Date(time);
170 }
171
172 /***
173 * Convert 64-bit NTP timestamp to Java standard time.
174 *
175 * Note that java time (milliseconds) by definition has less precision
176 * then NTP time (picoseconds) so converting NTP timestamp to java time and back
177 * to NTP timestamp loses precision. For example, Tue, Dec 17 2002 09:07:24.810 EST
178 * is represented by a single Java-based time value of f22cd1fc8a, but its
179 * NTP equivalent are all values ranging from c1a9ae1c.cf5c28f5 to c1a9ae1c.cf9db22c.
180 *
181 * @param ntpTimeValue
182 * @return the number of milliseconds since January 1, 1970, 00:00:00 GMT
183 * represented by this NTP timestamp value.
184 */
185 public static long getTime(long ntpTimeValue)
186 {
187 long seconds = (ntpTimeValue >>> 32) & 0xffffffffL; // high-order 32-bits
188 long fraction = ntpTimeValue & 0xffffffffL; // low-order 32-bits
189
190 // Use round-off on fractional part to preserve going to lower precision
191 fraction = Math.round(1000D * fraction / 0x100000000L);
192
193 /*
194 * If the most significant bit (MSB) on the seconds field is set we use
195 * a different time base. The following text is a quote from RFC-2030 (SNTP v4):
196 *
197 * If bit 0 is set, the UTC time is in the range 1968-2036 and UTC time
198 * is reckoned from 0h 0m 0s UTC on 1 January 1900. If bit 0 is not set,
199 * the time is in the range 2036-2104 and UTC time is reckoned from
200 * 6h 28m 16s UTC on 7 February 2036.
201 */
202 long msb = seconds & 0x80000000L;
203 if (msb == 0) {
204 // use base: 7-Feb-2036 @ 06:28:16 UTC
205 return msb0baseTime + (seconds * 1000) + fraction;
206 } else {
207 // use base: 1-Jan-1900 @ 01:00:00 UTC
208 return msb1baseTime + (seconds * 1000) + fraction;
209 }
210 }
211
212 /***
213 * Helper method to convert Java time to NTP timestamp object.
214 * Note that Java time (milliseconds) by definition has less precision
215 * then NTP time (picoseconds) so converting Ntptime to Javatime and back
216 * to Ntptime loses precision. For example, Tue, Dec 17 2002 09:07:24.810
217 * is represented by a single Java-based time value of f22cd1fc8a, but its
218 * NTP equivalent are all values from c1a9ae1c.cf5c28f5 to c1a9ae1c.cf9db22c.
219 * @param date the milliseconds since January 1, 1970, 00:00:00 GMT.
220 * @return NTP timestamp object at the specified date.
221 */
222 public static TimeStamp getNtpTime(long date)
223 {
224 return new TimeStamp(toNtpTime(date));
225 }
226
227 /***
228 * Constructs a NTP timestamp object and initializes it so that
229 * it represents the time at which it was allocated, measured to the
230 * nearest millisecond.
231 * @return NTP timestamp object set to the current time.
232 * @see java.lang.System#currentTimeMillis()
233 */
234 public static TimeStamp getCurrentTime()
235 {
236 return getNtpTime(System.currentTimeMillis());
237 }
238
239 /***
240 * Convert NTP timestamp hexstring (e.g. "c1a089bd.fc904f6d") to the NTP
241 * 64-bit unsigned fixed-point number.
242 *
243 * @return NTP 64-bit timestamp value.
244 * @throws NumberFormatException - if the string does not contain a parsable timestamp.
245 */
246 protected static long decodeNtpHexString(String s)
247 throws NumberFormatException
248 {
249 if (s == null) {
250 throw new NumberFormatException("null");
251 }
252 int ind = s.indexOf('.');
253 if (ind == -1) {
254 if (s.length() == 0) {
255 return 0;
256 }
257 return Long.parseLong(s, 16) << 32; // no decimal
258 }
259
260 return Long.parseLong(s.substring(0, ind), 16) << 32 |
261 Long.parseLong(s.substring(ind + 1), 16);
262 }
263
264 /***
265 * Parses the string argument as a NTP hexidecimal timestamp representation string
266 * (e.g. "c1a089bd.fc904f6d").
267 *
268 * @param s - hexstring.
269 * @return the Timestamp represented by the argument in hexidecimal.
270 * @throws NumberFormatException - if the string does not contain a parsable timestamp.
271 */
272 public static TimeStamp parseNtpString(String s)
273 throws NumberFormatException
274 {
275 return new TimeStamp(decodeNtpHexString(s));
276 }
277
278 /***
279 * Converts Java time to 64-bit NTP time representation.
280 *
281 * @param t Java time
282 * @return NTP timestamp representation of Java time value.
283 */
284 protected static long toNtpTime(long t)
285 {
286 boolean useBase1 = t < msb0baseTime; // time < Feb-2036
287 long baseTime;
288 if (useBase1) {
289 baseTime = t - msb1baseTime; // dates <= Feb-2036
290 } else {
291 // if base0 needed for dates >= Feb-2036
292 baseTime = t - msb0baseTime;
293 }
294
295 long seconds = baseTime / 1000;
296 long fraction = ((baseTime % 1000) * 0x100000000L) / 1000;
297
298 if (useBase1) {
299 seconds |= 0x80000000L; // set high-order bit if msb1baseTime 1900 used
300 }
301
302 long time = seconds << 32 | fraction;
303 return time;
304 }
305
306 /***
307 * Computes a hashcode for this Timestamp. The result is the exclusive
308 * OR of the two halves of the primitive <code>long</code> value
309 * represented by this <code>TimeStamp</code> object. That is, the hashcode
310 * is the value of the expression:
311 * <blockquote><pre>
312 * (int)(this.ntpValue()^(this.ntpValue() >>> 32))
313 * </pre></blockquote>
314 *
315 * @return a hash code value for this object.
316 */
317 @Override
318 public int hashCode()
319 {
320 return (int) (ntpTime ^ (ntpTime >>> 32));
321 }
322
323 /***
324 * Compares this object against the specified object.
325 * The result is <code>true</code> if and only if the argument is
326 * not <code>null</code> and is a <code>Long</code> object that
327 * contains the same <code>long</code> value as this object.
328 *
329 * @param obj the object to compare with.
330 * @return <code>true</code> if the objects are the same;
331 * <code>false</code> otherwise.
332 */
333 @Override
334 public boolean equals(Object obj)
335 {
336 if (obj instanceof TimeStamp) {
337 return ntpTime == ((TimeStamp) obj).ntpValue();
338 }
339 return false;
340 }
341
342 /***
343 * Converts this <code>TimeStamp</code> object to a <code>String</code>.
344 * The NTP timestamp 64-bit long value is represented as hex string with
345 * seconds separated by fractional seconds by a decimal point;
346 * e.g. c1a089bd.fc904f6d <=> Tue, Dec 10 2002 10:41:49.986
347 *
348 * @return NTP timestamp 64-bit long value as hex string with seconds
349 * separated by fractional seconds.
350 */
351 @Override
352 public String toString()
353 {
354 return toString(ntpTime);
355 }
356
357 /***
358 * Left-pad 8-character hex string with 0's
359 *
360 * @param buf - StringBuilder which is appended with leading 0's.
361 * @param l - a long.
362 */
363 private static void appendHexString(StringBuilder buf, long l)
364 {
365 String s = Long.toHexString(l);
366 for (int i = s.length(); i < 8; i++) {
367 buf.append('0');
368 }
369 buf.append(s);
370 }
371
372 /***
373 * Converts 64-bit NTP timestamp value to a <code>String</code>.
374 * The NTP timestamp value is represented as hex string with
375 * seconds separated by fractional seconds by a decimal point;
376 * e.g. c1a089bd.fc904f6d <=> Tue, Dec 10 2002 10:41:49.986
377 *
378 * @return NTP timestamp 64-bit long value as hex string with seconds
379 * separated by fractional seconds.
380 */
381 public static String toString(long ntpTime)
382 {
383 StringBuilder buf = new StringBuilder();
384 // high-order second bits (32..63) as hexstring
385 appendHexString(buf, (ntpTime >>> 32) & 0xffffffffL);
386
387 // low-order fractional seconds bits (0..31) as hexstring
388 buf.append('.');
389 appendHexString(buf, ntpTime & 0xffffffffL);
390
391 return buf.toString();
392 }
393
394 /***
395 * Converts this <code>TimeStamp</code> object to a <code>String</code>
396 * of the form:
397 * <blockquote><pre>
398 * EEE, MMM dd yyyy HH:mm:ss.SSS</pre></blockquote>
399 * See java.text.SimpleDataFormat for code descriptions.
400 *
401 * @return a string representation of this date.
402 */
403 public String toDateString()
404 {
405 if (simpleFormatter == null) {
406 simpleFormatter = new SimpleDateFormat(NTP_DATE_FORMAT, Locale.US);
407 simpleFormatter.setTimeZone(TimeZone.getDefault());
408 }
409 Date ntpDate = getDate();
410 return simpleFormatter.format(ntpDate);
411 }
412
413 /***
414 * Converts this <code>TimeStamp</code> object to a <code>String</code>
415 * of the form:
416 * <blockquote><pre>
417 * EEE, MMM dd yyyy HH:mm:ss.SSS UTC</pre></blockquote>
418 * See java.text.SimpleDataFormat for code descriptions.
419 *
420 * @return a string representation of this date in UTC.
421 */
422 public String toUTCString()
423 {
424 if (utcFormatter == null) {
425 utcFormatter = new SimpleDateFormat(NTP_DATE_FORMAT + " 'UTC'",
426 Locale.US);
427 utcFormatter.setTimeZone(TimeZone.getTimeZone("UTC"));
428 }
429 Date ntpDate = getDate();
430 return utcFormatter.format(ntpDate);
431 }
432
433 /***
434 * Compares two Timestamps numerically.
435 *
436 * @param anotherTimeStamp - the <code>TimeStamp</code> to be compared.
437 * @return the value <code>0</code> if the argument TimeStamp is equal to
438 * this TimeStamp; a value less than <code>0</code> if this TimeStamp
439 * is numerically less than the TimeStamp argument; and a
440 * value greater than <code>0</code> if this TimeStamp is
441 * numerically greater than the TimeStamp argument
442 * (signed comparison).
443 */
444 public int compareTo(TimeStamp anotherTimeStamp)
445 {
446 long thisVal = this.ntpTime;
447 long anotherVal = anotherTimeStamp.ntpTime;
448 return (thisVal < anotherVal ? -1 : (thisVal == anotherVal ? 0 : 1));
449 }
450
451 }