6 Subtle Date and Calendar Details to Learn before using Date in Java - Example Tutorial

Hello guys, to appreciate the brilliance of the new Date and Time API introduced in Java 8, you must remember the nasty problems you have earlier faced with Java's old Date and Calendar API Well, I have been using Java for the last 20 years and I have to face them so I thought to write this article to educate Java programmers about the shortcomings of old Java Date and Calendar API. Another reason for this article is that even though Java is ready with the new, shiny, and carefully designed Date and time API, your project is probably not. Most of the prominent organizations that use Java at large scales, like Investment banks, Insurance companies, major E-commerce giants, are quite reluctant to upgrade. There are many firms, both big and small that are still running on Java 5 and expect to migrate to Java 6 in a couple of years.

If you are working as a professional Java developer, you are expected to maintain and support those projects running in an older version of Java with the old date and calendar API, and having these details under your belt will only going to help you write better code in Java.

On a different note, I have found that Java developers know very little about Date and Calendar classes compared to other important parts of Java API like Collection framework, Multithreading, and Concurrency, utilities, etc.

One reason for that could be less exposure to Date, time, timezone, and Calendar classes, but I think the main reason is less exposure to these features on Java Interviews. I found that many Java developers know more about features that are frequently asked in Interviews. So, it may be the right time to start examining a candidate's Date, time, and Calendar skills as well.

Btw, If you are new to the Java world and want to learn Java better, I suggest you start with a comprehensive Java course like Java Programming for Complete Beginners by fellow Java developers and bloggers, Ranga Karnam on Udemy. It's also one of the most up-to-date courses and teaches you how to use Shell for quicker learning, introduced in Java 9.

6 Things Every Java developer Should Know about Date and Calendar class Before Using them

Without wasting any more of your time, here are some important details about Java's Date and Calendar class which every Java developer should know, especially, experienced Java developer or someone who needs to work and maintain applications running on Java 6 or Java 7.

1. The year starts from 1900

In Java, the Year of Date class begins in 1900, which means if you try to create a date object to represent today's Date as follows, it would be wrong.

Date d = new Date(2015, 7, 8, 18, 30);

Because of 2015, the means the year 1900 + 2015, which is 3915, quite far, no? In order to represent 2015, you should do something like this :

int year = 2015 - 1900;
Date d = new Date (year, 7, 8, 18, 30);

If you want to learn more about Java's old Date and Time API, I suggest you check out a comprehensive Java course like The Complete Java Masterclass on Udemy. It's also a very affordable and most up-to-date course, which means you can also use it to learn new the Date and time API in Java.

2. January is 0, December is 11

In Date, Month starts from Zero, which means the first month, which is January is 0 and the last month of the year, which is December is 1. So the above code has another problem, it's not representing the 8th of July as intended, it's representing 8th August. This is how you should specify the month :

int year = 2015 -1900;
int month = 7 - 1;
Date d = new Date (year, month, 8, 18, 30);

Because of this, you need to be really careful while using the old Date class in your Java application.

3. Date is Mutable

Yes, even though Date does represent a point in time scale, it's mutable, which means you can change the Date once created. This is non-intuitive as many programmers think of Date as a constant number that cannot be modified once created.

4. DateFormat is not thread-safe

DateFormat is used for formatting dates, and it's an expensive object. Many developer stores reference of DateFormat in a static field (as shown below) and use it throughout their program, this is wrong and create nasty bugs.

A DateFormat or its most popular implementation, SimpleDateFormat stores the Date to be formatted/parsed into an internal field. If two threads try to simultaneously parse or format dates, you may get runtime exceptions or incorrectly formatted dates.

It's not just a theoretical possibility but has caused a problem in production and is quite easy to reproduce using the unit tests as well. Thankfully, all major static code analysis tools like Findbugs and fortify can identify this bug in your code.

If you want to learn more about Thread safety and how it affects Java performance and how difficult it can be to solve Thread-related issues then I suggest you read Java Concurrency in Practice book by Brian Goetz, the bible of concurrency for Java developers.

Though it's not an easy book to read because Concurrency itself is very confusing and if you have trouble reading the book and understanding key concurrency concepts then I recommend you to combine this book with the Java Concurrency in Practice Bundle course by Heinz Kabutz, a Java Champion, and popular Java instructor. This course is based on the book and really makes it easy to get the best out book by explaining concepts in more detail and easier way.

5. The Calendar class cannot be formatted

The calendar class was created with a clever thought of representing the calendar aspect of Dates like Year, Month, Day of Month, Day of Week, etc., but working with the Calendar is not seamless. For example, you cannot format a Calendar, you need to extract the Date and then format it, as shown below :

6. SQL Date/Time/Timestamp extends Date

You would be surprised to know that the Date, Time, and Timestamp class actually extend the Java .util.Date of class. I didn't find it intuitive, though, because SQL Date is a date without time, SQL Time is time without Date, and SQL TimeStamp is just like Java .util.Date.


That's all about the crucial things about the old Date API a Java Programmer should know. I didn't know some of them even after working in Java for so many years, and only my quest for learning Java 8 new date and time exposed me to these details. It's imperative for both beginner and experienced Java developer to know these subtle details before you start using it in your application to avoid serious, hard to track issues. 



Further Reading
If you are curious to learn more about date and time in Java, You might like the following articles and tutorials:

• 10 Examples of Java 8 Date and Time API (tutorial)
• 10 Courses to learn Java for Beginners (courses)
• How do you calculate the difference between two dates in Java? (solution)
• How to convert XMLGregorianCalendar to Date in Java? (solution)
• How to get the current date with Timezone in Java? (example)
• my favorite free courses to learn Java in-depth (courses)
• How to convert a String to Date in Java? (example)
• How to add days, months, and years from a Date in Java? (solution)
• my favorite books to learn Java in-depth (books)
• java.sql.Time, java.sql.Timestamp vs java.util.Date in Java? (answer)
• How to increment the date in Java? (solution)
• How to convert local time to GMT in Java? (answer)
• How to get a day, month, and year from a Date in Java? (solution)
• 3 ways to compare two dates in Java? (program)
• How to convert Date to String in Java? (answer)
• Why should you not use SimpleDateFormat in Java? (answer)

Thanks for reading this article so far. If you find these Date and Calendar class details useful then please share them with your friends and colleagues. If you have any questions or feedback then please drop a note.

P.S. - If you are new to the Java world and want to learn Java better, I suggest you start with a comprehensive Java course like The Complete Java Masterclass course by Tim Buchalaka's son Udemy. It's also one of the most up-to-date courses.