If you run this on a US English system, the result will be "Friday, January 1, 1999 00:00:00 AM PST".

So far, this just seems like an expensive way of spelling Date.toString. But you get something for the extra effort: internationalization. If you change the second line of code to this:

DateFormat f = DateFormat.getDateTimeInstance(DateFormat.FULL,

                                              DateFormat.FULL,

                                              Locale.FRANCE);

DateFormat also solves the fixed-format problem. The examples above uses a "FULL" date/time formatter. If you want to be a bit more concise, you can use DateFormat.MEDIUM, which gives the result "Jan 1, 1999 00:00:00 AM" for English. Similarly, DateFormat.SHORT gives "1/1/99 00:00 AM."

If you want to see just the date in your output, not the time, the solution is also simple -- call getDateInstance instead of getDateTimeInstance :

Date d = new Date(99, 0, 1);

DateFormat f = DateFormat.getDateInstance(DateFormat.FULL);

String s = s.format(d);

and the result will be "January 1, 1999."

Now, remember the Date constructor that takes a String. That constructor had the same problems as toString , but in reverse: it required a fixed format and it assumed the string would be in English. DateFormat solves these problems too, because it doesn’t just format dates; it parses them. For example, consider the following code:

DateFormat f = DateFormat.getDateInstance(DateFormat.FULL,

                                          Locale.FRANCE);

Date d = f.parse("venredi 1 janvier 1999");

The Date object, d, will end up referring to 1/1/1999. All of the other points I discussed above apply to parsing as well as to formatting: you can request a particular locale, choose shorter or longer formats, etc.

Many of the DateFormat examples I showed above included time zones in their output. In JDK 1.0, all of Java's time zone logic was baked into Date.toString. It assumed that you always wanted dates displayed using the current default time zone, and that you wanted the US English abbreviations for the time zone names. This was fixed in JDK 1.1 as well, with the addition of the new class java.util.TimeZone.

TimeZone and its concrete subclass SimpleTimeZone are relatively low-level classes that encapsulate the relationship between local clock time and Greenwich Mean Time. You can use them to convert from GMT to local time and back as well as to determine whether daylight savings time is in effect. The other classes use TimeZone in their time-related calculations, and many of them expose the time zone as a property that you can get and set.

Here's a simple example. Say that you want to display the same date we've been using in all of our examples, but that you want to force it to be displayed in GMT, regardless of the time zone you're running in. The code would look like this:

Date d = new Date(99, 0, 1);

DateFormat f = DateFormat.getDateTimeInstance(DateFormat.FULL);

f.setTimeZone(TimeZone.getTimeZone("GMT"));

String s = s.format(d);

The formatter will now use GMT, so the result will be something like " Friday, January 1, 1999 08:00:00 AM GMT ". Note that the time zone is different, and that the time of day is 08:00, since GMT is 8 hours ahead of PST.

In JDK 1.1, there was one problem with the way that DateFormat used TimeZone. Let's jump back to this example for a moment:

Date d = new Date(99, 0, 1);

DateFormat f = DateFormat.getDateTimeInstance(DateFormat.FULL,

                                              DateFormat.FULL,

                                              Locale.FRANCE);

String s = s.format(d);

As I mentioned above, you'd expect the result to be "venredi 1 janvier 1999 00:00:00 GMT-08:00" if you were running your computer in the Pacific time zone. However, in JDK 1.1.5 and earlier, the result would actually be "venredi 1 janvier 1999 09:00:00 CEST". CEST is "Central European Standard Time", the time zone used in Paris, which is one hour ahead of GMT. Rather than using the system's default time zone, DateFormat was using the first time zone it could find for the locale you requested, in this case Locale.FRANCE. This caused no end of confusion, since it was almost never what programmers expected.

Fortunately, there was a simple workaround for this problem. To force a DateFormat to use the default time zone, you just do this:

DateFormat f = . . . .;

f.setTimeZone(TimeZone.getDefault());

In JDK 1.1.6 we fixed this problem, and a newly-created DateFormat object always uses the default time zone. If you need a different time zone, you can always call DateFormat.setTimeZone to request the one you want.

Now that I've given a quick tour of the other date-related classes that were new to JDK 1.1, I can go on to the meat of this article: java.util.Calendar. As an introduction, let's revisit a code snippet from our discussion of Date :

Date d = new Date(99, 1, 1);

In this example, the constructor arguments are interpreted in only one way: February 1, 1999 AD, in the Gregorian calendar. There's a similar problem with Date methods such as getDay, getMonth, getYear, etc. But as I described in the introduction, some countries use different calendars: Hebrew, Hijri, or whatever. A fully-internationalized Java application needs to be able to support multiple calendar systems, not just the Gregorian one.

