View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  
18  package org.apache.commons.net.ntp;
19  
20  import java.io.Serializable;
21  import java.text.DateFormat;
22  import java.text.SimpleDateFormat;
23  import java.util.Date;
24  import java.util.Locale;
25  import java.util.TimeZone;
26  
27  /**
28   * TimeStamp class represents the Network Time Protocol (NTP) timestamp as defined in RFC-1305 and SNTP (RFC-2030). It is represented as a 64-bit unsigned
29   * fixed-point number in seconds relative to 0-hour on 1-January-1900. The 32-bit low-order bits are the fractional seconds whose precision is about 200
30   * picoseconds. Assumes overflow date when date passes MAX_LONG and reverts back to 0 is 2036 and not 1900. Test for most significant bit: if MSB=0 then 2036
31   * basis is used otherwise 1900 if MSB=1.
32   * <p>
33   * Methods exist to convert NTP timestamps to and from the equivalent Java date representation, which is the number of milliseconds since the standard base time
34   * known as "the epoch", namely January 1, 1970, 00:00:00 GMT.
35   * </p>
36   *
37   * @see java.util.Date
38   */
39  public class TimeStamp implements Serializable, Comparable<TimeStamp> {
40      private static final long serialVersionUID = 8139806907588338737L;
41  
42      /**
43       * Baseline NTP time if bit-0=0 is 7-Feb-2036 @ 06:28:16 UTC
44       */
45      protected static final long msb0baseTime = 2085978496000L;
46  
47      /**
48       * Baseline NTP time if bit-0=1 is 1-Jan-1900 @ 01:00:00 UTC
49       */
50      protected static final long msb1baseTime = -2208988800000L;
51  
52      /**
53       * Default NTP date string format. E.g. Fri, Sep 12 2003 21:06:23.860. See <code>java.text.SimpleDateFormat</code> for code descriptions.
54       */
55      public static final String NTP_DATE_FORMAT = "EEE, MMM dd yyyy HH:mm:ss.SSS";
56  
57      /**
58       * Left-pad 8-character hexadecimal string with 0's
59       *
60       * @param buf - StringBuilder which is appended with leading 0's.
61       * @param l   - a long.
62       */
63      private static void appendHexString(final StringBuilder buf, final long l) {
64          final String s = Long.toHexString(l);
65          for (int i = s.length(); i < 8; i++) {
66              buf.append('0');
67          }
68          buf.append(s);
69      }
70  
71      /**
72       * Convert NTP timestamp hexstring (e.g. "c1a089bd.fc904f6d") to the NTP 64-bit unsigned fixed-point number.
73       *
74       * @param hexString the string to convert
75       *
76       * @return NTP 64-bit timestamp value.
77       * @throws NumberFormatException - if the string does not contain a parsable timestamp.
78       */
79      protected static long decodeNtpHexString(final String hexString) throws NumberFormatException {
80          if (hexString == null) {
81              throw new NumberFormatException("null");
82          }
83          final int ind = hexString.indexOf('.');
84          if (ind == -1) {
85              if (hexString.isEmpty()) {
86                  return 0;
87              }
88              return Long.parseLong(hexString, 16) << 32; // no decimal
89          }
90  
91          return Long.parseLong(hexString.substring(0, ind), 16) << 32 | Long.parseLong(hexString.substring(ind + 1), 16);
92      }
93  
94      /**
95       * Constructs a NTP timestamp object and initializes it so that it represents the time at which it was allocated, measured to the nearest millisecond.
96       *
97       * @return NTP timestamp object set to the current time.
98       * @see System#currentTimeMillis()
99       */
100     public static TimeStamp getCurrentTime() {
101         return getNtpTime(System.currentTimeMillis());
102     }
103 
104     // initialization of static time bases
105     /*
106      * static { TimeZone utcZone = TimeZone.getTimeZone("UTC"); Calendar calendar = Calendar.getInstance(utcZone); calendar.set(1900, Calendar.JANUARY, 1, 0, 0,
107      * 0); calendar.set(Calendar.MILLISECOND, 0); msb1baseTime = calendar.getTime().getTime(); calendar.set(2036, Calendar.FEBRUARY, 7, 6, 28, 16);
108      * calendar.set(Calendar.MILLISECOND, 0); msb0baseTime = calendar.getTime().getTime(); }
109      */
110 
111     /**
112      * Helper method to convert Java time to NTP timestamp object. Note that Java time (milliseconds) by definition has less precision than NTP time
113      * (picoseconds) so converting Ntptime to Javatime and back to Ntptime loses precision. For example, Tue, Dec 17 2002 09:07:24.810 is represented by a
114      * single Java-based time value of f22cd1fc8a, but its NTP equivalent are all values from c1a9ae1c.cf5c28f5 to c1a9ae1c.cf9db22c.
115      *
116      * @param dateMillis the milliseconds since January 1, 1970, 00:00:00 GMT.
117      * @return NTP timestamp object at the specified date.
118      */
119     public static TimeStamp getNtpTime(final long dateMillis) {
120         return new TimeStamp(toNtpTime(dateMillis));
121     }
122 
123     /**
124      * Converts 64-bit NTP timestamp to Java standard time.
125      *
126      * Note that java time (milliseconds) by definition has less precision than NTP time (picoseconds) so converting NTP timestamp to Java time and back to NTP
127      * timestamp loses precision. For example, Tue, Dec 17 2002 09:07:24.810 EST is represented by a single Java-based time value of f22cd1fc8a, but its NTP
128      * equivalent are all values ranging from c1a9ae1c.cf5c28f5 to c1a9ae1c.cf9db22c.
129      *
130      * @param ntpTimeValue the input time
131      * @return the number of milliseconds since January 1, 1970, 00:00:00 GMT represented by this NTP timestamp value.
132      */
133     public static long getTime(final long ntpTimeValue) {
134         final long seconds = ntpTimeValue >>> 32 & 0xffffffffL; // high-order 32-bits
135         long fraction = ntpTimeValue & 0xffffffffL; // low-order 32-bits
136 
137         // Use round-off on fractional part to preserve going to lower precision
138         fraction = Math.round(1000D * fraction / 0x100000000L);
139 
140         /*
141          * If the most significant bit (MSB) on the seconds field is set we use a different time base. The following text is a quote from RFC-2030 (SNTP v4):
142          *
143          * If bit 0 is set, the UTC time is in the range 1968-2036 and UTC time is reckoned from 0h 0m 0s UTC on 1 January 1900. If bit 0 is not set, the time
144          * is in the range 2036-2104 and UTC time is reckoned from 6h 28m 16s UTC on 7 February 2036.
145          */
146         final long msb = seconds & 0x80000000L;
147         if (msb == 0) {
148             // use base: 7-Feb-2036 @ 06:28:16 UTC
149             return msb0baseTime + seconds * 1000 + fraction;
150         }
151         // use base: 1-Jan-1900 @ 01:00:00 UTC
152         return msb1baseTime + seconds * 1000 + fraction;
153     }
154 
155     /**
156      * Parses the string argument as a NTP hexidecimal timestamp representation string (e.g. "c1a089bd.fc904f6d").
157      *
158      * @param s - hexstring.
159      * @return the Timestamp represented by the argument in hexidecimal.
160      * @throws NumberFormatException - if the string does not contain a parsable timestamp.
161      */
162     public static TimeStamp parseNtpString(final String s) throws NumberFormatException {
163         return new TimeStamp(decodeNtpHexString(s));
164     }
165 
166     /**
167      * Converts Java time to 64-bit NTP time representation.
168      *
169      * @param millis Java time
170      * @return NTP timestamp representation of Java time value.
171      */
172     protected static long toNtpTime(final long millis) {
173         final boolean useBase1 = millis < msb0baseTime; // time < Feb-2036
174         final long baseTimeMillis;
175         if (useBase1) {
176             baseTimeMillis = millis - msb1baseTime; // dates <= Feb-2036
177         } else {
178             // if base0 needed for dates >= Feb-2036
179             baseTimeMillis = millis - msb0baseTime;
180         }
181 
182         long seconds = baseTimeMillis / 1000;
183         final long fraction = baseTimeMillis % 1000 * 0x100000000L / 1000;
184 
185         if (useBase1) {
186             seconds |= 0x80000000L; // set high-order bit if msb1baseTime 1900 used
187         }
188 
189         return seconds << 32 | fraction;
190     }
191 
192     /**
193      * Converts 64-bit NTP timestamp value to a <code>String</code>. The NTP timestamp value is represented as hexadecimal string with seconds separated by
194      * fractional seconds by a decimal point; e.g. c1a089bd.fc904f6d == Tue, Dec 10 2002 10:41:49.986
195      *
196      * @param ntpTime the 64 bit timestamp
197      *
198      * @return NTP timestamp 64-bit long value as hexadecimal string with seconds separated by fractional seconds.
199      */
200     public static String toString(final long ntpTime) {
201         final StringBuilder buf = new StringBuilder();
202         // high-order second bits (32..63) as hexstring
203         appendHexString(buf, ntpTime >>> 32 & 0xffffffffL);
204 
205         // low-order fractional seconds bits (0..31) as hexstring
206         buf.append('.');
207         appendHexString(buf, ntpTime & 0xffffffffL);
208 
209         return buf.toString();
210     }
211 
212     /**
213      * NTP timestamp value: 64-bit unsigned fixed-point number as defined in RFC-1305 with high-order 32 bits the seconds field and the low-order 32-bits the
214      * fractional field.
215      */
216     private final long ntpTime;
217 
218     private DateFormat simpleFormatter;
219 
220     private DateFormat utcFormatter;
221 
222     /**
223      * Constructs a newly allocated NTP timestamp object that represents the Java Date argument.
224      *
225      * @param d - the Date to be represented by the Timestamp object.
226      */
227     public TimeStamp(final Date d) {
228         ntpTime = d == null ? 0 : toNtpTime(d.getTime());
229     }
230 
231     /**
232      * Constructs a newly allocated NTP timestamp object that represents the native 64-bit long argument.
233      *
234      * @param ntpTime the timestamp
235      */
236     public TimeStamp(final long ntpTime) {
237         this.ntpTime = ntpTime;
238     }
239 
240     /**
241      * Constructs a newly allocated NTP timestamp object that represents the value represented by the string in hexdecimal form (e.g. "c1a089bd.fc904f6d").
242      *
243      * @param hexStamp the hexadecimal timestamp
244      *
245      * @throws NumberFormatException - if the string does not contain a parsable timestamp.
246      */
247     public TimeStamp(final String hexStamp) throws NumberFormatException {
248         ntpTime = decodeNtpHexString(hexStamp);
249     }
250 
251     /**
252      * Compares two Timestamps numerically.
253      *
254      * @param anotherTimeStamp - the <code>TimeStamp</code> to be compared.
255      * @return the value <code>0</code> if the argument TimeStamp is equal to this TimeStamp; a value less than <code>0</code> if this TimeStamp is numerically
256      *         less than the TimeStamp argument; and a value greater than <code>0</code> if this TimeStamp is numerically greater than the TimeStamp argument
257      *         (signed comparison).
258      */
259     @Override
260     public int compareTo(final TimeStamp anotherTimeStamp) {
261         final long thisVal = this.ntpTime;
262         final long anotherVal = anotherTimeStamp.ntpTime;
263         return Long.compare(thisVal, anotherVal);
264     }
265 
266     /**
267      * Compares this object against the specified object. The result is {@code true} if and only if the argument is not {@code null} and is a
268      * <code>Long</code> object that contains the same <code>long</code> value as this object.
269      *
270      * @param obj the object to compare with.
271      * @return {@code true} if the objects are the same; {@code false} otherwise.
272      */
273     @Override
274     public boolean equals(final Object obj) {
275         if (obj instanceof TimeStamp) {
276             return ntpTime == ((TimeStamp) obj).ntpValue();
277         }
278         return false;
279     }
280 
281     /**
282      * Converts NTP timestamp to Java Date object.
283      *
284      * @return NTP Timestamp in Java Date
285      */
286     public Date getDate() {
287         return new Date(getTime(ntpTime));
288     }
289 
290     /**
291      * Returns low-order 32-bits representing the fractional seconds.
292      *
293      * @return fractional seconds represented by this NTP timestamp.
294      */
295     public long getFraction() {
296         return ntpTime & 0xffffffffL;
297     }
298 
299     /**
300      * Returns high-order 32-bits representing the seconds of this NTP timestamp.
301      *
302      * @return seconds represented by this NTP timestamp.
303      */
304     public long getSeconds() {
305         return ntpTime >>> 32 & 0xffffffffL;
306     }
307 
308     /**
309      * Converts NTP timestamp to Java standard time.
310      *
311      * @return the number of milliseconds since January 1, 1970, 00:00:00 GMT represented by this NTP timestamp value.
312      */
313     public long getTime() {
314         return getTime(ntpTime);
315     }
316 
317     /**
318      * Computes a hash code for this Timestamp. The result is the exclusive OR of the two halves of the primitive <code>long</code> value represented by this
319      * <code>TimeStamp</code> object. That is, the hash code is the value of the expression: <blockquote>
320      *
321      * <pre>
322      * {@code
323      * (int) (this.ntpValue() ^ (this.ntpValue() >>> 32))
324      * }
325      * </pre>
326      *
327      * </blockquote>
328      *
329      * @return a hash code value for this object.
330      */
331     @Override
332     public int hashCode() {
333         return (int) (ntpTime ^ ntpTime >>> 32);
334     }
335 
336     /**
337      * Returns the value of this Timestamp as a long value.
338      *
339      * @return the 64-bit long value represented by this object.
340      */
341     public long ntpValue() {
342         return ntpTime;
343     }
344 
345     private void readObject(final java.io.ObjectInputStream in) {
346         throw new UnsupportedOperationException("Serialization is not supported");
347     }
348 
349     /**
350      * Converts this <code>TimeStamp</code> object to a <code>String</code> of the form: <blockquote>
351      *
352      * <pre>
353      * EEE, MMM dd yyyy HH:mm:ss.SSS
354      * </pre>
355      *
356      * </blockquote> See java.text.SimpleDataFormat for code descriptions.
357      *
358      * @return a string representation of this date.
359      */
360     public String toDateString() {
361         if (simpleFormatter == null) {
362             simpleFormatter = new SimpleDateFormat(NTP_DATE_FORMAT, Locale.US);
363             simpleFormatter.setTimeZone(TimeZone.getDefault());
364         }
365         final Date ntpDate = getDate();
366         return simpleFormatter.format(ntpDate);
367     }
368 
369     /**
370      * Converts this <code>TimeStamp</code> object to a <code>String</code>. The NTP timestamp 64-bit long value is represented as hexadecimal string with
371      * seconds separated by fractional seconds by a decimal point; e.g. c1a089bd.fc904f6d == Tue, Dec 10 2002 10:41:49.986
372      *
373      * @return NTP timestamp 64-bit long value as hexadecimal string with seconds separated by fractional seconds.
374      */
375     @Override
376     public String toString() {
377         return toString(ntpTime);
378     }
379 
380     /*
381      * Serialization is unnecessary for this class. Reject attempts to do so until such time as the Serializable attribute can be dropped.
382      */
383 
384     /**
385      * Converts this <code>TimeStamp</code> object to a <code>String</code> of the form: <blockquote>
386      *
387      * <pre>
388      * EEE, MMM dd yyyy HH:mm:ss.SSS UTC
389      * </pre>
390      *
391      * </blockquote> See java.text.SimpleDataFormat for code descriptions.
392      *
393      * @return a string representation of this date in UTC.
394      */
395     public String toUTCString() {
396         if (utcFormatter == null) {
397             utcFormatter = new SimpleDateFormat(NTP_DATE_FORMAT + " 'UTC'", Locale.US);
398             utcFormatter.setTimeZone(TimeZone.getTimeZone("UTC"));
399         }
400         final Date ntpDate = getDate();
401         return utcFormatter.format(ntpDate);
402     }
403 
404     private void writeObject(final java.io.ObjectOutputStream out) {
405         throw new UnsupportedOperationException("Serialization is not supported");
406     }
407 
408 }