    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.text.DateFormat;
    022import java.text.SimpleDateFormat;
    023import java.util.Date;
    024import java.util.Locale;
    025import java.util.TimeZone;
    026
    027/***
    028 * TimeStamp class represents the Network Time Protocol (NTP) timestamp
    029 * as defined in RFC-1305 and SNTP (RFC-2030). It is represented as a
    030 * 64-bit unsigned fixed-point number in seconds relative to 0-hour on 1-January-1900.
    031 * The 32-bit low-order bits are the fractional seconds whose precision is
    032 * about 200 picoseconds. Assumes overflow date when date passes MAX_LONG
    033 * and reverts back to 0 is 2036 and not 1900. Test for most significant
    034 * bit: if MSB=0 then 2036 basis is used otherwise 1900 if MSB=1.
    035 * <p>
    036 * Methods exist to convert NTP timestamps to and from the equivalent Java date
    037 * representation, which is the number of milliseconds since the standard base
    038 * time known as "the epoch", namely January 1, 1970, 00:00:00 GMT.
    039 * </p>
    040 *
    041 * @see java.util.Date
    042 */
    043public class TimeStamp implements java.io.Serializable, Comparable<TimeStamp>
    044{
    045    private static final long serialVersionUID = 8139806907588338737L;
    046
    047    /**
    048     * baseline NTP time if bit-0=0 is 7-Feb-2036 @ 06:28:16 UTC
    049     */
    050    protected static final long msb0baseTime = 2085978496000L;
    051
    052    /**
    053     *  baseline NTP time if bit-0=1 is 1-Jan-1900 @ 01:00:00 UTC
    054     */
    055    protected static final long msb1baseTime = -2208988800000L;
    056
    057    /**
    058     * Default NTP date string format. E.g. Fri, Sep 12 2003 21:06:23.860.
    059     * See <code>java.text.SimpleDateFormat</code> for code descriptions.
    060     */
    061    public static final String NTP_DATE_FORMAT = "EEE, MMM dd yyyy HH:mm:ss.SSS";
    062
    063    /**
    064     * NTP timestamp value: 64-bit unsigned fixed-point number as defined in RFC-1305
    065     * with high-order 32 bits the seconds field and the low-order 32-bits the
    066     * fractional field.
    067     */
    068    private final long ntpTime;
    069
    070    private DateFormat simpleFormatter;
    071    private DateFormat utcFormatter;
    072
    073    // initialization of static time bases
    074    /*
    075    static {
    076        TimeZone utcZone = TimeZone.getTimeZone("UTC");
    077        Calendar calendar = Calendar.getInstance(utcZone);
    078        calendar.set(1900, Calendar.JANUARY, 1, 0, 0, 0);
    079        calendar.set(Calendar.MILLISECOND, 0);
    080        msb1baseTime = calendar.getTime().getTime();
    081        calendar.set(2036, Calendar.FEBRUARY, 7, 6, 28, 16);
    082        calendar.set(Calendar.MILLISECOND, 0);
    083        msb0baseTime = calendar.getTime().getTime();
    084    }
    085    */
    086
    087    /***
    088     * Constructs a newly allocated NTP timestamp object
    089     * that represents the native 64-bit long argument.
    090     * @param ntpTime the timestamp
    091     */
    092    public TimeStamp(final long ntpTime)
    093    {
    094        this.ntpTime = ntpTime;
    095    }
    096
    097    /***
    098     * Constructs a newly allocated NTP timestamp object
    099     * that represents the value represented by the string
    100     * in hexdecimal form (e.g. "c1a089bd.fc904f6d").
    101     * @param hexStamp the hex timestamp
    102     *
    103     * @throws NumberFormatException - if the string does not contain a parsable timestamp.
    104     */
    105    public TimeStamp(final String hexStamp) throws NumberFormatException
    106    {
    107        ntpTime = decodeNtpHexString(hexStamp);
    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(final 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        final 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 the input time
    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(final long ntpTimeValue)
    186    {
    187        final 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        final 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        }
    207        // use base: 1-Jan-1900 @ 01:00:00 UTC
    208        return msb1baseTime + (seconds * 1000) + fraction;
    209    }
    210
    211    /***
    212     * Helper method to convert Java time to NTP timestamp object.
    213     * Note that Java time (milliseconds) by definition has less precision
    214     * then NTP time (picoseconds) so converting Ntptime to Javatime and back
    215     * to Ntptime loses precision. For example, Tue, Dec 17 2002 09:07:24.810
    216     * is represented by a single Java-based time value of f22cd1fc8a, but its
    217     * NTP equivalent are all values from c1a9ae1c.cf5c28f5 to c1a9ae1c.cf9db22c.
    218     * @param   date   the milliseconds since January 1, 1970, 00:00:00 GMT.
    219     * @return NTP timestamp object at the specified date.
    220     */
    221    public static TimeStamp getNtpTime(final long date)
    222    {
    223        return new TimeStamp(toNtpTime(date));
    224    }
    225
    226    /***
    227     * Constructs a NTP timestamp object and initializes it so that
    228     * it represents the time at which it was allocated, measured to the
    229     * nearest millisecond.
    230     * @return NTP timestamp object set to the current time.
    231     * @see     java.lang.System#currentTimeMillis()
    232     */
    233    public static TimeStamp getCurrentTime()
    234    {
    235        return getNtpTime(System.currentTimeMillis());
    236    }
    237
    238    /***
    239     * Convert NTP timestamp hexstring (e.g. "c1a089bd.fc904f6d") to the NTP
    240     * 64-bit unsigned fixed-point number.
    241     * @param hexString the string to convert
    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(final String hexString)
    247            throws NumberFormatException
    248    {
    249        if (hexString == null) {
    250            throw new NumberFormatException("null");
    251        }
    252        final int ind = hexString.indexOf('.');
    253        if (ind == -1) {
    254            if (hexString.length() == 0) {
    255                return 0;
    256            }
    257            return Long.parseLong(hexString, 16) << 32; // no decimal
    258        }
    259
    260        return Long.parseLong(hexString.substring(0, ind), 16) << 32 |
    261                Long.parseLong(hexString.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(final 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(final long t)
    285    {
    286        final 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        final long fraction = ((baseTime % 1000) * 0x100000000L) / 1000;
    297
    298        if (useBase1) {
    299            seconds |= 0x80000000L; // set high-order bit if msb1baseTime 1900 used
    300        }
    301
    302        final 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     * {@code (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(final 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(final StringBuilder buf, final long l)
    364    {
    365        final 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     * @param ntpTime the 64 bit timestamp
    378     *
    379     * @return NTP timestamp 64-bit long value as hex string with seconds
    380     * separated by fractional seconds.
    381     */
    382    public static String toString(final long ntpTime)
    383    {
    384        final StringBuilder buf = new StringBuilder();
    385        // high-order second bits (32..63) as hexstring
    386        appendHexString(buf, (ntpTime >>> 32) & 0xffffffffL);
    387
    388        // low-order fractional seconds bits (0..31) as hexstring
    389        buf.append('.');
    390        appendHexString(buf, ntpTime & 0xffffffffL);
    391
    392        return buf.toString();
    393    }
    394
    395    /***
    396     * Converts this <code>TimeStamp</code> object to a <code>String</code>
    397     * of the form:
    398     * <blockquote><pre>
    399     * EEE, MMM dd yyyy HH:mm:ss.SSS</pre></blockquote>
    400     * See java.text.SimpleDataFormat for code descriptions.
    401     *
    402     * @return  a string representation of this date.
    403     */
    404    public String toDateString()
    405    {
    406        if (simpleFormatter == null) {
    407            simpleFormatter = new SimpleDateFormat(NTP_DATE_FORMAT, Locale.US);
    408            simpleFormatter.setTimeZone(TimeZone.getDefault());
    409        }
    410        final Date ntpDate = getDate();
    411        return simpleFormatter.format(ntpDate);
    412    }
    413
    414    /***
    415     * Converts this <code>TimeStamp</code> object to a <code>String</code>
    416     * of the form:
    417     * <blockquote><pre>
    418     * EEE, MMM dd yyyy HH:mm:ss.SSS UTC</pre></blockquote>
    419     * See java.text.SimpleDataFormat for code descriptions.
    420     *
    421     * @return  a string representation of this date in UTC.
    422     */
    423    public String toUTCString()
    424    {
    425        if (utcFormatter == null) {
    426            utcFormatter = new SimpleDateFormat(NTP_DATE_FORMAT + " 'UTC'",
    427                    Locale.US);
    428            utcFormatter.setTimeZone(TimeZone.getTimeZone("UTC"));
    429        }
    430        final Date ntpDate = getDate();
    431        return utcFormatter.format(ntpDate);
    432    }
    433
    434    /***
    435     * Compares two Timestamps numerically.
    436     *
    437     * @param   anotherTimeStamp - the <code>TimeStamp</code> to be compared.
    438     * @return  the value <code>0</code> if the argument TimeStamp is equal to
    439     *          this TimeStamp; a value less than <code>0</code> if this TimeStamp
    440     *          is numerically less than the TimeStamp argument; and a
    441     *          value greater than <code>0</code> if this TimeStamp is
    442     *          numerically greater than the TimeStamp argument
    443     *          (signed comparison).
    444     */
    445    @Override
    446    public int compareTo(final TimeStamp anotherTimeStamp)
    447    {
    448        final long thisVal = this.ntpTime;
    449        final long anotherVal = anotherTimeStamp.ntpTime;
    450        return (thisVal < anotherVal ? -1 : (thisVal == anotherVal ? 0 : 1));
    451    }
    452
    453}