Java's java.util.Calendar

Java's java.util.Calendar class is used to do date and time arithmetic. Whenever you have something slightly more advanced than just representing a date and time, this is the class to use.

The java.util.Calendar class is abstract, meaning you cannot instantiate it. The reason is that there are more than one calendar in the world. For instance, the Arab calendar uses a different year as year 0 than the Gregorian calendar used by most western countries.

Instantiating a GregorianCalendar

Java only comes with a Gregorian calendar implementation, the java.util.GregorianCalendar class. Here is how you instantiate a GregorianCalendar:

Calendar calendar = new GregorianCalendar();

A new GregorianCalendar has the date and time set to "now", meaning the date and time it was created.

Accessing Year, Month, Day etc.

The Calendar class has a couple of methods you can use to access the year, month, day, hour, minutes, seconds, milliseconds and time zone of a given date. Here are a few examples showing how that is done:

Calendar calendar = new GregorianCalendar();

int year       = calendar.get(Calendar.YEAR);
int month      = calendar.get(Calendar.MONTH); 
int dayOfMonth = calendar.get(Calendar.DAY_OF_MONTH); // Jan = 0, not 1
int dayOfWeek  = calendar.get(Calendar.DAY_OF_WEEK);
int weekOfYear = calendar.get(Calendar.WEEK_OF_YEAR);
int weekOfMonth= calendar.get(Calendar.WEEK_OF_MONTH);

int hour       = calendar.get(Calendar.HOUR);        // 12 hour clock
int hourOfDay  = calendar.get(Calendar.HOUR_OF_DAY); // 24 hour clock
int minute     = calendar.get(Calendar.MINUTE);
int second     = calendar.get(Calendar.SECOND);
int millisecond= calendar.get(Calendar.MILLISECOND);

There are a few more fields that you can access, like DAY_OF_WEEK_IN_MONTH and AM_PM which are not used so often. Check out the official JavaDoc to learn more about those fields.

The Calendar class has a corresponding set() method so you can set these fields too. Here is how that looks:

Calendar calendar = new GregorianCalendar();

calendar.set(Calendar.YEAR, 2009);
calendar.set(Calendar.MONTH, 11); // 11 = december
calendar.set(Calendar.DAY_OF_MONTH, 24); // christmas eve

etc.

Adding and Subtracting to Year, Month, Day etc.

You can also add to these fields and have the Calendar instance update itself correctly. Look at this example:

Calendar calendar = new GregorianCalendar();

//set date to last day of 2009
calendar.set(Calendar.YEAR, 2009);
calendar.set(Calendar.MONTH, 11); // 11 = december
calendar.set(Calendar.DAY_OF_MONTH, 31); // new years eve

//add one day
calendar.add(Calendar.DAY_OF_MONTH, 1);

//date is now jan. 1st 2010
int year       = calendar.get(Calendar.YEAR);  // now 2010
int month      = calendar.get(Calendar.MONTH); // now 0 (Jan = 0)
int dayOfMonth = calendar.get(Calendar.DAY_OF_MONTH); // now 1

The add() method is really handy when doing date arithmetics like adding or subtracting years, months, days, hours etc. from a given date.

To subtract from the fields call the add() method with negative values, like this:

calendar.add(Calendar.DAY_OF_MONTH, -1);

Traps and Pitfalls

There are a few minor traps in the Calendar class that you should be aware of to avoid unnecessary headaches. I'll cover those in the following sections.

The Month Trap

The MONTH field of the Calendar class does not go from 1 to 12 like they do when we write dates otherwise. Instead the months run from 0 to 11, where 0 is January and 11 is December. This can cause a bit of errors and subsequent debugging if you are not aware of this.

The Day of Week Trap

The day of week runs from 1 to 7 as you might expect, but sunday, not monday is the first day of the week. That means that 1 = sunday, 2 = monday, ..., 7 = saturday. This has also caused me minor annoyances from time to time.

More Detail in the JavaDoc

If you need to do heavy or complex date and time calculations it is a good idea to read the class documentation forjava.util.Calendar in the official JavaDoc's. The class documentation contains more detail about the specific behaviour of the class. For instance if you set the date to Jan. 34th 2009, what will the real date be?