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(final 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(final 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(final 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 final 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(final long ntpTimeValue) 186 { 187 final 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 final 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 } 207 // use base: 1-Jan-1900 @ 01:00:00 UTC 208 return msb1baseTime + (seconds * 1000) + fraction; 209 } 210 211 /*** 212 * Helper method to convert Java time to NTP timestamp object. 213 * Note that Java time (milliseconds) by definition has less precision 214 * then NTP time (picoseconds) so converting Ntptime to Javatime and back 215 * to Ntptime loses precision. For example, Tue, Dec 17 2002 09:07:24.810 216 * is represented by a single Java-based time value of f22cd1fc8a, but its 217 * NTP equivalent are all values from c1a9ae1c.cf5c28f5 to c1a9ae1c.cf9db22c. 218 * @param date the milliseconds since January 1, 1970, 00:00:00 GMT. 219 * @return NTP timestamp object at the specified date. 220 */ 221 public static TimeStamp getNtpTime(final long date) 222 { 223 return new TimeStamp(toNtpTime(date)); 224 } 225 226 /*** 227 * Constructs a NTP timestamp object and initializes it so that 228 * it represents the time at which it was allocated, measured to the 229 * nearest millisecond. 230 * @return NTP timestamp object set to the current time. 231 * @see java.lang.System#currentTimeMillis() 232 */ 233 public static TimeStamp getCurrentTime() 234 { 235 return getNtpTime(System.currentTimeMillis()); 236 } 237 238 /*** 239 * Convert NTP timestamp hexstring (e.g. "c1a089bd.fc904f6d") to the NTP 240 * 64-bit unsigned fixed-point number. 241 * @param hexString the string to convert 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(final String hexString) 247 throws NumberFormatException 248 { 249 if (hexString == null) { 250 throw new NumberFormatException("null"); 251 } 252 final int ind = hexString.indexOf('.'); 253 if (ind == -1) { 254 if (hexString.length() == 0) { 255 return 0; 256 } 257 return Long.parseLong(hexString, 16) << 32; // no decimal 258 } 259 260 return Long.parseLong(hexString.substring(0, ind), 16) << 32 | 261 Long.parseLong(hexString.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(final 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(final long t) 285 { 286 final 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 final long fraction = ((baseTime % 1000) * 0x100000000L) / 1000; 297 298 if (useBase1) { 299 seconds |= 0x80000000L; // set high-order bit if msb1baseTime 1900 used 300 } 301 302 final 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 * {@code (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(final 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(final StringBuilder buf, final long l) 364 { 365 final 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 * @param ntpTime the 64 bit timestamp 378 * 379 * @return NTP timestamp 64-bit long value as hex string with seconds 380 * separated by fractional seconds. 381 */ 382 public static String toString(final long ntpTime) 383 { 384 final StringBuilder buf = new StringBuilder(); 385 // high-order second bits (32..63) as hexstring 386 appendHexString(buf, (ntpTime >>> 32) & 0xffffffffL); 387 388 // low-order fractional seconds bits (0..31) as hexstring 389 buf.append('.'); 390 appendHexString(buf, ntpTime & 0xffffffffL); 391 392 return buf.toString(); 393 } 394 395 /*** 396 * Converts this <code>TimeStamp</code> object to a <code>String</code> 397 * of the form: 398 * <blockquote><pre> 399 * EEE, MMM dd yyyy HH:mm:ss.SSS</pre></blockquote> 400 * See java.text.SimpleDataFormat for code descriptions. 401 * 402 * @return a string representation of this date. 403 */ 404 public String toDateString() 405 { 406 if (simpleFormatter == null) { 407 simpleFormatter = new SimpleDateFormat(NTP_DATE_FORMAT, Locale.US); 408 simpleFormatter.setTimeZone(TimeZone.getDefault()); 409 } 410 final Date ntpDate = getDate(); 411 return simpleFormatter.format(ntpDate); 412 } 413 414 /*** 415 * Converts this <code>TimeStamp</code> object to a <code>String</code> 416 * of the form: 417 * <blockquote><pre> 418 * EEE, MMM dd yyyy HH:mm:ss.SSS UTC</pre></blockquote> 419 * See java.text.SimpleDataFormat for code descriptions. 420 * 421 * @return a string representation of this date in UTC. 422 */ 423 public String toUTCString() 424 { 425 if (utcFormatter == null) { 426 utcFormatter = new SimpleDateFormat(NTP_DATE_FORMAT + " 'UTC'", 427 Locale.US); 428 utcFormatter.setTimeZone(TimeZone.getTimeZone("UTC")); 429 } 430 final Date ntpDate = getDate(); 431 return utcFormatter.format(ntpDate); 432 } 433 434 /*** 435 * Compares two Timestamps numerically. 436 * 437 * @param anotherTimeStamp - the <code>TimeStamp</code> to be compared. 438 * @return the value <code>0</code> if the argument TimeStamp is equal to 439 * this TimeStamp; a value less than <code>0</code> if this TimeStamp 440 * is numerically less than the TimeStamp argument; and a 441 * value greater than <code>0</code> if this TimeStamp is 442 * numerically greater than the TimeStamp argument 443 * (signed comparison). 444 */ 445 @Override 446 public int compareTo(final TimeStamp anotherTimeStamp) 447 { 448 final long thisVal = this.ntpTime; 449 final long anotherVal = anotherTimeStamp.ntpTime; 450 return (thisVal < anotherVal ? -1 : (thisVal == anotherVal ? 0 : 1)); 451 } 452 453}