John O'Conner's Blog

Calendars, Dates, and TimeZones

In general, calendars are not easy to understand, develop, or to use. They are complex, created out of the need to understand and put order into celestial movements, seasons, religious events, and political decisions. It's a wonder that we stay on schedule for anything, and yet we do, and the world moves on, and we still are able to use the Java platform's Calendar and Date classes to properly handle date and time functions in our applications...despite the complaints against them.

I see a new JSR on the horizon, JSR 310: Date and Time API. I haven't been involved in that, but I'm confident it will help resolve some of the problems people have with the existing Calendar and Date API in the Java platform.

I can't complain about what we have today. I know the people that created these APIs, and I know their commitment and contributions. They've worked hard and have had to work under tremendous constraints that have limited their ability to implement perfect solutions. Just like real calendars, the existing Calendar and Date APIs have been influenced my many, many factors. So, until something better comes along that everyone agrees on, we have to work with what we have. For me, that's the core APIs...nothing against Joda or other products, nothing at all. However, I think the existing date and time support is usable.

In fact, I think it's time to help others resolve some of their concerns about the Calendar, Date, and TimeZone classes. If you have questions about these classes, I encourage you to email me (john at joconner dot com) or respond to this blog. I'm going to collect your comments and respond right here. Let's get rid of any confusions about these APIs and show some real solutions...these classes might just work better than you suspect. I'll devote the next few blogs to demonstrating best practices with these classes.

Comments

• Fewpoints:

  the Calendar and Date classes are mutable, creating performance bottlenecks, and meaning (unlike string) you need to copy the instance to be sure nobody else modifies it.
  there is no class defining the concept of a period or interval (i.e.: "one month" or "x milliseconds"); the latter can be implemented as a "long", the former requires tricky offset calculation depend on the length of a month etc.
  there's no concept of a partial date or time (for example, day of year without time, or time of day without year). Messing about with "int" constants is unwieldy too, Joda solves that in a readable way without preventing use of exotic calendar systems.

  - Chris

  Posted by: chris_e_brown on March 01, 2007 at 10:49 AM

• JSR 310 has a home here on java.net and also a Wiki for contributing to that JSR's development - might be more useful for you and others to contribute there,

  Posted by: niallp on March 01, 2007 at 03:46 PM

• Joda time has a lot of good points what's wrong with the date api:
  http://joda-time.sourceforge.net/
  

  Posted by: ge0ffrey on March 01, 2007 at 10:56 PM

• Joda has a lot of things wrong with it. It's used on one project here, and it's a terrible pain in the you know where.
  As John says, the standard API is quite usable even if not perfect. It's certainly superior in many aspects to Joda.
  Defined intervals would be nice, but IMO have no place in the standard API. A way to initialise a Date or Calendar to contain only the date or time part would also be nice, but I can live without it (and when not, a method that does it for you is quick to write in your personal utility library (you do have one, don't you?).
  Immutable again might be nice in special circumstances, but I've never needed it.

  Posted by: jwenting on March 02, 2007 at 06:08 AM

• Hi jwenting,

  Could you please provide specific use cases and cenarios that support your argument? As you stated now, it is as vague as Java is slow.

  Posted by: mister__m on March 02, 2007 at 06:51 AM

• jwenting:
  I could write a personal library, but why reinvent the wheel? The partial dates and times (and intervals) proposed by Joda, aren't just simple data structures, you get flexible comparison, parsing, and formatting capabilities too. That would take longer to write and test.
  I found Joda initially less easy to understand than the standard classes, simply because I was so familiar with them. I've found Joda to be much more logical and makes for more readable code in the long run.
  Consider running a profiler over code blocks that make extensive use of Date, Calendar, and (in particular) SimpleDateFormat. They are quite slow. Furthermore, the lack of thread safety means that you can't share instances (if you have a high-throughput data processing system, you can incur big performance overheads by need to create a single SimpleDateFormat per thread, which isn't a problem with a thread-safe equivalent).
  - Chris

  Posted by: chris_e_brown on March 02, 2007 at 07:57 AM

• I wouldn't trust profiler too much. When was it last time that profiler would point at a segment of code claimig CPU is 25% utilized right there, and when you would eliminate this piece, you would get exactly 25% (ok, let's be fair, at least 15%) back?Besides, what exactly is slow in the SimpleDateFormat? Is there away to do this work faster? I'm sure by now a bug would have been filed... The point is, it is an untrivial amount of work to translate a Date into a human-raedable string, according to rules of locale, timezone and such. If there's a faster way, everybody will appreciate the improvement. Until then, we just have to put a price tag on use of these classes and don't approach them without serious consideration WRT performance.

  Posted by: denka on March 02, 2007 at 09:39 AM

• This is the wrong fight, treating java.util.date or joda as a rival and proving it's not perfect. Except to the developers of these libraries themselves, these are nothing more than often-used utilities to the average developer. Anything that can make using them simpler and less error-prone is welcome. Hopefully the JSR will iron out major kinks and usability issues, but we've lived with a less-than-perfect java.util.date for a long time, we'll live with a jod atime that's not perfect if it's easier most of the time.
  

  Posted by: sumitkishore on March 02, 2007 at 10:45 AM

