GregorianCalendar : Java Glossary
©1996-2017 2007-10-10 Roedy Green of Canadian Mind Products
Oracle’s replacement for the brain-damaged and now deprecated Date class.
GregorianCalendar needs both time and date set before it will function properly, even
for date-only functions.
Pope Gregory XIII improved the accuracy of the Julian calendar by dropping the
leap year every century and adding it back every 400
When you use the default new GregorianCalendar
, you specify the date and time in the current time
zone and locale and daylight saving, not UTC
(Coordinated Universal Time/Temps Universel Coordonné
java.util.GregorianCalendar has far fewer bugs
and gotchas than the old java.util.Date class but it is
still no picnic.
- 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
- 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 );
gc.set( 2001, 1, 1, 1, 0, 0 );
nYear = gc.get ( Calendar.YEAR );
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 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
- 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.
Oracle’s Javadoc on GregorianCalendar
class : available: