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

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

(Original article : http://blog.sarathonline.com/2009/01/javas-calendar-date-and-timezone-what.html)

 

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 =newDate();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 codeSystem.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 =newSimpleDateFormat("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 =newSimpleDateFormat("yyyy-MM-dd hh:mm:ss z");//or
sdf.setTimeZone(TimeZone.getTimeZone("EST"));

Update: A small test case to complement theory:

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.Timestamp;
import java.text.SimpleDateFormat;
import java.util.Calendar;
import java.util.Date;
import java.util.TimeZone;

import junit.framework.TestCase;

import org.apache.commons.lang.time.FastDateFormat;

public class DateExampleTest extends TestCase {

	String userEntered = "2009-01-31 00:00:00";
	SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd hh:mm:ss");
	TimeZone userTimeZone = TimeZone.getTimeZone("PST");

	public void testOpSystem() throws Exception {

		System.out.println("========== OUTPUT TEST =================");
		// This test only proves that internally, all dates and cals
		// use same timeinmills if System date is considered.
		Date nowDate = new Date();
		Calendar cal = Calendar.getInstance();
		System.out.println("All 3 Should be the same");
		System.out.println(nowDate + " :: " + nowDate.getTime());
		System.out.println(cal.getTime() + " :: " + cal.getTimeInMillis());
		System.out.println(decorate(cal) + " :: " + cal.getTimeInMillis());

		System.out.println("\nUnderlying  Time is same, but cal will *show* offset");
		System.out.println("SYS:" + nowDate + " :: " + nowDate.getTime());
		cal = Calendar.getInstance(TimeZone.getTimeZone("PST"));
		System.out.println("CAL:" + cal.getTime() + " :: " + cal.getTimeInMillis());
		System.out.println("PST:" + decorate(cal) + " :: " + cal.getTimeInMillis());

		System.out.println("\nChanging timezone AFTER it is set, but cal will *show* offset");
		System.out.println("SYS:" + nowDate + " :: " + nowDate.getTime());
		cal = Calendar.getInstance();
		System.out.println("000:" + cal.getTime() + " :: " + cal.getTimeInMillis());
		System.out.println("EST:" + decorate(cal) + " :: " + cal.getTimeInMillis());
		cal.setTimeZone(TimeZone.getTimeZone("PST"));
		System.out.println("111:" + cal.getTime() + " :: " + cal.getTimeInMillis());
		System.out.println("PST:" + decorate(cal) + " :: " + cal.getTimeInMillis());
		System.out.println("set time zone MST will *show* offsetted time ");
		cal.setTimeZone(TimeZone.getTimeZone("CST"));
		System.out.println("CST:" + decorate(cal) + " :: " + cal.getTimeInMillis());
	}

	/**
	 * Wrong way of doing, changes with VM
	 * @throws Exception
	 */
	public void testInSimpleParseSystem() throws Exception {
		System.out.println("========== Parse def ================");
		String userEntered = "2009-01-31 00:00:00";
		SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd hh:mm:ss");
		TimeZone userTimeZone = TimeZone.getTimeZone("PST");

		System.out.println("No tz, takes system timezone");
		Date userDate = sdf.parse(userEntered);
		// timeInMilliSecs changes with system!!!
		System.out.println("SYS:" + userDate + " :: " + userDate.getTime());
		// setting this date to a cal and changing timezone is not right
		Calendar cal = Calendar.getInstance();
		cal.setTime(userDate);
		cal.setTimeZone(userTimeZone);
		// Observe TimeZone in Output
		System.out.println("CAL in SYS:" + cal.getTime() + " :: " + cal.getTimeInMillis());
		System.out.println("CAL:" + decorate(cal) + " :: " + cal.getTimeInMillis());
	}
	
	/**
	 * Correct way of doing
	 * @throws Exception
	 */
	public void testInSimpleParseTZParam() throws Exception {
		System.out.println("========== Parse Specific TZ ================");
		// Right way is to PARSE with TZ // parser sets mill secs
		System.out.println("\nparse with tz, independent of System");
		sdf.setTimeZone(userTimeZone);
		Date userDate = sdf.parse(userEntered);
		// will show in Sytem Time Zone but is = userDate in userTimeZone
		System.out.println("ENT:" + userDate + " :: " + userDate.getTime());
		// timeInMilliSecs DOESNOT change with system
		Calendar cal = Calendar.getInstance(userTimeZone);
		cal.setTime(userDate);
		System.out.println("USR:" + decorate(cal) + " :: " + cal.getTimeInMillis());
	}

	/**
	 * Correct way of doing
	 * @throws Exception
	 */
	public void testInSimpleCalTZManualSet() throws Exception {
		System.out.println("========== Parse def ================");
		// set values as if they were manually set (mutates mill secs)
		System.out.println("\nManaul setting with tz, independent of System");
		Calendar cal = Calendar.getInstance();
		System.out.println("CAL in SYS:" + cal.getTime() + " :: " + cal.getTimeInMillis());
		System.out.println("CAL:" + decorate(cal) + " :: " + cal.getTimeInMillis());
		cal.clear(); // This is important, otherwise unpredictible.
		cal.setTimeZone(userTimeZone);
		cal.set(Calendar.DATE, 31);
		cal.set(Calendar.YEAR, 2009);
		cal.set(Calendar.MONTH, Calendar.JANUARY);
		cal.set(Calendar.HOUR, 0);
		cal.set(Calendar.MINUTE, 0);
		cal.set(Calendar.SECOND, 0);
		System.out.println("CAL in SYS:" + cal.getTime() + " :: " + cal.getTimeInMillis());
		System.out.println("CAL:" + decorate(cal) + " :: " + cal.getTimeInMillis());
	}

	public void testOpDBRead() throws Exception {

		System.out.println("========== DATABASE READ TEST =================");
		Connection conn = null;
		try {
			conn = getConnection();
			PreparedStatement ps = conn.prepareStatement("select dt, tms, faceval from datex where id = ?");
			System.out.println("========== Row 1 =================");
			ps.setInt(1, 1); // First Row
			printRow(ps.executeQuery());
			System.out.println("========== Row 2 =================");
			ps.setInt(1, 3); // Second Row
			printRow(ps.executeQuery());

		} catch (Exception e) {
			e.printStackTrace();
		} finally {
			if (conn != null) {
				conn.close();
			}
		}

	}

	public void testDBWrite() throws Exception {

		String userEntered = "2009-01-31 00:00:00";
		SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd hh:mm:ss");
		TimeZone userTimeZone = TimeZone.getTimeZone("EST");

		Date userDate = sdf.parse(userEntered);

		System.out.println("========== DATABASE Write TEST =================");
		Connection conn = null;
		try {
			conn = getConnection();
			PreparedStatement ps = conn.prepareStatement("insert into datex(dt, tms, faceval) values (?,?,?)");
			ps.setDate(1, new java.sql.Date(userDate.getTime()));
			ps.setTimestamp(2, new Timestamp(userDate.getTime()));
			ps.setString(3, userDate.toString());
			ps.execute();
			
		} catch (Exception e) {
			e.printStackTrace();
		} finally {
			if (conn != null) {
				conn.close();
			}
		}

	}

	private void printRow(ResultSet rs) throws Exception {
		rs.next();
		// JDBC driver reads by face value, loses date info
		java.sql.Date sqlDate = rs.getDate("dt");
		Calendar cal = Calendar.getInstance();
		cal.setTime(sqlDate);
		System.out.println("Date Information");
		System.out.println(sqlDate + "::" + sqlDate.getTime() 
				+ " :: " + cal.getTime() + " :: " + cal.getTimeInMillis() + " :: " + decorate(cal));

		// JDBC driver reads by face value, applies system tz, (mutates mill secs)
		Timestamp sqlTS = rs.getTimestamp("tms");
		cal = Calendar.getInstance();
		cal.setTime(sqlTS);
		System.out.println("Timestamp Information");
		System.out.println(sqlTS + "::" + sqlDate.getTime() 
				+ " :: " + cal.getTime() + " :: " + cal.getTimeInMillis() + " :: " + decorate(cal));


		// JDBC driver reads by face value, applies the supplied tz that is supplied (mutates mill secs)
		cal = Calendar.getInstance(TimeZone.getTimeZone("MST"));
		sqlTS = rs.getTimestamp("tms", cal);
		cal.setTime(sqlTS);
		System.out.println("Timestamp Information read with a different Cal");
		System.out.println(sqlTS + "::" + sqlDate.getTime() 
				+ " :: " + cal.getTime() + " :: " + cal.getTimeInMillis() + " :: " + decorate(cal));

	}

	private String decorate(Calendar cal) {

		FastDateFormat f = FastDateFormat.getInstance("EEE MMM dd HH:mm:ss z yyyy");
		return f.format(cal);
	}

	private Connection getConnection() throws Exception {
		Class.forName("oracle.jdbc.OracleDriver");
		String url = "jdbc:oracle:thin:@localhost:1521:xe";

		return DriverManager.getConnection(url, "sarath", "pass");
	}

}