• I am also in the "the existing classes are usable" camp. They are not great, but they do. When I started with calendar I wished the documentation would contain more examples (field priorities? add() vs. roll()?) and not use so unusual terminology (lenient?). But one can get used to it.

  I remember that there was some website with a Java Date and Calendar cookbook. That one was great to get started. Unfortunately I can't find it any more. They ran through all the typical things one usually does with a date and time and provided example code.

  In my work I can observe that the one thing programmers and normal people :-) typically don't get are timezones (Locales), particularly when one comes with DST. Hint: If your time looks wrong by a multiple of fifteen minutes chances are you need to think about timezone or that DST thing.

  The second typical problem I can observe is a reading aversion among programmers, particular when it comes to Calendar. People like to spend hours writing more and more obscure code to "fix a problem with that brain-dead Calendar", instead of sitting down for twenty minutes and thoroughly reading the Calender, GregorianCalender, Date, and SimpleDateFormat API documentation.

  And the third thing people typically get wrong is date storage. Wall clock time alone (without timezone information) is not really a good format for long-term storage, particular if the data travels multiple time zones. Even with a timezone name it is bad, since one has to have historic data about the particular timezone, and three letter timezone abbreviations are anyhow ambiguous. Also, providing the offset to GMT in addition is not the best idea, since there are two ways to provide that offset. Storing GMT (or UTC) would be best, if people wouldn't start to complain that the dates in that file are "wrong", because they don't get timezones.

  Posted by: ewin on March 02, 2007 at 11:02 AM

• The main thing I wish for is partial dates, objects for just a time, or just a date, not both at once.

  Performance bottlenecks from copying date instances? Far be it from me to say it couldn't happen, but I am surprised. I mean, for copying dates to become the limiting factor in performance, that's astonishing.

  Intervals and so forth start getting into the anti-feature realm. Computations of this nature can quickly involve so many rules specific to a particular use case that trying to support them all in some general way would result in a horrible, horrible API.

  "A six month interval, please."

  "Sure thing, coming right up… oh, do you mean 180 days, or this day of the month 6 months from now, or what? Because I can do either with my trusty Calendar here."

  "Erm, uh…

  "What about weekends? Does the interval need to end on a work day?"

  "Oh, yes, I meant to mention that."

  "Super! If would fall on a weekend, do you want the day before, the day after, the closest day, or what? Oh, and what about holidays?"

  "No, please take out the holidays too."

  "Very well, then. Could you kindly tell me what you consider to be a holiday? Oh, and, uh, what exactly did you mean by 'six months'?"

  "Argh!"

  Posted by: erickson on March 02, 2007 at 11:03 AM

• Calendar and Date are just horrible classes. Sure, they work correctly (as far as I know). They allow you to do complex calculations. However, the use of constants to do all this is just horrible and not in the spirit of OO programming at all.

  Worse, given that Java is used in educational contexts, it is very hard to get beginning programmers to use all that. There should be a simple path for people not wanting to worry about timezones and Aztec calendars.

  Having used .Net I found the timerange features extremely cool. But I did miss Java's Timezones (when I needed them).

  Posted by: dog on March 02, 2007 at 12:14 PM

• ah, so because teachers use Java Java should be dumbed down to the level where teenagers who've never programmed before except maybe a level for Quake can use it without having to think.
  There's something wrong with that argument. Such a language already exists, it's called Logo.

  Posted by: jwenting on March 02, 2007 at 10:48 PM

• i'm also interested in hearing what jwenting finds wrong with joda. specific examples go a long way.

  Posted by: ilazarte on March 03, 2007 at 10:11 AM

• One function I'd love to see implemented in the Calendar class is the check if a Calendar object is between two others. Like the example below:

  Calendar.isBetween(Calednar beforeDate, Calendar afterDate);
  So far there only is .after() and .before().

  One other problem I encountered was using Calendar.getInstance() too often. I first started using that to return the current date+time. But it kept returning the same date/time as the first instance. I had to change it to forcefully set the timeInMillis whenever I want to return a Calendar class with the current date+time.

  Aside from that everything else is fine.

  Posted by: dma02 on March 04, 2007 at 02:17 AM

• Joda is overly complicated to use, especially as it doesn't map well with the standard Date and Calendar classes.
  Try interfacing between a 3rd party library using Joda and another 3rd party library that doesn't and its deficiencies soon become clear. Instead of making for ease of use it soon becomes a complete and utter mess. Add in some timezones for good measure and the disaster is complete as Joda is completely unportable.

  Posted by: jwenting on March 04, 2007 at 02:23 AM

• Isn't the simple fact that there are so many conflicting posts about this topic enough to see that there is clearly a problem? If it was easy and powerful I'm not sure this issue would come up every year. Someone, please recreate the wheel!

  Posted by: brl4n on March 04, 2007 at 08:47 AM

• Fine if "usable" is good enough for you.

  Gives the rest of us who strive for bug-free, efficient development a competitive advantage.

  Posted by: skelvin on March 05, 2007 at 01:57 AM

• I just rarely (ever?) have seen concrete examples of current APIs being bad that would stand a rigorous review. Most descend to a mere complaints (Boo-hoo... JANUARY is a zero) and refusal to learn standard APIs. Don't blame the API, folks, blame the real-world issue with time management. Don't believe API can be made simpler when the reality it reflects is so complex.

  Posted by: denka on March 06, 2007 at 10:36 AM

This work is licensed under a Creative Commons License.