Martin @ Blog

Dutch version can be found at the Finalist IT Group weblog.

Since the start of the development of JDK 7, there is quite some discussion on the API’s in the standard Java libraries which covers date and time. In the current Java version (1.6) there are roughly three major (groups of) classes which are responsible for handling date and time: Date and Calendar, the formatting classes, and the classes in the java.sql package, including java.sql.Date, java.sql.Time and java.sql.Timestamp. Most developers agree that these classes are far from perfect.

In order to resolve this issue, JSR-310 is started to improve the date and time API in the standard Java libraries. However, due to lack of developers and slow progress, it became very uncertain if the JSR would be ready for inclusion in JDK 7 (which will eventually become Java 7, the name I will use in the rest of this article). JSR-310 is lead by Stephan Colebourne and Michael Nascimento Santos. Colebourne is the original author of the increasingly popular Joda Time project, which is a replacement for the default Java date and time API’s. At Devoxx 2009, taking place last November, Mark Reinhold of Sun announced that Java 7 will be delayed until September 2010 at the earliest. Stephan Colebourne sees this as a opportunity to release at least a partially complete JSR-310 in time for the upcoming Java release.

But why is the current Java date and time API broken? How can you circumvent the issues in this API? And how does JSR-310 intends to resolve the issues in the upcoming release? These questions I will try to answer in this article.

Current date and time API in Java

While it is a bit to much to explain the complete workings of the date and time API in Java 1.6 (and before), I will try to explain the main problems with the current date and time API in Java. I assume some upfront knowledge of the API by the reader, but probably it is not very difficult to follow for people who don’t have extensive experience with the API.

The Java 1.6 standard library contains a few classes which deals with date and time. The most important ones are Date and Calendar. Almost the entire API is designed around these two classes. The main problem with them is that fairly simple operations on date and time require a rather large amount of code with many instances of individual classes. This has a negative impact on performance. The API is inconsistent and confusing for developers, making code using Date and Calendar hard to read and maintain. Additionally, the API is incomplete which force developers to create custom solutions for simple problems. Finally, the API misses opportunities which would made the usage of the API simpler. With this last point, I mainly refer to the lack of fluent API’s and the fact that all objects are mutable.

In the current API only a specific instance in time can be represented using a Date object. This object represents a specific point in time, internally defined by the number of milliseconds since the Epoch (January the 1st 1970 at 0:00 hour) and a timezone. In fact, this could be easily represented by an immutable object. Unfortunately, this is not the case. In earlier Java versions, many methods were added to the Date class making it possible to manipulate it. Nowadays, almost all these methods are deprecated and should not be used anymore. However, they still exists, and worse of all the setTime(long time) method is not deprecated and changes the state of a Date object.

The fact that Date is a mutable object, makes it hard to use it in other classes which are immutable. One should always make a defensive copy of every Date object that is part of an immutable object. Joshua Bloch gives an example in his book Effective Java:

public final class Period {
  private final Date start;
  private final Date end;

  public Period(Date start, Date end) {
    if (start.compareTo(end) > 0)
      throw new IllegalArgumentException(start + " after " + end);
    this.start = start;
    this.end = end;
  }

  public Date start() {
    return start;
  }

  public Date end() {
    return end;
  }
}

Objects of the type Period appears to be immutable, however it is not due to the usage of the Date class. An example where a Period object is changed:

Date start = new Date();
Date end = new Date();
Period p = new Period(start, end);
end.setYear(78); // Modifies internals of P!

This bug makes it possible to change the end date of the Period p, which renders the check in the constructor of Period void. Of course, there is a pretty simple way to prevent this problem by making a copy of start and end in the constructor of Period:

public period(Date start, Date end) {
  this.start = new Date(start.getTime());
  this.end = new Date(end.getTime());
  [...] // remainder omitted
}

However, this requires additional effort of the user of the API and can easily be forgotten. When Date objects would be immutable, this extra copy would not be necessary.

