Should I use Java date and time classes or go with a 3rd party library like Joda Time?

EDIT: Now that Java 8 has been released, if you can use that, do so! java.time is even cleaner than Joda Time, in my view. However, if you're stuck pre-Java-8, read on...

Max asked for the pros and cons of using Joda...

Pros:

• It works, very well. I strongly suspect there are far fewer bugs in Joda than the standard Java libraries. Some of the bugs in the Java libraries are really hard (if not impossible) to fix due to the design.
• It's designed to encourage you to think about date/time handling in the right way - separating the concept of a "local time" (e.g "wake me at 7am wherever I am") and an instant in time ("I'm calling James at 3pm PST; it may not be 3pm where he is, but it's the same instant")
• I believe it makes it easier to update the timezone database, which does change relatively frequently
• It has a good immutability story, which makes life a lot easier IME.
• Leading on from immutability, all the formatters are thread-safe, which is great because you almost always want to reuse a single formatter through the application
• You'll have a head-start on learning java.time in Java 8, as they're at least somewhat similar

Cons:

• It's another API to learn (although the docs are pretty good)
• It's another library to build against and deploy
• When you use Java 8, there's still some work to migrate your skills
• I've failed to use the DateTimeZoneBuilder effectively in the past. This is a very rare use case though.

To respond to the oxbow_lakes' idea of effectively building your own small API, here are my views of why this is a bad idea:

• It's work. Why do work when it's already been done for you?
• A newcomer to your team is much more likely to be familiar with Joda than with your homegrown API
• You're likely to get it wrong for anything beyond the simplest uses... and even if you initially think you only need simple functionality, these things have a habit of growing more complicated, one tiny bit at a time. Date and time manipulation is hard to do properly. Furthermore, the built-in Java APIs are hard to use properly - just look at the rules for how the calendar API's date/time arithmetic works. Building anything on top of these is a bad idea rather than using a well-designed library to start with.

Well, unless you intend to wait for Java 8, hoping that they will implement a better API for manipulating date and time, yes, please, use Joda-Time. It's time saving and avoid many headaches.

The answer is: it depends

JODA (and JSR-310) is a fully-functional date/time library, including support for use with multiple calendar systems.

Personally I found JODA to be a step too far in terms of complexity for what I need. The 2 principal (IMHO) mistakes in the standard java Date and Calendar classes are:

1. They are mutable
2. They mix up the concept of a Year-Month-Day from an Instant-In-Time

Although these are addressed by JODA, you'll find it quite easy to roll your own classes for YearMonthDay and Instant, which both use the java classes under the hood for actual "calendrical" calculations. Then you don't have to familiarize yourself with an API of >100 classes, a different formatting/parsing mechanism etc.

Of course, if you do need complete representation of different chronologies (e.g. Hebrew) or wish to be able to define your own imaginary Calendar system (e.g. for a game you are writing) then perhaps JODA or JRS-310 is for you. If not, then I would suggest that rolling your own is possibly the way to go.

The JSR-310 spec lead is Stephen Colebourne who wrote JODA in the 1st place, so will logically replace JODA.