Contents | Prev | Next

Calendar and Time Zone Support

JDK 1.0 introduced the java.util.Date class for the representation of dates. The java.util.Date class allowed for the interpretation of dates as year, month, day, hour, minute and second values, and it formatted and parsed date strings. Unfortunately, the API for these functions was not amenable to internationalization. Only the "representation" part of this class is retained in JDK1.1.

As of JDK 1.1, the Date class should only be used as a wrapper for a date. That is, Date objects represent a specific instant in time with millisecond precision. The java.util.Calendar class should be used to convert between dates and time fields and the java.text.DateFormat class should be used to format and parse date strings. The corresponding methods in the JDK 1.0 version of java.util.Date are deprecated.

Calendar

The class Calendar is an abstract base class which can convert between a point in time (represented as milliseconds from 00:00:00 GMT, Jan 1, 1970) and a set of integers representing the year, month, week and so on. GregorianCalendar is a concrete subclass of Calendar that does this according to the rules of the Gregorian calendar. In future, subclasses could be provided to represent the various lunar calendars used in many countries.

Calendar and its subclasses are useful for doing various manipulations with time values. Arithmetic can be performed on a Calendar's fields and the resulting date determined. A Calendar can also take "funny" dates like the 35th day of the 2nd month and normalize them. The following example shows how GregorianCalendar is used to determine if today is a weekday.

TimeZone tz = TimeZone.getDefault();

	// this constructor initializes the new GregorianCalendar

	// object with System.currentTimeMillis()

GregorianCalendar calendar = new GregorianCalendar(tz);

calendar.computeFields();

int dayOfWeek = calendar.get( Calendar.DAYOFWEEK );

if( dayOfWeek == Calendar.SATURDAY

	|| dayOfWeek == Calendar.SUNDAY ) {

	System.out.println("Weekend!");

} else {

	System.out.println("Weekday");

}

Note - Calendar does not handle text representations of dates. That is the job of DateFormat. However, Calendar is used by DateFormat.

TimeZone

The abstract class TimeZone encapsulates a time zone offset from UTC¹ (Universal Coordinated Time) and a possible daylight-savings time offset. The class SimpleTimeZone is a concrete subclass that encapsulates some simple rules about daylight-savings time. These rules do not take into account historical changes in the laws affecting daylight-savings time. TimeZone and SimpleTimeZone are used by Calendar and its subclasses to convert between local time and UTC which is the internal representation used by Date objects. Most programs will not have to deal with TimeZone directly.

Note that in order to correctly handle historical daylight savings time calculations, the API for the TimeZone class may need to be modified. This is being examined during the beta period. During the beta period, developers are encouraged to not use TimeZone directly but take advantage of it through the Calendar class.

Contents | Prev | Next

¹ For our purposes, UTC is the same as GMT. See the JavaDoc for the Date class for a careful description of the actual differences.

java-intl@java.sun.com