The other class in the date and time API in Java is the Calendar class. Instances of this class represents a point at a specific type of calendar (most of the time Gregorian) and provide methods to do some simple calculations. The main problem with this class is that it is mutable as well. The methods on this class are also not very beautiful. For example, to get the current year of the Calendar instance cal, one should call cal.get(YEAR) where YEAR is a constant. It is also confusing that a Calendar can operate in two modes, namely ‘lenient’ and ‘non-lenient’. In the first case, it is possible to define values for fields which are normally out of range. For example, it is possible to set the month to 15. The Calendar object then automatically converts it to a valid month, by increasing the year by one, and set the month to april.
Wait, april I wrote? Yes, months are zero-based in the Calendar (however, days, years, etc. are not).
The way the days of a week are represented are a little bit confusion

The main problems are clear now, however, there are many other smaller problems. For example, there also exists java.sql.Date, java.sql.Time and java.sql.Timestamp. These classes are childs of the java.util.Date class, but add some functionality for use in databases. However, there is a problem in the implementation of these classes. The java.sql.Date class and is used to represent a date without a time, while the java.sql.Time class represents a time without a date. Timestamp adds nanoseconds to the Date object. However, internally they still contain both a time and date and the implementers did not override the equals and hashCode methods causing hard to find bugs:

Date date = new Date();
Time time = new Time(date.getTime());
java.sql.Date sqldate = new java.sql.Date(date.getTime());
Timestamp timestamp = new Timestamp(date.getTime());

System.out.println(date.toString()); // Sun Dec 20 15:53:55 CET 2009
System.out.println(time.toString()); // 15:53:55
System.out.println(sqldate.toString()); // 2009-12-20
System.out.println(timestamp.equals(date)); // false
System.out.println(date.equals(timestamp)); // true

This means that java.sql.Timestamp does not obey to the equals contract, saying that the equals should be symmetric. Additionally, it is confusing that Time and java.sql.Date only represent a part of the date, but still use the same equals implementation.

Astronomical Clock

There are more problems with the current API. For example, there is no way to define durations or a reliable way to represent a date without a time, or a time without a date. The performance of the API is unpredictable, because the fields are recalculated at unexpected moments. Finally, it is not very straightforward to format a date for print. One should use the (Simple)DateFormat classes for this, which means additional objects.

Joda Time

At this moment there is already a working solution for the problems described in the previous section. It’s called Joda Time and this is a replacement for the date and time API in the Java standard library. Joda Time solves most problems that currently exists. Joda Time contains two ways of defining a particular date or time: instant for a particular point in the ‘date time continuum’ and partial for a time or date representation which is not exactly a point in time, because a part is missing (the time, timezone, year, etc.).

Intstants in Joda Time are defined by the ReadableInstant interface, of which the most used implementation the DateTime class is. A DateTime object is immutable and contains a fluent API to do calculations on it (which of course return new objects). In order to make it easy to use it in existing projects, it is easy to convert a JDK Date object to a DateTime object and vice versa. Joda Time also provides a mutable version of the DateTime class, MutableDateTime, which can be used when a lot of transformation on a date has to be done. However, the usage of this object is most of the time not really necessary and should be avoided in my opinion. A MutableDateTime can easily be converted to a immutable version of it.

Partials are represented by the ReadablePartial interface, of which the most used implementations are LocalDate, LocalTime and LocalDateTime. Object of these types are also immutable and can easily be converted to DateTime objects and JDK Date objects. Additionally, Joda Time contains Duration, Period and Interval for completeness.

Of course, an example of Joda Time usage cannot be omitted in this article:

DateTime now = new DateTime();
Period sixdays = new Period(0, 0, 0, 6, 6, 0, 0, 0);
System.out.println(now); // 2009-12-20T18:35:53.360+01:00
DateTime future = now.plus(sixdays);
System.out.println(future); // 2009-12-27T00:41:59.097+01:00
System.out.println(now.withYear(2028).plusDays(31).toString("dd-MM-yyyy hh:mm")); // 20-01-2029 06:41

This example initializes now to the current time (the default value of a DateTime without constructor parameters). The variable sixdays contains a reference to a Period object which defines a period of 6 days and 6 hours. Periods can easily be added to a DateTime object using the plus() method. Note that the result of the method should be assigned to a variable, since it does not modify the existing object, but creates a new one which has to be assigned to a variable in order to use it actually.
The last line shows how easy it is to perform simple calculations with date using Joda Time. Additionally, it shows another feature of Joda Time, namely the ease to format a date according to a specific pattern. A similar operation would be much more difficult using the JDK Date and Calendar classes, since one would have to instanciate a Calendar, Date, SimpleDateFormat and call several individual methods.

