GregorianCalendar : Java Glossary

Pope Gregory XIII improved the accuracy of the Julian calendar by dropping the leap year every century and adding it back every 400 years.

java.util.GregorianCalendar Gotchas

• Had there been programmers when Daylight Saving Time was first proposed, they would have vetoed it as insane and intractable. With daylight saving, there is a fundamental ambiguity. In the fall when you set your clocks back one hour at 2 AM there are two different instants in time both called 2:00 AM local time. You can tell them apart only if you record whether you intended daylight saving or standard time with the reading. Unfortunately, there is no way to tell GregorianCalendar which you intended. You must resort to telling it the local time with the dummy UTC TimeZone to avoid the ambiguity. Programmers usually close their eyes to this problem and just hope nobody does anything during this hour.
• Millennium bug. The bugs are still not out of the Calendar classes. Even in JDK (Java Development Kit) 1.3 there is a 2001 bug. Consider the following code:

  gc = new GregorianCalendar();
  gc.setLenient( false );
  /* Bug only manifests if lenient set false */
  gc.set( 2001, 1, 1, 1, 0, 0 );
  nYear = gc.get ( Calendar.YEAR );
  /* throws exception */

  The bug disappears at 7AM on 2001/01/01 for MST.
• GregorianCalendar is controlled by a giant of pile of untyped int magic constants. This technique totally destroys any hope of compile-time error checking. For example to get the month you use GregorianCalendar.get(Calendar.MONTH));
• GregorianCalendar has the raw GregorianCalendar.get(Calendar.ZONE_OFFSET) and the daylight savings GregorianCalendar.get(Calendar.DST_OFFSET), but no way to get the actual time zone offset being used. You must get these two separately and add them together.
• GregorianCalendar.set(year, month, day, hour, minute) does not set the seconds to 0.
• DateFormat and GregorianCalendar do not mesh properly. To get them to work, you must clumsily must specify the Calendar twice, once indirectly as a Date. see my essay for details.
• If the user has not configured his time zone correctly it will default quietly to either PST (Pacific Standard Time) or GMT (Greenwich Mean Time).
• In GregorianCalendar, Months are numbered starting at January=0, rather than 1 as everyone else on the planet does. Yet days start at 1 as do days of the week with Sunday=1, Monday=2,… Saturday=7. Yet DateFormat.parse behaves in the traditional way with January=1.
• In SimpleDateFormat, by default has setLenient( true ); which mean that March 32, when parsed, is a valid date. Further, two digit years, e.g. 02 are not converted in the usual way, 02 means the year 0002.
• This gotcha is not Java’s fault, but rather comes from the odd ISO (International Standards Organisation) definition of week number.

Learning More