View Javadoc

1   package org.apache.commons.net.ntp;
2   /*
3    * Licensed to the Apache Software Foundation (ASF) under one or more
4    * contributor license agreements.  See the NOTICE file distributed with
5    * this work for additional information regarding copyright ownership.
6    * The ASF licenses this file to You under the Apache License, Version 2.0
7    * (the "License"); you may not use this file except in compliance with
8    * the License.  You may obtain a copy of the License at
9    *
10   *      http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  
19  
20  
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
29   * as defined in RFC-1305 and SNTP (RFC-2030). It is represented as a
30   * 64-bit unsigned fixed-point number in seconds relative to 0-hour on 1-January-1900.
31   * The 32-bit low-order bits are the fractional seconds whose precision is
32   * about 200 picoseconds. Assumes overflow date when date passes MAX_LONG
33   * and reverts back to 0 is 2036 and not 1900. Test for most significant
34   * bit: if MSB=0 then 2036 basis is used otherwise 1900 if MSB=1.
35   * <p>
36   * Methods exist to convert NTP timestamps to and from the equivalent Java date
37   * representation, which is the number of milliseconds since the standard base
38   * time known as "the epoch", namely January 1, 1970, 00:00:00 GMT.
39   * </p>
40   *
41   * @author Jason Mathews, MITRE Corp
42   * @version $Revision: 1489361 $
43   * @see java.util.Date
44   */
45  public class TimeStamp implements java.io.Serializable, Comparable<TimeStamp>
46  {
47      private static final long serialVersionUID = 8139806907588338737L;
48  
49      /**
50       * baseline NTP time if bit-0=0 -> 7-Feb-2036 @ 06:28:16 UTC
51       */
52      protected static final long msb0baseTime = 2085978496000L;
53  
54      /**
55       *  baseline NTP time if bit-0=1 -> 1-Jan-1900 @ 01:00:00 UTC
56       */
57      protected static final long msb1baseTime = -2208988800000L;
58  
59      /**
60       * Default NTP date string format. E.g. Fri, Sep 12 2003 21:06:23.860.
61       * See <code>java.text.SimpleDateFormat</code> for code descriptions.
62       */
63      public final static String NTP_DATE_FORMAT = "EEE, MMM dd yyyy HH:mm:ss.SSS";
64  
65      /**
66       * NTP timestamp value: 64-bit unsigned fixed-point number as defined in RFC-1305
67       * with high-order 32 bits the seconds field and the low-order 32-bits the
68       * fractional field.
69       */
70      private final long ntpTime;
71  
72      private DateFormat simpleFormatter;
73      private DateFormat utcFormatter;
74  
75      // initialization of static time bases
76      /*
77      static {
78          TimeZone utcZone = TimeZone.getTimeZone("UTC");
79          Calendar calendar = Calendar.getInstance(utcZone);
80          calendar.set(1900, Calendar.JANUARY, 1, 0, 0, 0);
81          calendar.set(Calendar.MILLISECOND, 0);
82          msb1baseTime = calendar.getTime().getTime();
83          calendar.set(2036, Calendar.FEBRUARY, 7, 6, 28, 16);
84          calendar.set(Calendar.MILLISECOND, 0);
85          msb0baseTime = calendar.getTime().getTime();
86      }
87      */
88  
89      /***
90       * Constructs a newly allocated NTP timestamp object
91       * that represents the native 64-bit long argument.
92       */
93      public TimeStamp(long ntpTime)
94      {
95          this.ntpTime = ntpTime;
96      }
97  
98      /***
99       * 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 //    @Override
445     public int compareTo(TimeStamp anotherTimeStamp)
446     {
447         long thisVal = this.ntpTime;
448         long anotherVal = anotherTimeStamp.ntpTime;
449         return (thisVal < anotherVal ? -1 : (thisVal == anotherVal ? 0 : 1));
450     }
451 
452 }