Joda Time also makes many other use cases very simple. For example, the DateTime constructor accept many different types of objects for initialization. For example, one can provide many different formatted String objects, which are automatically parsed correctly. This includes the ISO 8601 format, which is used in XML. For testing purposes Joda Time also makes it possible to change the current time, using DateTimeUtils.setCurrentMillisFixed(millis);.

JSR-310 and Joda Time

As mentioned earlier, JSR-310 is lead by Stephan Colebourne, who also created Joda Time. It may be obvious to take the latest Joda Time release and put a JSR stamp on it, declaring it the reference implementation. This is not what is happening, with good reason.
Stephan devoted a recent blog post on this topic, explaining why JSR-310 differs from Joda Time. The main reason is that Joda Time is not perfect.
The design goals for JSR-310 are clearly defined: The API should support immutability, a fluent API, it has to be extensible and the API should be clear, explicit and expected. Especially this last point is where Joda Time is not perfect. For example, Joda Time uses the notion of Chronology to represent different calendar types. It is possible to define the Chronology when instantiating a DateTime object. In the default case, a DateTime object will return a value between 1 and 12 when calling the getMonthOfDay() method. However, when using a for examle a Coptic Chronology, this method can also return 13, since the Coptic calendar has 13 months. This makes the API return values the user might not expect, and in fact, the previous method call requires a check to make sure the result is as expected. Also the use of the ReadableInstant by DateTime and the Instant class (which is a machine representation of an instant in time) is wrong, since there is difference in how humans define an instant in time compared to how machines see it. Finally, Joda Time accept null values in many places without throwing an error, which is also wrong according to Colebourne.

The issues in Joda Time should be fixed in the JSR-310 implementation making it an even better date and time API. Should we therefor not use Joda Time? Definitely not! Of all available options, Joda Time is definitely the best choice for working with dates and times in Java. The fact that the completion of JSR-310 takes a very long time, is since for most developers Joda Time fixes the problem that exists in the current JDK API, making the urgency of completing JSR-310 pretty low.

Conclusion

The date and time function in the default Java SDK is flawed in many ways. While it can be used for most projects with some extra effort, it can also cause many unexpected problems. JSR-310 is on its way to finally fix this problem. However, it is still not yet sure if it will be part of Java 7, mainly because of the lack of developers.
For new projects, there is very few arguments for not using Joda Time. It is well tested and well supported, including support for Hibernate and JSP’s. It makes it a lot easier to perform calculations using dates, and provides an easy to use API with reliable performance.

Tags: Date Time API, Joda Time, JSR-310

This entry was posted on Wednesday, January 6th, 2010 at 12:48 and is filed under English, Software, java. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.

46 Responses to “Java Date and Time API and JSR-310”

January 8th, 2010 at 4:07
Jonathan Felch says:

Joda Time is a great, and as you say very popular, alternative to Calendar and Date. That said, there are lots of problems with Joda Time and JSR-310 that are serious enough than fans of these initiatives should push for serious work and reconsideration before it moves closer to any JDK release. Some considerations might include:

1. From a library point of view, the package is just too big. Interval and period has similar but incomputable and awkward interfaces. Except for DateMidnight there are few ways of initiating a time instance that represents the beginning of a period around a given reference date. Rather than sub-classing ReadableDate, there should probably just be simple factory methods to get the start or end of a period around a given reference date. All said, the library needs a design overhaul and should be a lot smaller.

2. Financial dates. Any serious revision to dates and times in Java should include simple implementations for calculating business and financial accrual (number of days of interest payable on a debt) using ISO standard day count conventions and the like. Similarly there should be basic support for business and legal calendars used by the countries where most software development is done (U.S, E.U., Russia, China, India, etc…)

3.) Date serialization and portability. Joda Time, Calendar, and Date all use context from the local machine to initialize the TimeZone and initializing all the fields in Calendar is extremely expensive. The date / calendar should have a small enough footprint to exist in a cluster and get serialized around the network as part of a time series collection in which hundreds of thousands and millions of observations can be organized temporally without a huge I/O or computational foot print. Contact Alex Miller or any of the guys at Terracotta and ask them what they want in a Date class. Of all the standard classes in the JDK, the Date/Calendar/JodaTime problem was probably the most common, most expensive, and most annoying part of clustering terrabytes of data on a networked heap.
January 9th, 2010 at 1:10
Martin Sturm says:

