001    package 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    
021    import java.lang.ref.SoftReference;
022    import java.text.DateFormat;
023    import java.text.SimpleDateFormat;
024    import java.util.Date;
025    import java.util.Locale;
026    import java.util.TimeZone;
027    
028    /***
029     * TimeStamp class represents the Network Time Protocol (NTP) timestamp
030     * as defined in RFC-1305 and SNTP (RFC-2030). It is represented as a
031     * 64-bit unsigned fixed-point number in seconds relative to 0-hour on 1-January-1900.
032     * The 32-bit low-order bits are the fractional seconds whose precision is
033     * about 200 picoseconds. Assumes overflow date when date passes MAX_LONG
034     * and reverts back to 0 is 2036 and not 1900. Test for most significant
035     * bit: if MSB=0 then 2036 basis is used otherwise 1900 if MSB=1.
036     * <p>
037     * Methods exist to convert NTP timestamps to and from the equivalent Java date
038     * representation, which is the number of milliseconds since the standard base
039     * time known as "the epoch", namely January 1, 1970, 00:00:00 GMT.
040     * </p>
041     *
042     * @author Jason Mathews, MITRE Corp
043     * @version $Revision: 929344 $ $Date: 2010-03-31 01:20:49 +0100 (Wed, 31 Mar 2010) $
044     * @see java.util.Date
045     */
046    public class TimeStamp implements java.io.Serializable, Comparable<TimeStamp>
047    {
048    
049        /**
050         * baseline NTP time if bit-0=0 -> 7-Feb-2036 @ 06:28:16 UTC
051         */
052        protected static final long msb0baseTime = 2085978496000L;
053    
054        /**
055         *  baseline NTP time if bit-0=1 -> 1-Jan-1900 @ 01:00:00 UTC
056         */
057        protected static final long msb1baseTime = -2208988800000L;
058    
059        /**
060         * Default NTP date string format. E.g. Fri, Sep 12 2003 21:06:23.860.
061         * See <code>java.text.SimpleDateFormat</code> for code descriptions.
062         */
063        public final static String NTP_DATE_FORMAT = "EEE, MMM dd yyyy HH:mm:ss.SSS";
064    
065        /*
066         * Caches for the DateFormatters used by various toString methods.
067         */
068        private static SoftReference<DateFormat> simpleFormatter = null;
069        private static SoftReference<DateFormat> utcFormatter = null;
070    
071        /**
072         * NTP timestamp value: 64-bit unsigned fixed-point number as defined in RFC-1305
073         * with high-order 32 bits the seconds field and the low-order 32-bits the
074         * fractional field.
075         */
076        private final long ntpTime;
077    
078        private static final long serialVersionUID = 8139806907588338737L;
079    
080        // initialization of static time bases
081        /*
082        static {
083            TimeZone utcZone = TimeZone.getTimeZone("UTC");
084            Calendar calendar = Calendar.getInstance(utcZone);
085            calendar.set(1900, Calendar.JANUARY, 1, 0, 0, 0);
086            calendar.set(Calendar.MILLISECOND, 0);
087            msb1baseTime = calendar.getTime().getTime();
088            calendar.set(2036, Calendar.FEBRUARY, 7, 6, 28, 16);
089            calendar.set(Calendar.MILLISECOND, 0);
090            msb0baseTime = calendar.getTime().getTime();
091        }
092        */
093    
094        /***
095         * Constructs a newly allocated NTP timestamp object
096         * that represents the native 64-bit long argument.
097         */
098        public TimeStamp(long ntpTime)
099        {
100            this.ntpTime = ntpTime;
101        }
102    
103        /***
104         * Constructs a newly allocated NTP timestamp object
105         * that represents the value represented by the string
106         * in hexdecimal form (e.g. "c1a089bd.fc904f6d").
107         *
108         * @throws NumberFormatException - if the string does not contain a parsable timestamp.
109         */
110        public TimeStamp(String s) throws NumberFormatException
111        {
112            ntpTime = decodeNtpHexString(s);
113        }
114    
115        /***
116         * Constructs a newly allocated NTP timestamp object
117         * that represents the Java Date argument.
118         *
119         * @param d - the Date to be represented by the Timestamp object.
120         */
121        public TimeStamp(Date d)
122        {
123            ntpTime = (d == null) ? 0 : toNtpTime(d.getTime());
124        }
125    
126        /***
127         * Returns the value of this Timestamp as a long value.
128         *
129         * @return the 64-bit long value represented by this object.
130         */
131        public long ntpValue()
132        {
133            return ntpTime;
134        }
135    
136        /***
137         * Returns high-order 32-bits representing the seconds of this NTP timestamp.
138         *
139         * @return seconds represented by this NTP timestamp.
140         */
141        public long getSeconds()
142        {
143            return (ntpTime >>> 32) & 0xffffffffL;
144        }
145    
146        /***
147         * Returns low-order 32-bits representing the fractional seconds.
148         *
149         * @return fractional seconds represented by this NTP timestamp.
150         */
151        public long getFraction()
152        {
153            return ntpTime & 0xffffffffL;
154        }
155    
156        /***
157         * Convert NTP timestamp to Java standard time.
158         *
159         * @return NTP Timestamp in Java time
160         */
161        public long getTime()
162        {
163            return getTime(ntpTime);
164        }
165    
166        /***
167         * Convert NTP timestamp to Java Date object.
168         *
169         * @return NTP Timestamp in Java Date
170         */
171        public Date getDate()
172        {
173            long time = getTime(ntpTime);
174            return new Date(time);
175        }
176    
177        /***
178         * Convert 64-bit NTP timestamp to Java standard time.
179         *
180         * Note that java time (milliseconds) by definition has less precision
181         * then NTP time (picoseconds) so converting NTP timestamp to java time and back
182         * to NTP timestamp loses precision. For example, Tue, Dec 17 2002 09:07:24.810 EST
183         * is represented by a single Java-based time value of f22cd1fc8a, but its
184         * NTP equivalent are all values ranging from c1a9ae1c.cf5c28f5 to c1a9ae1c.cf9db22c.
185         *
186         * @param ntpTimeValue
187         * @return the number of milliseconds since January 1, 1970, 00:00:00 GMT
188         * represented by this NTP timestamp value.
189         */
190        public static long getTime(long ntpTimeValue)
191        {
192            long seconds = (ntpTimeValue >>> 32) & 0xffffffffL;     // high-order 32-bits
193            long fraction = ntpTimeValue & 0xffffffffL;             // low-order 32-bits
194    
195            // Use round-off on fractional part to preserve going to lower precision
196            fraction = Math.round(1000D * fraction / 0x100000000L);
197    
198            /*
199             * If the most significant bit (MSB) on the seconds field is set we use
200             * a different time base. The following text is a quote from RFC-2030 (SNTP v4):
201             *
202             *  If bit 0 is set, the UTC time is in the range 1968-2036 and UTC time
203             *  is reckoned from 0h 0m 0s UTC on 1 January 1900. If bit 0 is not set,
204             *  the time is in the range 2036-2104 and UTC time is reckoned from
205             *  6h 28m 16s UTC on 7 February 2036.
206             */
207            long msb = seconds & 0x80000000L;
208            if (msb == 0) {
209                // use base: 7-Feb-2036 @ 06:28:16 UTC
210                return msb0baseTime + (seconds * 1000) + fraction;
211            } else {
212                // use base: 1-Jan-1900 @ 01:00:00 UTC
213                return msb1baseTime + (seconds * 1000) + fraction;
214            }
215        }
216    
217        /***
218         * Helper method to convert Java time to NTP timestamp object.
219         * Note that Java time (milliseconds) by definition has less precision
220         * then NTP time (picoseconds) so converting Ntptime to Javatime and back
221         * to Ntptime loses precision. For example, Tue, Dec 17 2002 09:07:24.810
222         * is represented by a single Java-based time value of f22cd1fc8a, but its
223         * NTP equivalent are all values from c1a9ae1c.cf5c28f5 to c1a9ae1c.cf9db22c.
224         * @param   date   the milliseconds since January 1, 1970, 00:00:00 GMT.
225         * @return NTP timestamp object at the specified date.
226         */
227        public static TimeStamp getNtpTime(long date)
228        {
229            return new TimeStamp(toNtpTime(date));
230        }
231    
232        /***
233         * Constructs a NTP timestamp object and initializes it so that
234         * it represents the time at which it was allocated, measured to the
235         * nearest millisecond.
236         * @return NTP timestamp object set to the current time.
237         * @see     java.lang.System#currentTimeMillis()
238         */
239        public static TimeStamp getCurrentTime()
240        {
241            return getNtpTime(System.currentTimeMillis());
242        }
243    
244        /***
245         * Convert NTP timestamp hexstring (e.g. "c1a089bd.fc904f6d") to the NTP
246         * 64-bit unsigned fixed-point number.
247         *
248         * @return NTP 64-bit timestamp value.
249         * @throws NumberFormatException - if the string does not contain a parsable timestamp.
250         */
251        protected static long decodeNtpHexString(String s)
252                throws NumberFormatException
253        {
254            if (s == null) {
255                throw new NumberFormatException("null");
256            }
257            int ind = s.indexOf('.');
258            if (ind == -1) {
259                if (s.length() == 0) return 0;
260                return Long.parseLong(s, 16) << 32; // no decimal
261            }
262    
263            return Long.parseLong(s.substring(0, ind), 16) << 32 |
264                    Long.parseLong(s.substring(ind + 1), 16);
265        }
266    
267        /***
268         * Parses the string argument as a NTP hexidecimal timestamp representation string
269         * (e.g. "c1a089bd.fc904f6d").
270         *
271         * @param s - hexstring.
272         * @return the Timestamp represented by the argument in hexidecimal.
273         * @throws NumberFormatException - if the string does not contain a parsable timestamp.
274         */
275        public static TimeStamp parseNtpString(String s)
276                throws NumberFormatException
277        {
278            return new TimeStamp(decodeNtpHexString(s));
279        }
280    
281        /***
282         * Converts Java time to 64-bit NTP time representation.
283         *
284         * @param t Java time
285         * @return NTP timestamp representation of Java time value.
286         */
287        protected static long toNtpTime(long t)
288        {
289            boolean useBase1 = t < msb0baseTime;    // time < Feb-2036
290            long baseTime;
291            if (useBase1) {
292                baseTime = t - msb1baseTime; // dates <= Feb-2036
293            } else {
294                // if base0 needed for dates >= Feb-2036
295                baseTime = t - msb0baseTime;
296            }
297    
298            long seconds = baseTime / 1000;
299            long fraction = ((baseTime % 1000) * 0x100000000L) / 1000;
300    
301            if (useBase1) {
302                seconds |= 0x80000000L; // set high-order bit if msb1baseTime 1900 used
303            }
304    
305            long time = seconds << 32 | fraction;
306            return time;
307        }
308    
309        /***
310         * Computes a hashcode for this Timestamp. The result is the exclusive
311         * OR of the two halves of the primitive <code>long</code> value
312         * represented by this <code>TimeStamp</code> object. That is, the hashcode
313         * is the value of the expression:
314         * <blockquote><pre>
315         * (int)(this.ntpValue()^(this.ntpValue() >>> 32))
316         * </pre></blockquote>
317         *
318         * @return  a hash code value for this object.
319         */
320        @Override
321        public int hashCode()
322        {
323            return (int) (ntpTime ^ (ntpTime >>> 32));
324        }
325    
326        /***
327         * Compares this object against the specified object.
328         * The result is <code>true</code> if and only if the argument is
329         * not <code>null</code> and is a <code>Long</code> object that
330         * contains the same <code>long</code> value as this object.
331         *
332         * @param   obj   the object to compare with.
333         * @return  <code>true</code> if the objects are the same;
334         *          <code>false</code> otherwise.
335         */
336        @Override
337        public boolean equals(Object obj)
338        {
339            if (obj instanceof TimeStamp) {
340                return ntpTime == ((TimeStamp) obj).ntpValue();
341            }
342            return false;
343        }
344    
345        /***
346         * Converts this <code>TimeStamp</code> object to a <code>String</code>.
347         * The NTP timestamp 64-bit long value is represented as hex string with
348         * seconds separated by fractional seconds by a decimal point;
349         * e.g. c1a089bd.fc904f6d <=> Tue, Dec 10 2002 10:41:49.986
350         *
351         * @return NTP timestamp 64-bit long value as hex string with seconds
352         * separated by fractional seconds.
353         */
354        @Override
355        public String toString()
356        {
357            return toString(ntpTime);
358        }
359    
360        /***
361         * Left-pad 8-character hex string with 0's
362         *
363         * @param buf - StringBuilder which is appended with leading 0's.
364         * @param l - a long.
365         */
366        private static void appendHexString(StringBuilder buf, long l)
367        {
368            String s = Long.toHexString(l);
369            for (int i = s.length(); i < 8; i++)
370                buf.append('0');
371            buf.append(s);
372        }
373    
374        /***
375         * Converts 64-bit NTP timestamp value to a <code>String</code>.
376         * The NTP timestamp value is represented as hex string with
377         * seconds separated by fractional seconds by a decimal point;
378         * e.g. c1a089bd.fc904f6d <=> Tue, Dec 10 2002 10:41:49.986
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            DateFormat formatter = null;
408            if (simpleFormatter != null) {
409                formatter = simpleFormatter.get();
410            }
411            if (formatter == null) {
412                // No cache yet, or cached formatter GC'd
413                formatter = new SimpleDateFormat(NTP_DATE_FORMAT, Locale.US);
414                formatter.setTimeZone(TimeZone.getDefault());
415                simpleFormatter = new SoftReference<DateFormat>(formatter);
416            }
417            Date ntpDate = getDate();
418            synchronized (formatter) {
419                return formatter.format(ntpDate);
420            }
421        }
422    
423        /***
424         * Converts this <code>TimeStamp</code> object to a <code>String</code>
425         * of the form:
426         * <blockquote><pre>
427         * EEE, MMM dd yyyy HH:mm:ss.SSS UTC</pre></blockquote>
428         * See java.text.SimpleDataFormat for code descriptions.
429         *
430         * @return  a string representation of this date in UTC.
431         */
432        public String toUTCString()
433        {
434            DateFormat formatter = null;
435            if (utcFormatter != null)
436                formatter = utcFormatter.get();
437            if (formatter == null) {
438                // No cache yet, or cached formatter GC'd
439                formatter = new SimpleDateFormat(NTP_DATE_FORMAT + " 'UTC'",
440                        Locale.US);
441                formatter.setTimeZone(TimeZone.getTimeZone("UTC"));
442                utcFormatter = new SoftReference<DateFormat>(formatter);
443            }
444            Date ntpDate = getDate();
445            synchronized (formatter) {
446                return formatter.format(ntpDate);
447            }
448        }
449    
450        /***
451         * Compares two Timestamps numerically.
452         *
453         * @param   anotherTimeStamp - the <code>TimeStamp</code> to be compared.
454         * @return  the value <code>0</code> if the argument TimeStamp is equal to
455         *          this TimeStamp; a value less than <code>0</code> if this TimeStamp
456         *          is numerically less than the TimeStamp argument; and a
457         *          value greater than <code>0</code> if this TimeStamp is
458         *          numerically greater than the TimeStamp argument
459         *          (signed comparison).
460         */
461        public int compareTo(TimeStamp anotherTimeStamp)
462        {
463            long thisVal = this.ntpTime;
464            long anotherVal = anotherTimeStamp.ntpTime;
465            return (thisVal < anotherVal ? -1 : (thisVal == anotherVal ? 0 : 1));
466        }
467    
468    }