Java's Calendar Date and TimeZone - What is all about it?

Intenally, A Date object is nothing but a long value that holds the number of milliseconds since January 1, 1970, 00:00:00 GMT. So new Date() on Jan 21 13:53:58 EST 2009 would be the same as Jan 21 10:53:58 PST 2009 = 1232564038800 (precise to the last 3 digits). So how are those two different? TimeZoneOffset. This is a int value that give millisecs diference between GMT and the Specified TimeZone. So When *printing* or getting the value of date in TimeZone, this timezone offset is added to the long utc secs. This gives the new print value (or face value - Jan 21 13:53:58 EST 2009 ). The face value includes all calculations for Timezone and is meaningfully correct only when displayed with the Timezone information (as above). Just reading and writing "yyyy-MM-dd hh:mm:ss" is incorrect. To start with let me show a small example:

Date t = new Date();
System.out.println(t);
//internal value - same (precise to last 3 digits)
System.out.println(t.getTime());
System.out.println(System.currentTimeMillis() );
//The following will change where you are running this code
System.out.println(t.getTimezoneOffset() );

Run the above program twice. Second time around set your system time to a different timezone. You will see in java.util.Date, a timezoneOffset is always set to match VM's Default TimeZone. What this means is that, the face value of [new Date()] is different on  VMs running on different Timezones, even when run at the same time.  And also, this TimeZone is not mutable on a Date. So When you need to SPECIFY a timezone, you use java.util.Calendar. The Calendar encapsulates a Date (internally the other way around, which is way complex and out of the scope this article) to spit information in TimeZone specified. So you could run on a VM in EST at Jan 21 13:53:58 EST 2009 something like

Calendar c = Calendar.getInstance(TimeZone.getTimeZone("PST"));

c holds the current time in PST = Jan 21 10:53:58 PST 2009.

If you do sysout on c, you will get a long GregorianCalendar Output. You should print it as

System.out.printf("%02d/%02d/%04d %02d:%02d:%02d in PST", c.get(c.MONTH)+1, 
    c.get(c.DATE), c.get(c.YEAR), c.get(c.HOUR_OF_DAY),
    c.get(c.MINUTE), c.get(c.SECOND));

Ouput will be 01/21/2009 10:53:58 in PST
However, The Date inside this calendar will not be in PST. It will be on System Timezone.

So If I print c.getTime() it will show Jan 21 13:53:58 EST 2009 instead of Jan 21 1:53:58 PST 2009.

Suppose you want your program to be independent of the TimeZone of the end users' VM. Example, You have an applet (or an application deployable on network) that sends information about client events and their timing, and you want to collect them in to a global list. And that the timing be reported in GMT all the time. You can set the Default TimeZone by doing TimeZone.setDefault(TimeZone.getTimeZone("GMT")). Warning: Do this with care. Because, all future Calendar.getInstance() calls will be in GMT.

Another important gotcha is when we are parsing a DATE string. Simply the innocent looking following code is soooo Evil

SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd hh:mm:ss");
Date userDate = sdf.parse("2009-01-21 13:53:58");

Running this in two different (in timezone) VM at the same time(like on a network or something) will yeild in DIFFERENT Date object. To eliminate that bug, Either Read it with timeZone or setTimeZone on sdf like this

SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd hh:mm:ss z");
//or
sdf.setTimeZone(TimeZone.getTimeZone("EST"));

Update: A small test case to complement theory!