Thanks for your comment. I think your points are valid, and some of them should maybe addressed in JSR-310. I’m not sure if I understand your first point. You say the library is too big, but when is a library too big? If the modularization effort in Java 7 will be finished, it is theoretically possible to split the date/time handling into several sub-packages. For example, it will be possible to put financial dates into a seperate package, and as such I don’t think it should be part of the ‘core’ JSR-310 package (I think Stephen Colebourne mentioned this also in a blog post). With regard to your last point: to be honest, I don’t have enough knowledge to say something meaningful on clustering. I think it is also a difficult trade of, since many times users of the library expect the package to use the default timezone for the local machine, but I can imagine that this is a problem when clustering or a class is (de)serialized.
January 9th, 2010 at 19:26
Anthony says:

Financial Dates? Don’t go there… That is a huge nut to crack that is beyond the scope of a well thought out Date/Time implementation. We need a better solution to Date/Time in Java than Date/Calendar, and we can build a decent solution for Financial Dates on top of a smart implementation. My favorite solution is http://objectlabkit.sourceforge.net/

Java is overall a pretty smart and well thought out language with smartly constructed libraries, but I am amazed at how poor their Time/Date solution is compared to other languages. Joda time is a decent solution that has been thoroughly tested over years… I don’t see why we don’t want to leverage this and build it into the Java core. It is a long time coming.

I need this part of the JDK (rather than using Joda-Time) so that other standards can leverage it, like JPA, Bean Validation, JSF, etc.

I don’t understand the “lack of developers” comment… Why does it need more developers? Joda-Time provided the perfect reference implementation, so this spec was largely written already, so you didn’t need a lot of developers to get involved. Certainly, we need people to review and ratify it, but I suspect that all of the joda-time users would welcome it.
January 10th, 2010 at 5:40
i30817 says:

The other class in the date and time API in Java is the Calendar class. Instances of this class represents a point at a specific type of calendar (most of the time Gregorian) and provide methods to do some simple calculations. The main problem with this class is that it is immutable as well.

Did you mean mutable?
January 10th, 2010 at 5:58
i30817 says:

Actually i like that there is a large api as long as:

1) it has a factory class (like Executors)
2) exposed in interfaces (for extension factories)
3) (i would say private implementations, however that is not friendly to extensions, so extensions in another sub-package)

(serialization can be optimized by readObject writeObject methods).
January 10th, 2010 at 12:18
Martin Sturm says:

Yes, I meant mutable. Thanks for pointing out!
January 19th, 2010 at 14:08
Frank Hardisty says:

I’m in the camp that hopes JSR 310 makes it in. It’s time for time!

Joda Time is nice, it has a good API and seems well implemented. However, an external library is always in danger of falling behind (Apache Commons Collections, anyone?), or getting pushed aside later by a new standard.

Also, the size of the 1.6 joda-time.jar is 534 kB. Now, half a megabyte ain’t no thing on the server, but if you want to include it in a client application (Web Start or applet), that’s a fair bit of bloat just to do some reasonable date and time operations.
January 19th, 2010 at 20:03
Tom says:

I don’t think the comments in the sample Joda code represent the correct output. I get (of course the current time is different):

2010-01-19T12:56:09.256-06:00
2010-01-25T18:56:09.256-06:00
19-02-2028 12:56

The minutes, seconds, and milliseconds shouldn’t change between the first two lines.
February 15th, 2010 at 16:38
Chris Winters says:

Another benefit of Joda (and presumably JSR-310) is that everything is threadsafe. Stressing immutability goes a long way toward this, but the fact that the JDK SimpleDateFormat is *not* threadsafe has bitten quite a few people.
March 28th, 2010 at 17:51
gustav says:

JSR-310 is just one of many projects that is more or less failing due to lack of resources.
So will oracle bring resources to JDK development or not ?.
Its not much point of keep going if not, this problem has been going on for many years and its only been worsening over time.
The alternative is to let the needed control go, and let outsiders do alot more.
June 10th, 2010 at 16:12
domik.ch says:

