JSR 310 Part 1 : Existing Date and Time API

Greetings everyone!

It has been a long time since my last post. So far, we have emphasised more on the Introduction of some of the very cool Java features. We also tried to understand the concepts with the help of example code. Moving ahead in the same train, in this Java Tutorial we will check out a yet another exciting Java 8 Feature and that is JSR 310 a new Java Date and Time API.

The New Java Date and Time API (a. k. a JSR 310 or ThreeTen) was originally planed to ship with Java SE 7. But because of the delays in the progress of the project ThreeTen (project JSR 310), the plan changed to Java SE 8 and further changed to Java SE 9. Very recently, it has been officially declared that, the Java Date and Time API progress is in a good shape and it will be able to safely catch the Java SE 8 train.

A Date and Time mechanism is very critical in any programming language. The existing Java Date and Time API has lot of problems and a non-unified structure. The JSR 310 aims to enhance the current Java Date and Time support by introducing a new package called as ‘java.time’. Before we move ahead, we will have a look at the problems with existing API.

Existing Java Date and Time API:

The Java Date and Time support exists since the beginning of Java. It has been evolved during this time with the addition of new classes and modification of the existing ones. Because of this, many classes have their own constructs and they do not follow a common structure with the other Date and Time classes. This ends up giving a bunch of classes with their independent behaviour and set of their own limitations.

The very basic problem with the Date class is that, it is mutable.

private Date dateOfJoining;
public Date getDateOfJoining() {
    return dateOfJoining;

The getDateOfJoining method above returns a Date object. But the client is still able to call a setter method on dateOfJoining. This makes it very unsafe to be used in the multithreaded environments. If we print the dateOfJoining it returns.

Mon Mar 25 11:21:45 GMT+05:30 2013

The intention is to capture the date when the student actually joined the institute, but the Date class unnecessarily captures the time as well, which we do not need and can be misleading when the Date is shared along with the clients. In Java Date and Time Mechanism, there is no possibility of storing only Date without Time and Only time without Date. To represent only Date, we usually put default time of 12 mid-night. This may introduce a new problem, as in some regions there is no mid-night once in a year, because of DST changes.

In Java’s date class the epoch is considered as 1st January 1900, which too far, and hence results in larger calculation. Also it is not able to deal with a time unit smaller than millisecond. Java is a faster language and it is impossible to calculate statement execution times with the help of milliseconds.

Another interesting problem with the existing Java Date and Time mechanism is its month calculation begins with a zero. January is a 0th month and December is 11th. This makes it error prone when a month is set from outside with the help of integer. It was very complicated with Java Date class to develop a system that can works in different time zones across the world, as Java Date class doesn’t support Timezones.

The lately introduced Calendar class is little smarter and also supports TimeZone, but it also has its own set of problems. The Calendar considers the epoch from 1 January 1970. As the respective methods in Java Date have been deprecated, this is the class which we need to use when we want to set Months, Day, Year separately. The Java Calendar is also mutable, and hence unsafe in multithreaded environments.

When we want formatted Date, we can use SimpleDateFormat. Calendar dates can not be formatted with the help of SimpleDateFormat. To format a Calendar date we first need to convert it to Date and then format it. Calendar has lots of performance issues as it calculates time difference in milliseconds since the epoch multiple times for internal processing.

Another big problem with the Java Date and Time is, it break the rule of equality. See the following code.

Date date = new Date();
Timestamp timeStamp = new Timestamp(date.getTime());
System.out.println("date.equals(timeStamp) => "+date.equals(timeStamp));
System.out.println("timeStamp.equals(date) => "+timeStamp.equals(date));

The output is:

date.equals(timeStamp) => true
timeStamp.equals(date) => false

According to the symmetric rule of equality, both the of answers should have been true. But this is not true in this case.
Also the Java Date and Time mechanism doesn’t have a control over the Day Light Saving. It can’t be turned OFF or ON depending upon the need.

So far we have seen the problems with the traditional Java Date and Time mechanism. In the next section, we will have a brief look at the JODA Time API, which is used as an alternative to overcome the shortcomings of the default Java Date and Time API and then we will move in detail with the new Java Date and Time API (JSR 310) in the next section.

One thought on “JSR 310 Part 1 : Existing Date and Time API

  1. Interesting article about problems with Date and time API that any developer will encounter in day to day life… waiting for the next part on this..

Comments are closed.