The official statement of the author of Joda-time himself is to migrate as soon as Java-8 is available. See also this citation from the website:
Note that Joda-Time is considered to be a largely “finished” project.
No major enhancements are planned. If using Java SE 8, please migrate
to java.time (JSR-310).
So the short answer to your question is: YES (deprecated). However, keep in mind that some features like Joda-Interval
or PeriodType
or PeriodFormatter
are not available in Java-8 so you have to write your own partially ugly workarounds, see also my SO-post about differences between Joda-Time and JSR-310.
Side remarks about the future of both libraries:
What does "finished" means in this context?
Well, you can compare the Joda-issue 254 with my small discussion on Twitter. I think people should rather set down their expectations to any major enhancement of Joda-Time. Please also consider that the future development resources regarding Joda-Time are limited (lack of manpower). And let's be honest: Most releases since Joda-Time in year 2008 rather have the character of bugfix releases (with the exception of 2.0).
On the other side: The innovation speed of JSR-310 will probably not be very high, too (because it is already big, and because Oracle is here the decisive player and a date-time-library is in general not considered as the central cornerstone of any Java-release). So there is always some space left for an external library in the future to supply missing features, for example (in alphabetical order):
- Threeten-Extra (as the favourite of Basil Bourque, see his comment)
- Time4J (my own extension, interoperability issue solved in summer 2015)
Should I use it exclusively instead of the old classes?
No, no need to exclude old classes. The old java.util.Date/.Calendar work the same, unchanged. The have not been deprecated.
You can mix and match all three frameworks (old classes, Joda-Time, and java.time). Just be careful of some identical or similar class names -- watch your import
statements!
See The Tutorial, Legacy Date-Time Code.
Also, the ThreeTen-Extra project extends java.time with additional features. The "ThreeTen" refers to JSR 310 that defines java.time.
Should I replace existing usages of old classes whereever I spot them because the new stuff is so much better?
If the old code is working as intended, then no need to change now.
If you were concerned about that old code possibly not handling time zones properly or have been wanting to do more localization, the you might want to rework them using java.time. Even then, remember that you can easily convert between j.u.Date and Instant. So you could leave your business logic as-is with j.u.Date/.Calendar and change only the user-presentation code to use java.time.
Should I refrain from using java.util.Calendar, java.util.Date, java.sql.Date and java.text.DateFormat in favor of the new API all together OR are there use cases where the old classes are still preferable?
You will need the old classes for interoperation with old code and libraries that expect the old types. Again, the old classes are not deprecated and are not going away. They will probably never go away given their extensive usage and the Java team’s top priority being preservation of backward-compatibility.
The new java.time classes are far superior, that's why they were added. And they are more logical and easier to use. So yes, it would be beneficial and pleasant to learn how to use them. But not urgent. In a crunch, write code the old way you are used to. When you can afford the time to learn (Tutorial) and to perform extra testing, start to use the new classes.
A newbie programmer should certainly focus their learning on java.time.
Has the Joda Time API become obsolete thanks to the new Date API similarly to the substitution of Guava FluentIterable by Java 8 stream API?
Joda-Time was the inspiration for java.time. The same folks invented both. They intend for java.time to be their "2.0" re-invention of Joda-Time, what they would have done then if they knew what they know now. They have said Joda-Time users should transition over to java.time.
That said, Joda-Time is not going away. It is still worked on, still updated with bug fixes and fresh tz
time zone data. And it is very important to the large Android community who have no other decent date-time library (that I know of). So you can continue to rely on Joda-Time, no urgent need to rip out old code, but expect no new features or enhancements.
Joda-Time is well-worn and proven while java.time has had a few minor bugs and kinks to work out. Joda-Time and java.time each have features the other lacks. So personally, I mix-and-match to best fit. I rely on Joda-Time while dabbling with java.time.
Plan an eventual transition to java.time but no rush, no panic.
Best Answer
Common features
a) Both libraries use immutable types. Joda-Time also offers additional mutable types like
MutableDateTime
.b) Furthermore: Both libraries are inspired by the design study "TimeAndMoney" from Eric Evans or ideas from Martin Fowler about domain driven style so they strive more or less for a fluent programming style (although not always perfect ;-)).
c) With both libraries we get a real calendar date type (called
LocalDate
), a real wall time type (calledLocalTime
) and the composition (calledLocalDateTime
). That is a very big win compared with oldjava.util.Calendar
andjava.util.Date
.d) Both libraries use a method-centric approach meaning they encourage the user to use
getDayOfYear()
instead ofget(DAY_OF_YEAR)
. This causes a lot of extra methods compared withjava.util.Calendar
(although latter is not type-safe at all due to excessive use of ints).Performance
See the other answer by @OO7 pointing to the analysis of Mikhail Vorontsov although point 3 (exception catching) is probably obsolete - see this JDK-bug. The different performance (which is in general favour of JSR-310) is mainly due to the fact that the internal implementation of Joda-Time always use a machine-time-like long-primitive (in milliseconds).
Null
Joda-Time often use NULL as default for system timezone, default locale, current timestamp etc. while JSR-310 almost always rejects NULL values.
Precision
JSR-310 handles nanosecond precision while Joda-Time is limited to millisecond precision.
Supported fields:
An overview about supported fields in Java-8 (JSR-310) is given by some classes in the temporal-package (for example ChronoField and WeekFields) while Joda-Time is rather weak on this area - see DateTimeFieldType. The biggest lack of Joda-Time is here the absence of localized week-related fields. A common feature of both field implementation design is that both are based on values of type long (no other types, not even enums).
Enum
JSR-310 offers enums like
DayOfWeek
orMonth
while Joda-Time does not offer this because it was mainly developed in years 2002-2004 before Java 5.Zone API
a) JSR-310 offers more timezone features than Joda-Time. Latter is not able to yield a programmatical access to the history of timezone offset transitions while JSR-310 is capable to do this.
b) For your information: JSR-310 has moved its internal timezone repository to a new location and a different format. The old library folder lib/zi does not exist any more.
Adjuster vs. Property
JSR-310 has introduced the
TemporalAdjuster
-interface as a formalized way to externalize temporal calculations and manipulations, especially for library or framework-writers this is a nice and relative easy way to embed new extensions of JSR-310 (a kind of equivalent to static helper classes for formerjava.util.Date
).For most users however, this feature has very limited value because the burden to write code is still with the user. Built-in solutions based on the new
TemporalAdjuster
-concept are not so many, there is currently only the helper classTemporalAdjusters
with a limited set of manipulations (and the enumsMonth
or other temporal types).Joda-Time offers a field-package but practice has shown evidence that new field implementations are very hard to code. On the other side Joda-Time offers so-called properties which make some manipulations much easier and more elegant than in JSR-310, for example property.withMaximumValue().
Calendar systems
JSR-310 offers 4 extra calendar systems. The most interesting one is Umalqura (used in Saudi Arabia). The other 3 are: Minguo (Taiwan), Japanese (only the modern calendar since 1871!) and ThaiBuddhist (only correct after 1940).
Joda-Time offers an Islamic calendar based on calculatory base - not a sighting-based calendar like Umalqura. Thai-Buddhist is also offered by Joda-Time in a similar form, Minguo and the japanese one not. Otherwise Joda-Time offers coptic and ethiopic calendar, too (but without any support for internationalization).
More interesting for Europeans: Joda-Time also offers a Gregorian, Julian and mixed-gregorian-julian calendar. However, the practical value for real historical calculations is limited because important features like different year starts in date history are not supported at all (the same criticism is valid for old
java.util.GregorianCalendar
).Other calendars like Hebrew or Persian or Hindu are completely missing in both libraries.
Epoch days
JSR-310 has the class JulianFields while Joda-Time (version 2.0) offers some helper methods in the class DateTimeUtils.
Clocks
JSR-310 has no interface (a design mistake) but an abstract class
java.time.Clock
which can be used for any clock dependency injection. Joda-Time offers the interface MillisProvider and some helper methods in DateTimeUtils instead. So this way Joda-Time is also capable of supporting test-driven models with different clocks (mocking etc.).Duration arithmetic
Both libraries support the calculation of time distances in one or more temporal units. However, when handling single-unit-durations the JSR-310-style is obviously nicer (and long-based instead of using int):
JSR-310 =>
long days = ChronoUnit.DAYS.between(date1, date2);
Joda-Time =>
int days = DAYS.daysBetween(date1, date2).getDays();
Handling of multiple-unit-durations are also different. Even the calculation results can differ - see this closed Joda-Time issue. While JSR-310 use a very simple and limited approach to use just the classes
Period
(duration based on years, months and days) andDuration
(based on seconds and nanoseconds), Joda-Time uses a more sophisticated way using the classPeriodType
in order to control in which units a duration (Joda-Time call it "Period") shall be expressed. While thePeriodType
-API is somehow awkward to use a similar way is not offered by JSR-310 at all. Especially it is not yet possible in JSR-310 to define mixed date and time durations (based on days and hours for example). So be warned if it comes to migration from one library to another. The libraries in discussion are incompatible - despite of partially same class names.Intervals
JSR-310 does not support this feature while Joda-Time has limited support. See also this SO-answer.
Formatting and Parsing
Best way to compare both libraries is to view the equal-named classes DateTimeFormatterBuilder (JSR-310) and DateTimeFormatterBuilder (Joda-Time). The JSR-310-variant is a little bit more powerful (can also handle any kind of
TemporalField
provided the field implementor has managed to code some extension points like resolve()). Most important difference is however - in my opinion:JSR-310 can much better parse timezone names (format pattern symbol z) while Joda-Time could not do this at all in its earlier versions and now only in a very limited way.
Another advantage of JSR-310 is support for standalone month names which is important in languages like Russian or Polish etc. Joda-Time has no access to such resources - not even on Java-8 platforms.
The pattern syntax in JSR-310 is also more flexible than in Joda-Time, allows for optional sections (using square brackets), is more orientated towards CLDR-standard and offers padding (letter symbol p) and more fields.
Otherwise it should be noted that Joda-Time can format durations using PeriodFormatter. JSR-310 cannot do this.
Hope this overview helps. All the gathered information is mainly there due to my efforts and investigations how to design and implement a better date-and-time library (nothing is perfect).
Update from 2015-06-24:
Meanwhile I have found the time to write and publish a tabular overview for different time libraries in Java. The tables also contain a comparison between Joda-Time v2.8.1 and Java-8 (JSR-310). It is more detailed than this post.