You can get current date and/or time in Java using the following method. You may change the date format in the constructor of SimpleDateFormat to get the result in a different format:
import java.util.Date;
import java.text.DateFormat;
import java.text.SimpleDateFormat;

private String getDateTime() {
DateFormat dateFormat = new SimpleDateFormat(”yyyy/MM/dd HH:mm:ss”);
Date date = new Date();
return dateFormat.format(date);
}
July 9th, 2010 at 15:24
A propos de Joda-Time « C0De « the coffee workshop says:

[...] http://www.wolkje.net/2010/01/06/java-date-and-time-api-and-jsr-310/ [...]
September 1st, 2010 at 14:55
zero cost commissions says:

Genuinely definitely excellent website article which has obtained me considering. I in no way looked at this from a stage of look at.
September 1st, 2010 at 15:01
zero cost commissions says:

hi. I just now got word of this valuable web site plus I have got to state that this amazing is a great article. Thanks just for this unique wise information.
September 1st, 2010 at 15:01
zero cost commissions says:

Maintain up the great work mate. This website article shows how well you recognize and know this subject.
November 21st, 2010 at 21:08
Matthew Rawlings says:

Date and Time in Joda and Java represent Clock values rather than values of Date and Time. Until we grok the distinction then process clock values won’t get any easier.
January 8th, 2011 at 7:54
free iphone 5 news says:

i might not have considered this was interesting two or three years back then again it’s crazy precisely how time varies the manner by which you understand distinctive concepts, many thanks regarding the blog post it is actually good to look over some thing intelligent occasionally in lieu of the ordinary rubbish mascarading as blogs and forums on the web
January 8th, 2011 at 8:03
turf says:

thanks for this nice tips
January 8th, 2011 at 9:35
Weight gain diet says:

Excellent theme! What is its name? Or maybe you can gimme a download link? Regards!
January 11th, 2011 at 15:30
Eugene Lehrke says:

Great article. Waiting for more.
June 13th, 2011 at 14:25
Elvin Vazques says:

Out of my research, shopping for electronic devices online may be easily expensive, nevertheless there are some how-to’s that you can use to acquire the best bargains. There are continually ways to uncover discount discounts that could make one to have the best technology products at the lowest prices. Interesting blog post.
June 15th, 2011 at 17:06
Wilhemina Ziola says:

Good post right here. One thing I would like to say is always that most professional job areas consider the Bachelors Degree just as the entry level requirement for an online course. Although Associate Certifications are a great way to begin with, completing the Bachelors opens up many entrance doors to various jobs, there are numerous on-line Bachelor Course Programs available coming from institutions like The University of Phoenix, Intercontinental University Online and Kaplan. Another issue is that many brick and mortar institutions provide Online variations of their college diplomas but typically for a greatly higher fee than the organizations that specialize in online education plans.
June 15th, 2011 at 21:26
Cash Gifting Programs says:

Thank you wonderful. find advice reading through homework, and trying to find such.Penis Bigger
June 28th, 2011 at 2:24
Kurt Eifert says:

And in order to treat it you’ll need to take care of the “fascia” tissue of your arch that is causing the problem in the first place.CNN recently profiled a female veteran who had qualified as a swimmer in the 2008 summer Paralympics.Let the boots dry and do not set them out in the sun.The range of footwear offered by Loake has been extended to include new designs and a choice of both classic and modern designs.23
July 5th, 2011 at 4:45
Doyle Delfino says:

does one accomplish if you can’t know everyone whom futures the love pertaining to
August 1st, 2011 at 19:22
1234test.com says:

Sorry blog…

a few of my ideas….
August 1st, 2011 at 19:30
AR-15 Tactical Rifle says:

For what its worth I will tell all my friends about it, extremely original. Thanks.
August 8th, 2011 at 23:53
Dobos³aw says:

Significant other, this fabulous website is fabolous, i find it irresistible
August 26th, 2011 at 1:40
Lynn Rhue says:

I actually respect the valuable knowledge everyone offer in your own posts. We’re in the position to save your website and have the children check out upward the following typically. Now i’m relatively sure they’ll understand a wide range of brand-new products in this article as compared to other people!
August 31st, 2011 at 7:18
watch bad girls club says:

