How to Watch Next: Leap Second in Java

What is a Leap Second?

As some know - there will be a new leap second at the end of this month. Leap seconds are inserted into the standard UTC time scale by help of label "60" either at the end of June or December (exceptionally also in March and September) in irregular intervals in order to compensate for the slightly increasing difference between an astronomical day and the pulse of modern atomic clocks we now use for time-keeping.

Initial Situation

When I asked myself in year 2012 (where the last leap second happened) how to watch it using Java-based software the answer was simply: Not possible. At least not possible with any kind of standard tool. As with most software today, Java is totally ignorant towards leap seconds and pretends that they don't exist. There is no way to let Java print timestamps like "2015-06-30T23:59:60Z". Note that Java-8 with its new time library (JSR-310, java.time-package) does not offer this feature, too.

For standard business purposes this approach is fine. From a scientific point of view however, this is not satisfying. Of course, these rare leap seconds still exist. When it comes to clock synchronization even leap-second-ignorant software has to pay some attribution if monotonicity is important. Any clock will sooner or later be synchronized such that leap seconds will be taken into account, often by setting the clock one second back. NTP time servers will usually repeat the timestamp "2015-06-30T23:59:59Z" and send in advance a so called leap indicator flag. This flag does not directly indicate the current timestamp as leap second but is only intended to be an announcement flag. So even NTP tries to hide leap seconds in some way. And some NTP servers like those from Google apply internal smearing algorithms (by slightly prolonging the second over a day) in order to avoid reporting any leap second at all.

Decision for a New Library

So I decided to develop a new time library named Time4J  to solve this issue. First I had to set up a new infrastructure around a built-in configurable leap second table, then a new class <code>net.time4j.Moment</code> capable of holding a leap second as internal state. A SNTP-based clock yielding <code>Moment</code>-timestamps was developed and successfully tested during the last leap second in 2012. Since leap seconds are also reported by the well-known IANA-TZDB (standard timezone repository) I decided to develop a mechanism to apply the whole TZDB and its leap seconds on the class <code>net.time4j.Moment</code>. Finally I had even set up a new format and parse engine from the scratch to enable formatting and parsing of leap seconds in any timezone. A lot of work but the existing Java-software was not useable at all, not even as starting point.

Recently I also developed a monotonic clock which enables to watch a leap second offline. Keep in mind that any clock - even NTP - are no reliable sources to watch a leap second in live connection. Fortunately Java offers at least <code>System.nanoTime()</code> which accesses the monotonic clock of operating system (if available). So I used this as a base of the new monotonic clock of Time4J which can connect to a NTP time server before a leap second will happen.

How Does Time4J Help?

import net.time4j.Moment;
import net.time4j.Month;
import net.time4j.PlainDate;
import net.time4j.SI;
import net.time4j.SystemClock;
import net.time4j.base.TimeSource;
import net.time4j.clock.FixedClock;
import net.time4j.format.expert.ChronoFormatter;
import net.time4j.format.expert.PatternType;
import net.time4j.tz.olson.AMERICA;

import java.util.Locale;
import java.util.concurrent.ScheduledFuture;
import java.util.concurrent.ScheduledThreadPoolExecutor;
import java.util.concurrent.TimeUnit;

public class DZone {

    static TimeSource<Moment> clock;
    static ScheduledThreadPoolExecutor executor;
    static ScheduledFuture<?> future;

    public static void main(String[] args) throws Exception {

        // when is the next leap second?
        Moment ls = SystemClock.currentMoment().with(Moment.nextLeapSecond());

        if (ls == null) {
            // ooops, we are now too late and after last known leap second,
            // so let us set it directly
            ls = 
               PlainDate.of(2015, Month.JUNE, 30).atTime(23, 59, 59)
               .atUTC().plus(1, SI.SECONDS);
        }

        // move 5 seconds earlier
        ls = ls.minus(5, SI.SECONDS);

        // let's start our monotonic clock at determined fixed time
        clock = SystemClock.MONOTONIC.synchronizedWith(FixedClock.of(ls));

        // finally we observe our clock every second for 10 times
        executor = new ScheduledThreadPoolExecutor(15);
        future = executor.scheduleAtFixedRate(
            new ClockTask(),
            0,
            1,
            TimeUnit.SECONDS);

    }

    static class ClockTask implements Runnable {
        private int attempt = 1;

        public void run() {
            Moment moment = clock.currentTime();
            String time =
                ChronoFormatter.ofMomentPattern(
                    "MMM/dd/uuuu hh:mm:ss a XXX",
                    PatternType.CLDR,
                    Locale.ENGLISH,
                    AMERICA.NEW_YORK
                ).format(moment);
            String flag = moment.isLeapSecond() ? " [leap second]" : "";

            System.out.println(time + flag);

            attempt++;
            if (attempt > 10) {
                future.cancel(false);
            }
        }
    }
}

/*
output:

Jun/30/2015 07:59:55 PM -04:00
Jun/30/2015 07:59:56 PM -04:00
Jun/30/2015 07:59:57 PM -04:00
Jun/30/2015 07:59:58 PM -04:00
Jun/30/2015 07:59:59 PM -04:00
Jun/30/2015 07:59:60 PM -04:00 [leap second]
Jun/30/2015 08:00:00 PM -04:00
Jun/30/2015 08:00:01 PM -04:00
Jun/30/2015 08:00:02 PM -04:00
Jun/30/2015 08:00:03 PM -04:00
 */

For a real-life scenario you can just replace the clock this way (SNTP-example):

        SntpConnector sntp = new SntpConnector("ptbtime1.ptb.de");
        sntp.connect();
        clock = sntp;

Conclusion

Time4J does not try to hide the reality but gives you also the freedom to decide if you want to handle leap seconds or not. You can even switch off this feature completely by setting an appropriate system property. As side effect, a library has been developed which does not need to be afraid of any comparison  with other existing libraries like JSR-310 (java.time-package in Java-8) or Joda-Time.