This is likely not the first time you’ve heard that
Calendar classes in the JDK just don’t cut it and you likely have fought with one or both on more than one occasion.
The main problems with
- it exposes nothing to do date manipulation or math
- it doesn’t provide sufficient control over timezone
- it isn’t immutable so passing around Dates can be dangerous
Calendar class was intended to break out that point in time and provide access to its individual pieces (hour, seconds, day of month, etc.). In doing so, the ability to mutate the calendar’s fields individually or even perform date math became possible.
Calendar has these pretty major flaws:
- it is mutable, which makes passing around instances dangerous
- thread-safety becomes an issue because of its mutability
- mutation methods are complicated and have caveats
It makes sense to use an alternative to these in everyday use for these basic cases and once you have the alternative, it becomes the ideal choice for any date use. I won’t comment on Joda much which is being considered as a basis for introducing these types of improvements into Java 7 as when we undertook creating these improved representations here at Carfey Software, no feasible alternative existed. Regardless, what we ended up with is much leaner, cleaner and more targeted then what Joda has become. What I’ll do instead is go over the design decisions and requirements for an alternative, some of which you may recognize from Joda.
First, there are many times that we’d like to be able deal with a Date with no time component and Time without the date component. So we want 3 primary classes,
DateTime. Secondly, since we’re going to support manipulations, the classes all need to be immutable. Those two key approaches already solve many pains we experience when dealing directly with the JDK classes.
Let’s also create our own
DateFormat that takes these objects, wraps
SimpleDateFormat but adds thread safety, internally synchronizing its use so we can use them as they naturally are much of the time, as constants.
Internally, our three classes can use
Calendar since it technically supports most of what you’d want to do. We want them to be easy to use, so lets hide the
Calendar when it comes to representing months and days. So let’s use enums to represent
Now this really starts to take shape. We can add all our getters and our math methods as appropriate to each class.
addHours and even
lastDay, and the extremely useful
isLastOccurenceOfDayOfWeekInMonth (e.g. is this the last Friday of the month).
And of course they implement
equals properly so these can be used as keys and have natural sorting order and be used in
A simplified class diagram is shown below:
Free for Use
Since we think our date classes are very useful for the most common cases and are cleaner than Joda time and other alternatives, we’ve decided to make the code available under the MIT licence. This leaves you free to do virtually anything you like to the code, including try to sell it if you feel so inclined.
If you find any bugs or have questions, leave a comment here or on the sourceforge project site.