Since the Java Class Libraries are object-oriented, the obvious solution to this problem is to create an abstract class that represents a generic calendar, with concrete subclasses for specific calendar systems. And that's just what we did. JDK 1.1. included a new abstract class, java.util.Calendar, which provides a generic API for calendar operations. It also included one concrete subclass, which as you might guess is GregorianCalendar.

Calendar has a number of abstract methods that parallel the old, deprecated get methods of Date. For example, imagine that you want to find out what year it is. With the old Date API, the code would look like this:

int year = new Date().getYear();

With Calendar, you do this instead:

int year = Calendar.getInstance().get(Calendar.MONTH);

The call to getInstance creates a Calendar that is appropriate for the current locale, and the call to get returns the current value of the calendar's MONTH field. Calendar provides constants for about fifteen fields, including YEAR, DAY_OF_MONTH, DAY_OF_WEEK, WEEK_OF_YEAR, and many others. These constants are all interpreted in terms of the calendar system that your Calendar object represents, so if you have a Hebrew calendar object, you'll get the Hebrew month, not the Gregorian one.

If you're wondering how this works, remember that Calendar is an abstract class. Each time that get is called, the calendar checks to see if the fields are up to date. If they are not, it calls the abstract, protected method computeFields. Each subclass overrides this method to perform the calculations appropriate for that calendar system. For example, GregorianCalendar has a computeFields method that performs the standard Gregorian calculations.

Calendar.get replaces the deprecated get methods on Date, but what about the constructor? That functionality is provided by constructors on the concrete Calendar subclasses. If you want to construct a Calendar set to January 1, 2000, you write:

Calendar c = new GregorianCalendar(2000, Calendar.JANUARY, 1);

This solves the problem neatly. You know exactly which calendar system will be used to interpret the year, month, and day that you've specified: the calendar that you're instantiating. If someone has input a Hebrew date, and you have a HebrewCalendar class, the code is fairly obvious:

Calendar c = new HebrewCalendar(5760, HebrewCalendar.TEVET, 23);

You would think that when we deprecated most of Date and added the new Calendar class, we would have fixed Date's biggest annoyance: the fact that January is month 0. We certainly should have, but unfortunately we didn't. We were afraid that programmers would be confused if Date used zero-based months and Calendar used one-based months. And a few programmers probably would have been. But in hindsight, the fact that Calendar is still zero-based has caused an enormous amount of confusion, and it was probably the biggest single mistake in the Java international API's.

When you're using Calendar or any of its subclasses, it's usually best not to use raw numbers in Calendar calls unless you just can't avoid it. Instead of writing code like this:

Calendar c = new GregorianCalendar(2000, 0, 1);

write this instead:

Calendar c = new GregorianCalendar(2000, Calendar.JANUARY, 1);

One aspect of Calendars that wasn't addressed at all in Date was calendar manipulation. For example, imagine that you want to determine what the date will be one month in the future. With the old API, you had to do an awful lot of work on your own: call getMonth, getYear, and getDate, add one to the month, see if it wrapped to a new year, make sure the day of the month is still in bounds (remembering those leap years!) and so on. Not only is this a hassle, it's not internationalized. Other calendar systems have a different number of days per month, different (and possibly variable) months per year, different leap year calculations, and so on.

Calendar and its subclasses solve this problem for you, with their add and roll methods. If you want to add one month to the current date, you only need two lines of code:

Calendar c = Calendar.getInstance();

c.add(Calendar.MONTH, 1);

As you'd expect, the add method adds the given number to the field that you specify. It knows about all of the rules for the calendar system, so code like this will work properly.

GregorianCalendar c = new GregorianCalendar(1999, Calendar.JULY, 29);

c.add(Calendar.MONTH, 7);

String s = DateFormat.getInstance().format(c.getTime());

The result of this calculation will be February 29, 2000. GregorianCalendar.add knows that when the month passes 11 (December) it should roll back to 0. It also knows that February 29, 2000 is a valid date, using the complicated rules that it is a leap year because it's divisible by four, except it isn't because it's divisible by 100, except it is because it's divisible by 400.

Closely related to add is the roll method. This method is handy when you want to implement a user interface that "rolls" from the end of a month back to the beginning of the same month, or to do the same thing for weeks or years. The usage is almost identical to add:

GregorianCalendar c = new GregorianCalendar(1999, Calendar.JULY, 29);

c.roll(Calendar.DAY_OF_MONTH, 6);

Notice that in France, the first day of the week is Monday (or lundi), while in the United States it is Sunday. If you're writing an application that displays calendars graphically, you need to take this into account. Java provides the method Calendar.getFirstDayOfWeek to handle this. When you create a calendar, you can specify the locale you're interested in:

Calendar c = Calendar.getInstance(Locale.FRANCE);

