Deprecate public APIs referencing Joda Time

[headius]

This will be a series of commits to deprecate and replace all public APIs referencing classes from the Joda Time library and providing new versions based on java.time.

We will need to maintain these deprecated methods for a while before we can remove them and Joda Time from JRuby.

Some helpful guides:

• Mapping joda to java.time types, but not much help on how to convert: https://blog.joda.org/2014/11/converting-from-joda-time-to-javatime.html
• timeywimey a tiny library for converting some joda types to and from java.time: https://github.com/meetup/timeywimey

[headius]

@kares I think you may have looked into a full conversion in the past, perhaps you know how to handle some of the other APIs we have that use Joda types?

[kares]

@headius great effort, what I ended up with with was pretty much the same as you - did not find direct replacement for JRuby's various use-cases of JODA DateTime. in some places it made sense to use ZonedTime but (e.g. in RubyTime although sometimes it's really a LocalTime we want), while others (RubyDate/RubyDateTime) seemed to need something different.

have you looked at what TruffleRuby is using in the backend for the Ruby date/time types - they weren't using Java 8 time APIs back when I looked but now they should be?

[headius]

@kares Last time I looked they were using the Java 8 time API and ZonedDateTime. Do you remember any specific examples of behavior that needed local time instead? I am not planning to carry this conversion forward for 9.3 but we'll need to do it at some point.

[headius]

I have pushed my last changes, which deprecate all remaining public-facing APIs with Joda classes and suppress or fix deprecation warnings internally to JRuby.

There will be some churn using the new java.time APIs since we still use Joda internally but this at least provides a migration path for third-party libraries. We can incrementally convert the internals to java.time in point releases leading up to a complete conversion by 9.4.

[headius]

This is getting punted to 9.4, sadly.

The last couple commits led me to discover that java.time's time zone support is significantly stricter and narrower than the time zone support in Joda. It may not be possible to do a direct conversion from Joda to java.time without extending how java.time deals with custom or legacy time zone specifications. There may be time zone info providers out there for java.time that help fill in the gaps, but for now it is not possible to proceed with this conversion.

A couple examples:

• A TZ of "AST-3:00:00" should be treated as a time zone named "AST" with an offset of +3, but that does not correspond to any standard time zone ("AST" in java.time is Anchorage Standard Time at -10). As a result, we can only represent it in java.time as a ZoneOffset of +3 with no name.
• A TZ of "PST8:00:00" should be treated as a time zone named "PST" with an offset of -8, which matches Pacific Standard Time, but when parsed in this way it ends up as a nameless zone at -8.
• A TZ of "PDT" should be treated as Pacific Daylight Time but this ID does not roundtrip through java.time without error.

I believe now we will have to attempt the conversion from the inside out, matching behavior using java.time before we decide that we can ditch Joda. This won't happen for 9.3, and since we do not yet know whether we are able to use java.time to represent Ruby Time and Date, we cannot deprecate the Joda APIs.

[headius]

I have rebased this on latest master but the problems remain: java.time is not a drop-in replacement due to strict and limited time zone support, so even if we deprecate the Joda Time APIs we can't start using java.time internally yet.

I find the java.time API to be inscrutable so I'm not sure how to proceed.