I’ve been surfing online greater than three hours as of late, yet I by no means discovered any fascinating article like yours. It is lovely price sufficient for me. Personally, if all web owners and bloggers made good content as you probably did, the internet shall be much more useful than ever before.
September 6th, 2011 at 20:01
gladiator says:

Anyone know of or have links to Australian copyright infringement cases involving photos or articles? Thanks.?…

I’ve Googled around but no luck yet. The ones I’ve come across so far all have to do with MP3s, software and what not. If you have any in mind, please provide links to the sources. Many thanks in advance!. …
October 15th, 2011 at 2:31
MdYcbbgcx says:

2011…

Attractive section of content. I just stumbled upon your weblog and in accession capital to assert that I get in fact enjoyed account your blog posts. Any way I’ll be subscribing to your augment and even I achievement you access consistently quickly….
October 26th, 2011 at 5:45
twitter followers for free says:

twitter followers for free…

[...]Martin @ Blog » Blog Archive » Java Date and Time API and JSR-310[...]…
November 2nd, 2011 at 22:41
Chong Spindler says:

I feel this is one of the most vital information for me. And i am happy reading your article. However wanna commentary on some general things, The website taste is great, the articles is truly great : D. Just right job, cheers
November 22nd, 2011 at 10:11
at risk software says:

at risk software…

[...]Martin @ Blog » Blog Archive » Java Date and Time API and JSR-310[...]…
December 2nd, 2011 at 6:14
medical assistant schools in virginia says:

medical assistant schools in virginia…

[...]Martin @ Blog » Blog Archive » Java Date and Time API and JSR-310[...]…
December 14th, 2011 at 21:18
veggie dating says:

Zune and iPod: Most people compare the Zune to the Touch, but after seeing how slim and surprisingly small and light it is, I consider it to be a rather unique hybrid that combines qualities of both the Touch and the Nano. It’s very colorful and lovely OLED screen is slightly smaller than the touch screen, but the player itself feels quite a bit smaller and lighter. It weighs about 2/3 as much, and is noticeably smaller in width and height, while being just a hair thicker.
December 15th, 2011 at 9:30
louis vuitton wallet says:

Hiring a non-public tutor is a great way to assist motivate your youngsters and to make guaranteed they get the one on a person awareness that they need. There are lots of tutors obtainable at cost-effective selling prices that can tutor your baby in everything from math to science. You could spend an older student or hire a expert tutor dependent on how complex the subject matter make any difference is and the amount of function that requirements to be carried out. You can consult close to for suggested tutors and retain the services of a person that has a verified monitor document for delivering productive results.
December 18th, 2011 at 2:29
KaaaCCvftT says:

Thank you for spending some time to make pay off the terminlogy to the the beginner!
December 30th, 2011 at 0:42
wypadek drogowy says:

Vielen Dank für dieses Blog-es ist toll! Ich mag diese Art von Menschen, die Wissen mit anderen zu teilen.
January 3rd, 2012 at 19:18
pozycjonowanie says:

own you seen this trifle medical task i confidently liked it and found legal healthiness workbook
January 4th, 2012 at 9:18
Website Design says:

Website Design…

[...]Martin @ Blog » Blog Archive » Java Date and Time API and JSR-310[...]…
January 5th, 2012 at 20:24
hair loss and baldness says:

hair loss and baldness…

[...]Martin @ Blog » Blog Archive » Java Date and Time API and JSR-310[...]…
January 18th, 2012 at 19:59
qkwttcvyet says:

qltatxpmlkf, efjzfhjlrn
January 21st, 2012 at 3:33
lawnmower says:

lawnmower…

[...]Martin @ Blog » Blog Archive » Java Date and Time API and JSR-310[...]…
January 24th, 2012 at 3:40
Learn how to slim down after xmas and shed 6 pounds with our 12 stage strategy. says:

Learn how to slim down after xmas and shed 6 pounds with our 12 stage strategy….

[...]Martin @ Blog » Blog Archive » Java Date and Time API and JSR-310[...]…

Java Date and Time API and JSR-310

Current date and time API in Java

Joda Time

JSR-310 and Joda Time

Conclusion

46 Responses to “Java Date and Time API and JSR-310”

Leave a Reply

Martin @ Twitter

Martin @ Moby

Wolkje @ Del.icio.us

Meta

Weblogs