and then call getFirstDayOfWeek to find out how to draw it:

int d = c.getFirstDayOfWeek();

A related method is getMinimalDaysInFirstWeek, which tells you how long a week has to be to qualify as the "first" week of the month. In the US calendar shown above, is the first week of July the week that starts on July 5, or the previous one that starts on June 27? According to Java's locale data it's the latter, because getMinimalDaysInFirstWeek returns 1.

All of the international calendar features I've talked about so far are great. However, there's a catch that limits the amount of calendar internationalization that you can actually do. Both JDK 1.1 and Java 2 only provide one concrete subclass of Calendar: GregorianCalendar. The traditional calendars used in other countries are not yet supported.

However, all is not lost. It entirely possible to create your own subclasses of Calendar that support different calendar systems. I've written classes that support the Buddhist, Hebrew, Hijri, and Japanese Imperial calendars, and I want to share some of that knowledge here.

When you look at the Calendar class, you'll notice that it has 11 abstract methods: add, after, before, equals, getMinimum, getMaximum, getGreatestMinimum, getLeastMaximum, roll, computeTime, and computeFields. Implementing your own calendar subclass requires that you override all of these methods to provide an implementation that's specific to your calendar system. These methods can be divided into three basic groups.

The first group, the minimum and maximum functions, are the easiest so these are usually the ones that I implement first. The first two, getMinimum and getMaximum, tell you the largest allowable range for each field, while getLeastMaximum and getGreatestMinimum , tell you the smallest range for the field. For example, the DAY_OF_MONTH field of GregorianCalendar has a minimum and maximum of 1 and 31, but a greatest minimum and least maximum of 1 and 29. Implementing this is easy. Since the result is a constant, you can just store it in a table. The methods almost always ends up looking like this:

public int getMinimum(int field) {

    return minMax[field][0];

}

The real heart of a calendar class consists of its computeFields and computeTime methods. The first, computeFields, calculates the values of all of the fields (year, month, day, etc.) from the absolute time, which is represented as the number of milliseconds since January 1, 1970. Conversely, computeTime uses the field values to calculate the absolute time.

These two methods are usually quite complicated, because they must implement the calendar system's rules very precisely. The details for a real calendar are way beyond the scope of this article, so I've invented a very simple calendar that we can experiment with. It has 360 days per year, divided into 12 months of 30 days each, with no leap years. There are seven days per week, just like our calendar, and the day 1/1/1 in this calendar was a Saturday. Based on this simplification, I can offer a few generalizations.

First, your calculations will usually be based on an "epoch" date on which the calendar started. Usually you'll want this to be the 0^th day of your calendar, that is the day before the first day of year 1. You should define a constant that specifies the epoch in milliseconds since 1/1/1970 AD. I'll start our example calendar on the same day the Hebrew calendar started, just because I have the constant handy:

private static final long EPOCH_MILLIS = -180799862400000L;

You'll also need a few constants for the number of milliseconds in a second, minute, hour, etc:

private static final long SECOND_MS = 1000;

private static final long MINUTE_MS = 60 * SECOND_MS;

private static final long HOUR_MS   = 60 * MINUTE_MS;

private static final long DAY_MS    = 24 * HOUR_MS;

Next, you'll want to get used to modular arithmetic, because you'll be doing a lot of it. Many of the calculations will be based on the number of days since the epoch, so you should calculate that first:

long absDay = (time - EPOCH_MILLIS) / DAY_MS;

Once you have that number, it's easy to calculate the year, month, and day:

int year  = (int)(absDay / 360) + 1;

int month = (int)((absDay / 30) % 12) + 1;

int day   = (int)(absDay % 30) + 1;

If you'd like to see some real Java classes that implement non-Gregorian calendars, pay a visit to http://www.alphaWorks.ibm.com/tech/calendars. The "International Calendars" package you'll find on that page supports the Buddhist, Hebrew, Hijri, and Japanese Imperial calendars. It includes Java ResourceBundle files containing translated strings for these calendars in a number of different languages, as well as some utility methods for formatting dates as strings using non-Gregorian calendars.

I hope this article has given you a good feel for the things that you can do with calendars in Java. Though it has its warts, Java's calendar framework is the most powerful one I've seen in any major operating system or application framework.

Laura Werner is the is the manager of the Unicode Technology Group at IBM Cupertino. She joined Taligent in 1994 and moved to the Unicode group in 1997, just before Taligent was absorbed into IBM. Laura became the group's manager in 1999 and is now responsible for coordinating the Java and C++ Unicode efforts at IBM Cupertino, helping to architect the Unicode class libraries, and working on occasional side projects such as this paper. Laura holds Bachelor’s degrees in Geological Sciences and Integrated Science from Northwestern University.