001package 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 021import java.text.DateFormat; 022import java.text.SimpleDateFormat; 023import java.util.Date; 024import java.util.Locale; 025import 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 * @see java.util.Date 042 */ 043public class TimeStamp implements java.io.Serializable, Comparable<TimeStamp> 044{ 045 private static final long serialVersionUID = 8139806907588338737L; 046 047 /** 048 * baseline NTP time if bit-0=0 is 7-Feb-2036 @ 06:28:16 UTC 049 */ 050 protected static final long msb0baseTime = 2085978496000L; 051 052 /** 053 * baseline NTP time if bit-0=1 is 1-Jan-1900 @ 01:00:00 UTC 054 */ 055 protected static final long msb1baseTime = -2208988800000L; 056 057 /** 058 * Default NTP date string format. E.g. Fri, Sep 12 2003 21:06:23.860. 059 * See <code>java.text.SimpleDateFormat</code> for code descriptions. 060 */ 061 public static final String NTP_DATE_FORMAT = "EEE, MMM dd yyyy HH:mm:ss.SSS"; 062 063 /** 064 * NTP timestamp value: 64-bit unsigned fixed-point number as defined in RFC-1305 065 * with high-order 32 bits the seconds field and the low-order 32-bits the 066 * fractional field. 067 */ 068 private final long ntpTime; 069 070 private DateFormat simpleFormatter; 071 private DateFormat utcFormatter; 072 073 // initialization of static time bases 074 /* 075 static { 076 TimeZone utcZone = TimeZone.getTimeZone("UTC"); 077 Calendar calendar = Calendar.getInstance(utcZone); 078 calendar.set(1900, Calendar.JANUARY, 1, 0, 0, 0); 079 calendar.set(Calendar.MILLISECOND, 0); 080 msb1baseTime = calendar.getTime().getTime(); 081 calendar.set(2036, Calendar.FEBRUARY, 7, 6, 28, 16); 082 calendar.set(Calendar.MILLISECOND, 0); 083 msb0baseTime = calendar.getTime().getTime(); 084 } 085 */ 086 087 /*** 088 * Constructs a newly allocated NTP timestamp object 089 * that represents the native 64-bit long argument. 090 * @param ntpTime the timestamp 091 */ 092 public TimeStamp(long ntpTime) 093 { 094 this.ntpTime = ntpTime; 095 } 096 097 /*** 098 * Constructs a newly allocated NTP timestamp object 099 * that represents the value represented by the string 100 * in hexdecimal form (e.g. "c1a089bd.fc904f6d"). 101 * @param hexStamp the hex timestamp 102 * 103 * @throws NumberFormatException - if the string does not contain a parsable timestamp. 104 */ 105 public TimeStamp(String hexStamp) throws NumberFormatException 106 { 107 ntpTime = decodeNtpHexString(hexStamp); 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 the input time 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 * @param hexString the string to convert 243 * 244 * @return NTP 64-bit timestamp value. 245 * @throws NumberFormatException - if the string does not contain a parsable timestamp. 246 */ 247 protected static long decodeNtpHexString(String hexString) 248 throws NumberFormatException 249 { 250 if (hexString == null) { 251 throw new NumberFormatException("null"); 252 } 253 int ind = hexString.indexOf('.'); 254 if (ind == -1) { 255 if (hexString.length() == 0) { 256 return 0; 257 } 258 return Long.parseLong(hexString, 16) << 32; // no decimal 259 } 260 261 return Long.parseLong(hexString.substring(0, ind), 16) << 32 | 262 Long.parseLong(hexString.substring(ind + 1), 16); 263 } 264 265 /*** 266 * Parses the string argument as a NTP hexidecimal timestamp representation string 267 * (e.g. "c1a089bd.fc904f6d"). 268 * 269 * @param s - hexstring. 270 * @return the Timestamp represented by the argument in hexidecimal. 271 * @throws NumberFormatException - if the string does not contain a parsable timestamp. 272 */ 273 public static TimeStamp parseNtpString(String s) 274 throws NumberFormatException 275 { 276 return new TimeStamp(decodeNtpHexString(s)); 277 } 278 279 /*** 280 * Converts Java time to 64-bit NTP time representation. 281 * 282 * @param t Java time 283 * @return NTP timestamp representation of Java time value. 284 */ 285 protected static long toNtpTime(long t) 286 { 287 boolean useBase1 = t < msb0baseTime; // time < Feb-2036 288 long baseTime; 289 if (useBase1) { 290 baseTime = t - msb1baseTime; // dates <= Feb-2036 291 } else { 292 // if base0 needed for dates >= Feb-2036 293 baseTime = t - msb0baseTime; 294 } 295 296 long seconds = baseTime / 1000; 297 long fraction = ((baseTime % 1000) * 0x100000000L) / 1000; 298 299 if (useBase1) { 300 seconds |= 0x80000000L; // set high-order bit if msb1baseTime 1900 used 301 } 302 303 long time = seconds << 32 | fraction; 304 return time; 305 } 306 307 /*** 308 * Computes a hashcode for this Timestamp. The result is the exclusive 309 * OR of the two halves of the primitive <code>long</code> value 310 * represented by this <code>TimeStamp</code> object. That is, the hashcode 311 * is the value of the expression: 312 * <blockquote><pre> 313 * {@code (int)(this.ntpValue()^(this.ntpValue() >>> 32))} 314 * </pre></blockquote> 315 * 316 * @return a hash code value for this object. 317 */ 318 @Override 319 public int hashCode() 320 { 321 return (int) (ntpTime ^ (ntpTime >>> 32)); 322 } 323 324 /*** 325 * Compares this object against the specified object. 326 * The result is <code>true</code> if and only if the argument is 327 * not <code>null</code> and is a <code>Long</code> object that 328 * contains the same <code>long</code> value as this object. 329 * 330 * @param obj the object to compare with. 331 * @return <code>true</code> if the objects are the same; 332 * <code>false</code> otherwise. 333 */ 334 @Override 335 public boolean equals(Object obj) 336 { 337 if (obj instanceof TimeStamp) { 338 return ntpTime == ((TimeStamp) obj).ntpValue(); 339 } 340 return false; 341 } 342 343 /*** 344 * Converts this <code>TimeStamp</code> object to a <code>String</code>. 345 * The NTP timestamp 64-bit long value is represented as hex string with 346 * seconds separated by fractional seconds by a decimal point; 347 * e.g. c1a089bd.fc904f6d == Tue, Dec 10 2002 10:41:49.986 348 * 349 * @return NTP timestamp 64-bit long value as hex string with seconds 350 * separated by fractional seconds. 351 */ 352 @Override 353 public String toString() 354 { 355 return toString(ntpTime); 356 } 357 358 /*** 359 * Left-pad 8-character hex string with 0's 360 * 361 * @param buf - StringBuilder which is appended with leading 0's. 362 * @param l - a long. 363 */ 364 private static void appendHexString(StringBuilder buf, long l) 365 { 366 String s = Long.toHexString(l); 367 for (int i = s.length(); i < 8; i++) { 368 buf.append('0'); 369 } 370 buf.append(s); 371 } 372 373 /*** 374 * Converts 64-bit NTP timestamp value to a <code>String</code>. 375 * The NTP timestamp value is represented as hex string with 376 * seconds separated by fractional seconds by a decimal point; 377 * e.g. c1a089bd.fc904f6d == Tue, Dec 10 2002 10:41:49.986 378 * @param ntpTime the 64 bit timestamp 379 * 380 * @return NTP timestamp 64-bit long value as hex string with seconds 381 * separated by fractional seconds. 382 */ 383 public static String toString(long ntpTime) 384 { 385 StringBuilder buf = new StringBuilder(); 386 // high-order second bits (32..63) as hexstring 387 appendHexString(buf, (ntpTime >>> 32) & 0xffffffffL); 388 389 // low-order fractional seconds bits (0..31) as hexstring 390 buf.append('.'); 391 appendHexString(buf, ntpTime & 0xffffffffL); 392 393 return buf.toString(); 394 } 395 396 /*** 397 * Converts this <code>TimeStamp</code> object to a <code>String</code> 398 * of the form: 399 * <blockquote><pre> 400 * EEE, MMM dd yyyy HH:mm:ss.SSS</pre></blockquote> 401 * See java.text.SimpleDataFormat for code descriptions. 402 * 403 * @return a string representation of this date. 404 */ 405 public String toDateString() 406 { 407 if (simpleFormatter == null) { 408 simpleFormatter = new SimpleDateFormat(NTP_DATE_FORMAT, Locale.US); 409 simpleFormatter.setTimeZone(TimeZone.getDefault()); 410 } 411 Date ntpDate = getDate(); 412 return simpleFormatter.format(ntpDate); 413 } 414 415 /*** 416 * Converts this <code>TimeStamp</code> object to a <code>String</code> 417 * of the form: 418 * <blockquote><pre> 419 * EEE, MMM dd yyyy HH:mm:ss.SSS UTC</pre></blockquote> 420 * See java.text.SimpleDataFormat for code descriptions. 421 * 422 * @return a string representation of this date in UTC. 423 */ 424 public String toUTCString() 425 { 426 if (utcFormatter == null) { 427 utcFormatter = new SimpleDateFormat(NTP_DATE_FORMAT + " 'UTC'", 428 Locale.US); 429 utcFormatter.setTimeZone(TimeZone.getTimeZone("UTC")); 430 } 431 Date ntpDate = getDate(); 432 return utcFormatter.format(ntpDate); 433 } 434 435 /*** 436 * Compares two Timestamps numerically. 437 * 438 * @param anotherTimeStamp - the <code>TimeStamp</code> to be compared. 439 * @return the value <code>0</code> if the argument TimeStamp is equal to 440 * this TimeStamp; a value less than <code>0</code> if this TimeStamp 441 * is numerically less than the TimeStamp argument; and a 442 * value greater than <code>0</code> if this TimeStamp is 443 * numerically greater than the TimeStamp argument 444 * (signed comparison). 445 */ 446 @Override 447 public int compareTo(TimeStamp anotherTimeStamp) 448 { 449 long thisVal = this.ntpTime; 450 long anotherVal = anotherTimeStamp.ntpTime; 451 return (thisVal < anotherVal ? -1 : (thisVal == anotherVal ? 0 : 1)); 452 } 453 454}