Philadelphia 2.0.0: Improvements in date and time handling

[jvirtanen]

Until 2.0.0, Philadelphia has relied on the Joda-Time library for representing dates and times. 2.0.0 replaces usages of Joda-Time's MutableDateTime with the new FIXTimestamp class. Why the change? Moreover, why hasn't Philadelphia used java.time all along?

Why did Philadelphia initially choose Joda-Time?

Java 8 was released in 2014. Philadelphia was born in 2015. The first Philadelphia release, 0.1.0 in late 2015, still required a Java 7 runtime environment. From 0.2.0 onwards, Philadelphia started to require a Java 8 runtime environment instead.

Before Java 8, Joda-Time was a de facto standard for date and time handling. It provided a much better API than Java's built-in Date class. Joda-Time was so influential that java.time, introduced in Java 8, is essentially just a refinement of it.

The MutableDateTime class in particular made Joda-Time feel like a good fit for Philadelphia. As one of the main objectives of this project has always been to avoid memory allocation on the fast path, a mutable date and time container makes sense. This also explains why java.time has never felt like a viable choice: it only provides immutable date and time containers.

Why did Philadelphia move away from Joda-Time?

From the beginning, Joda-Time has been the only third-party dependency of Philadelphia. Having a third-party dependency in the first place has always been annoying. Until 1.2.0 it was also cumbersome, as each Philadelphia release had a transitive dependency on a specific Joda-Time release. Joda-Time being one of the most common Java libraries, it was likely that many applications would already have Joda-Time on their runtime classpath and that it would be a different version than what Philadelphia depended on.

There has also been the question of performance. Although I hadn't actually compared Joda-Time to e.g. java.time in the context of Philadelphia, surprising performance regressions, such as 39c3968, always made me feel that there must be further room for improvement.

Finally, @ddimtirov gave a concrete suggestion to move away from Joda-Time during 2.0.0 development.

How is Philadelphia after Joda-Time?

Philadelphia is now faster and thinner. Based on the performance regression test, date and time operations can be now up to 2-3x as fast as before. Applications that do not otherwise need Joda-Time are also hundreds of kilobytes smaller.

The new FIXTimestamp class tries to combine the best parts of Joda-Time and java.time into a lean package that is tailored for Philadelphia's needs. Like Joda-Time's MutableDateTime, it is a mutable date and time container. However, like java.time, it stores the individual date and time fields separately, which makes it much faster than Joda-Time. Finally, it tries to follow the naming conventions of java.time so that it would feel familiar to 2022's developers.