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.lang.ref.SoftReference;
022import java.text.DateFormat;
023import java.text.SimpleDateFormat;
024import java.util.Date;
025import java.util.Locale;
026import 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: 658518 $ $Date: 2008-05-21 02:04:30 +0100 (Wed, 21 May 2008) $
044 * @see java.util.Date
045 */
046public class TimeStamp implements java.io.Serializable, Comparable // TODO add comparable type?
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 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 - StringBuffer which is appended with leading 0's.
364     * @param l - a long.
365     */
366    private static void appendHexString(StringBuffer 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        StringBuffer buf = new StringBuffer();
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    /***
469     * Compares this TimeStamp to another Object.  If the Object is a TimeStamp,
470     * this function behaves like <code>compareTo(TimeStamp)</code>.  Otherwise,
471     * it throws a <code>ClassCastException</code> (as TimeStamps are comparable
472     * only to other TimeStamps).
473     *
474     * @param   o the <code>Object</code> to be compared.
475     * @return  the value <code>0</code> if the argument is a TimeStamp
476     *      numerically equal to this TimeStamp; a value less than
477     *      <code>0</code> if the argument is a TimeStamp numerically
478     *      greater than this TimeStamp; and a value greater than
479     *      <code>0</code> if the argument is a TimeStamp numerically
480     *      less than this TimeStamp.
481     * @exception ClassCastException if the argument is not a
482     *        <code>TimeStamp</code>.
483     * @see     java.lang.Comparable
484     */
485    public int compareTo(Object o)
486    {
487        return compareTo((TimeStamp) o);
488    }
489
490}