View Javadoc

1   package org.apache.commons.net.ntp;
2   /*
3    * Copyright 2001-2005 The Apache Software Foundation
4    *
5    * Licensed under the Apache License, Version 2.0 (the "License");
6    * you may not use this file except in compliance with the License.
7    * 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  
19  import java.util.TimeZone;
20  import java.util.Date;
21  import java.util.Locale;
22  import java.lang.ref.SoftReference;
23  import java.text.SimpleDateFormat;
24  import java.text.DateFormat;
25  
26  /***
27   * TimeStamp class represents the Network Time Protocol (NTP) timestamp
28   * as defined in RFC-1305 and SNTP (RFC-2030). It is represented as a
29   * 64-bit unsigned fixed-point number in seconds relative to 0-hour on 1-January-1900.
30   * The 32-bit low-order bits are the fractional seconds whose precision is
31   * about 200 picoseconds. Assumes overflow date when date passes MAX_LONG
32   * and reverts back to 0 is 2036 and not 1900. Test for most significant
33   * bit: if MSB=0 then 2036 basis is used otherwise 1900 if MSB=1.
34   * <p>
35   * Methods exist to convert NTP timestamps to and from the equivalent Java date
36   * representation, which is the number of milliseconds since the standard base
37   * time known as "the epoch", namely January 1, 1970, 00:00:00 GMT.
38   * </p>
39   *
40   * @author Jason Mathews, MITRE Corp
41   * @version $Revision: 165675 $ $Date: 2005-05-02 15:09:55 -0500 (Mon, 02 May 2005) $
42   * @see java.util.Date
43   */
44  public class TimeStamp implements java.io.Serializable, Comparable
45  {
46  
47      /**
48       * baseline NTP time if bit-0=0 -> 7-Feb-2036 @ 06:28:16 UTC
49       */
50      protected static final long msb0baseTime = 2085978496000L;
51  
52      /**
53       *  baseline NTP time if bit-0=1 -> 1-Jan-1900 @ 01:00:00 UTC
54       */
55      protected static final long msb1baseTime = -2208988800000L;
56  
57      /**
58       * Default NTP date string format. E.g. Fri, Sep 12 2003 21:06:23.860.
59       * See <code>java.text.SimpleDateFormat</code> for code descriptions.
60       */
61      public final static String NTP_DATE_FORMAT = "EEE, MMM dd yyyy HH:mm:ss.SSS";
62  
63      /*
64       * Caches for the DateFormatters used by various toString methods.
65       */
66      private static SoftReference simpleFormatter = null;
67      private static SoftReference utcFormatter = null;
68  
69      /**
70       * NTP timestamp value: 64-bit unsigned fixed-point number as defined in RFC-1305
71       * with high-order 32 bits the seconds field and the low-order 32-bits the
72       * fractional field.
73       */
74      private long ntpTime;
75  
76      private static final long serialVersionUID = 8139806907588338737L;
77  
78      // initialization of static time bases
79      /*
80      static {
81          TimeZone utcZone = TimeZone.getTimeZone("UTC");
82          Calendar calendar = Calendar.getInstance(utcZone);
83          calendar.set(1900, Calendar.JANUARY, 1, 0, 0, 0);
84          calendar.set(Calendar.MILLISECOND, 0);
85          msb1baseTime = calendar.getTime().getTime();
86          calendar.set(2036, Calendar.FEBRUARY, 7, 6, 28, 16);
87          calendar.set(Calendar.MILLISECOND, 0);
88          msb0baseTime = calendar.getTime().getTime();
89      }
90      */
91  
92      /***
93       * Constructs a newly allocated NTP timestamp object
94       * that represents the native 64-bit long argument.
95       */
96      public TimeStamp(long ntpTime)
97      {
98          this.ntpTime = ntpTime;
99      }
100 
101     /***
102      * Constructs a newly allocated NTP timestamp object
103      * that represents the value represented by the string
104      * in hexdecimal form (e.g. "c1a089bd.fc904f6d").
105      *
106      * @throws NumberFormatException - if the string does not contain a parsable timestamp.
107      */
108     public TimeStamp(String s) throws NumberFormatException
109     {
110         ntpTime = decodeNtpHexString(s);
111     }
112 
113     /***
114      * Constructs a newly allocated NTP timestamp object
115      * that represents the Java Date argument.
116      *
117      * @param d - the Date to be represented by the Timestamp object.
118      */
119     public TimeStamp(Date d)
120     {
121         ntpTime = (d == null) ? 0 : toNtpTime(d.getTime());
122     }
123 
124     /***
125      * Returns the value of this Timestamp as a long value.
126      *
127      * @return the 64-bit long value represented by this object.
128      */
129     public long ntpValue()
130     {
131         return ntpTime;
132     }
133 
134     /***
135      * Returns high-order 32-bits representing the seconds of this NTP timestamp.
136      *
137      * @return seconds represented by this NTP timestamp.
138      */
139     public long getSeconds()
140     {
141         return (ntpTime >>> 32) & 0xffffffffL;
142     }
143 
144     /***
145      * Returns low-order 32-bits representing the fractional seconds.
146      *
147      * @return fractional seconds represented by this NTP timestamp.
148      */
149     public long getFraction()
150     {
151         return ntpTime & 0xffffffffL;
152     }
153 
154     /***
155      * Convert NTP timestamp to Java standard time.
156      *
157      * @return NTP Timestamp in Java time
158      */
159     public long getTime()
160     {
161         return getTime(ntpTime);
162     }
163 
164     /***
165      * Convert NTP timestamp to Java Date object.
166      *
167      * @return NTP Timestamp in Java Date
168      */
169     public Date getDate()
170     {
171         long time = getTime(ntpTime);
172         return new Date(time);
173     }
174 
175     /***
176      * Convert 64-bit NTP timestamp to Java standard time.
177      *
178      * Note that java time (milliseconds) by definition has less precision
179      * then NTP time (picoseconds) so converting NTP timestamp to java time and back
180      * to NTP timestamp loses precision. For example, Tue, Dec 17 2002 09:07:24.810 EST
181      * is represented by a single Java-based time value of f22cd1fc8a, but its
182      * NTP equivalent are all values ranging from c1a9ae1c.cf5c28f5 to c1a9ae1c.cf9db22c.
183      *
184      * @param ntpTimeValue
185      * @return the number of milliseconds since January 1, 1970, 00:00:00 GMT
186      * represented by this NTP timestamp value.
187      */
188     public static long getTime(long ntpTimeValue)
189     {
190         long seconds = (ntpTimeValue >>> 32) & 0xffffffffL;	// high-order 32-bits
191         long fraction = ntpTimeValue & 0xffffffffL;		// low-order 32-bits
192 
193         // Use round-off on fractional part to preserve going to lower precision
194         fraction = Math.round(1000D * fraction / 0x100000000L);
195 
196         /*
197          * If the most significant bit (MSB) on the seconds field is set we use
198          * a different time base. The following text is a quote from RFC-2030 (SNTP v4):
199          *
200          *  If bit 0 is set, the UTC time is in the range 1968-2036 and UTC time
201          *  is reckoned from 0h 0m 0s UTC on 1 January 1900. If bit 0 is not set,
202          *  the time is in the range 2036-2104 and UTC time is reckoned from
203          *  6h 28m 16s UTC on 7 February 2036.
204          */
205         long msb = seconds & 0x80000000L;
206         if (msb == 0) {
207             // use base: 7-Feb-2036 @ 06:28:16 UTC
208             return msb0baseTime + (seconds * 1000) + fraction;
209         } else {
210             // use base: 1-Jan-1900 @ 01:00:00 UTC
211             return msb1baseTime + (seconds * 1000) + fraction;
212         }
213     }
214 
215     /***
216      * Helper method to convert Java time to NTP timestamp object.
217      * Note that Java time (milliseconds) by definition has less precision
218      * then NTP time (picoseconds) so converting Ntptime to Javatime and back
219      * to Ntptime loses precision. For example, Tue, Dec 17 2002 09:07:24.810
220      * is represented by a single Java-based time value of f22cd1fc8a, but its
221      * NTP equivalent are all values from c1a9ae1c.cf5c28f5 to c1a9ae1c.cf9db22c.
222      * @param   date   the milliseconds since January 1, 1970, 00:00:00 GMT.
223      * @return NTP timestamp object at the specified date.
224      */
225     public static TimeStamp getNtpTime(long date)
226     {
227         return new TimeStamp(toNtpTime(date));
228     }
229 
230     /***
231      * Constructs a NTP timestamp object and initializes it so that
232      * it represents the time at which it was allocated, measured to the
233      * nearest millisecond.
234      * @return NTP timestamp object set to the current time.
235      * @see     java.lang.System#currentTimeMillis()
236      */
237     public static TimeStamp getCurrentTime()
238     {
239         return getNtpTime(System.currentTimeMillis());
240     }
241 
242     /***
243      * Convert NTP timestamp hexstring (e.g. "c1a089bd.fc904f6d") to the NTP
244      * 64-bit unsigned fixed-point number.
245      *
246      * @return NTP 64-bit timestamp value.
247      * @throws NumberFormatException - if the string does not contain a parsable timestamp.
248      */
249     protected static long decodeNtpHexString(String s)
250             throws NumberFormatException
251     {
252         if (s == null) {
253             throw new NumberFormatException("null");
254         }
255         int ind = s.indexOf('.');
256         if (ind == -1) {
257             if (s.length() == 0) return 0;
258             return Long.parseLong(s, 16) << 32; // no decimal
259         }
260 
261         return Long.parseLong(s.substring(0, ind), 16) << 32 |
262                 Long.parseLong(s.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      * (int)(this.ntpValue()^(this.ntpValue() >>> 32))
314      * </pre></blockquote>
315      *
316      * @return  a hash code value for this object.
317      */
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     public boolean equals(Object obj)
334     {
335         if (obj instanceof TimeStamp) {
336             return ntpTime == ((TimeStamp) obj).ntpValue();
337         }
338         return false;
339     }
340 
341     /***
342      * Converts this <code>TimeStamp</code> object to a <code>String</code>.
343      * The NTP timestamp 64-bit long value is represented as hex string with
344      * seconds separated by fractional seconds by a decimal point;
345      * e.g. c1a089bd.fc904f6d <=> Tue, Dec 10 2002 10:41:49.986
346      *
347      * @return NTP timestamp 64-bit long value as hex string with seconds
348      * separated by fractional seconds.
349      */
350     public String toString()
351     {
352         return toString(ntpTime);
353     }
354 
355     /***
356      * Left-pad 8-character hex string with 0's
357      *
358      * @param buf - StringBuffer which is appended with leading 0's.
359      * @param l - a long.
360      */
361     private static void appendHexString(StringBuffer buf, long l)
362     {
363         String s = Long.toHexString(l);
364         for (int i = s.length(); i < 8; i++)
365             buf.append('0');
366         buf.append(s);
367     }
368 
369     /***
370      * Converts 64-bit NTP timestamp value to a <code>String</code>.
371      * The NTP timestamp value is represented as hex string with
372      * seconds separated by fractional seconds by a decimal point;
373      * e.g. c1a089bd.fc904f6d <=> Tue, Dec 10 2002 10:41:49.986
374      *
375      * @return NTP timestamp 64-bit long value as hex string with seconds
376      * separated by fractional seconds.
377      */
378     public static String toString(long ntpTime)
379     {
380         StringBuffer buf = new StringBuffer();
381         // high-order second bits (32..63) as hexstring
382         appendHexString(buf, (ntpTime >>> 32) & 0xffffffffL);
383 
384         // low-order fractional seconds bits (0..31) as hexstring
385         buf.append('.');
386         appendHexString(buf, ntpTime & 0xffffffffL);
387 
388         return buf.toString();
389     }
390 
391     /***
392      * Converts this <code>TimeStamp</code> object to a <code>String</code>
393      * of the form:
394      * <blockquote><pre>
395      * EEE, MMM dd yyyy HH:mm:ss.SSS</pre></blockquote>
396      * See java.text.SimpleDataFormat for code descriptions.
397      *
398      * @return  a string representation of this date.
399      */
400     public String toDateString()
401     {
402         DateFormat formatter = null;
403         if (simpleFormatter != null) {
404             formatter = (DateFormat) simpleFormatter.get();
405         }
406         if (formatter == null) {
407             // No cache yet, or cached formatter GC'd
408             formatter = new SimpleDateFormat(NTP_DATE_FORMAT, Locale.US);
409             formatter.setTimeZone(TimeZone.getDefault());
410             simpleFormatter = new SoftReference(formatter);
411         }
412         Date ntpDate = getDate();
413         synchronized (formatter) {
414             return formatter.format(ntpDate);
415         }
416     }
417 
418     /***
419      * Converts this <code>TimeStamp</code> object to a <code>String</code>
420      * of the form:
421      * <blockquote><pre>
422      * EEE, MMM dd yyyy HH:mm:ss.SSS UTC</pre></blockquote>
423      * See java.text.SimpleDataFormat for code descriptions.
424      *
425      * @return  a string representation of this date in UTC.
426      */
427     public String toUTCString()
428     {
429         DateFormat formatter = null;
430         if (utcFormatter != null)
431             formatter = (DateFormat) utcFormatter.get();
432         if (formatter == null) {
433             // No cache yet, or cached formatter GC'd
434             formatter = new SimpleDateFormat(NTP_DATE_FORMAT + " 'UTC'",
435                     Locale.US);
436             formatter.setTimeZone(TimeZone.getTimeZone("UTC"));
437             utcFormatter = new SoftReference(formatter);
438         }
439         Date ntpDate = getDate();
440         synchronized (formatter) {
441             return formatter.format(ntpDate);
442         }
443     }
444 
445     /***
446      * Compares two Timestamps numerically.
447      *
448      * @param   anotherTimeStamp - the <code>TimeStamp</code> to be compared.
449      * @return  the value <code>0</code> if the argument TimeStamp is equal to
450      *          this TimeStamp; a value less than <code>0</code> if this TimeStamp
451      *          is numerically less than the TimeStamp argument; and a
452      *          value greater than <code>0</code> if this TimeStamp is
453      *          numerically greater than the TimeStamp argument
454      *		(signed comparison).
455      */
456     public int compareTo(TimeStamp anotherTimeStamp)
457     {
458         long thisVal = this.ntpTime;
459         long anotherVal = anotherTimeStamp.ntpTime;
460         return (thisVal < anotherVal ? -1 : (thisVal == anotherVal ? 0 : 1));
461     }
462 
463     /***
464      * Compares this TimeStamp to another Object.  If the Object is a TimeStamp,
465      * this function behaves like <code>compareTo(TimeStamp)</code>.  Otherwise,
466      * it throws a <code>ClassCastException</code> (as TimeStamps are comparable
467      * only to other TimeStamps).
468      *
469      * @param   o the <code>Object</code> to be compared.
470      * @return  the value <code>0</code> if the argument is a TimeStamp
471      *		numerically equal to this TimeStamp; a value less than
472      *		<code>0</code> if the argument is a TimeStamp numerically
473      *		greater than this TimeStamp; and a value greater than
474      *		<code>0</code> if the argument is a TimeStamp numerically
475      *		less than this TimeStamp.
476      * @exception ClassCastException if the argument is not a
477      *		  <code>TimeStamp</code>.
478      * @see     java.lang.Comparable
479      */
480     public int compareTo(Object o)
481     {
482         return compareTo((TimeStamp) o);
483     }
484 
485 }