Date : Java Glossary


Java has no standard classes for handling pure dates without times. It does have the following classes: These are among the worst bits of code ever written. You can do quite a bit with
// get time in milliseconds since 1970 Jan 1
long timestamp = System.currentTimeMillis();
If you use pure longs, you don’t have to deal with time zones, leap years, months with variable number of days, regional differences, bulky objects, slow code and all the gotchas in the Date and Calendar classes. SQL (Standard Query Language) can’t screw up a long. It surely can a SQLDate. Think hard to keep the bulk of your application dealing with simple longs. Only use Date, Calendar or CalendarFormat when you need to input or output human-readable dates/times.

There are a ton of surprises and bugs awaiting the unwary users of these classes.

lemon java.util.Date Gotchas

The java.util.Date class is crawling with gotchas. It is a disgrace. It is the lemon of Java and deserves a giant string of raspberries. In Java version 1.2, Date has largely been deprecated and replaced by something even more complicated, Calendar/ GregorianCalendar.

The key to understanding Date is that it is not a date class, but a timestamp class. Inside each date is stored the number of milliseconds since 1970-01-01 UTC (Coordinated Universal Time/Temps Universel Coordonné) . It does not record the time zone or the timestamp in local time. You choose the time zone when you display the date with code like this:

With Date, you can’t have a date without a time. Keep in mind that when you display the same Date with different time zones you will sometimes get 1999-12-14 and sometimes 1999-12-25.

In contrast GregorianCalendar objects do contain a TimeZone reference along with the date and time. Like Dates, they are initialised with the current date and time. Unfortunately, if they are not sure about the user’s time zone, the Sun classes quietly revert to GMT and in early versions of GregorianCalendar, seem to revert to PST (Pacific Standard Time) if you so much as breathe on them. DateFormats also have TimeZone that is similarly erratic. For code to work, your clients must have configured the TimeZone correctly in the OS (Operating System). You can’t help them configure it.

One way out is to use my BigDate class which handles dates from 999,999 BC to 999,999 AD. Sun has deprecated most of the Date methods and replaced them with GregorianCalendar (which knows the TimeZone unlike Date). Date is still used for storing a date. GregorianCalendar would be far too bulky. GregorianCalendar has not nearly as many limitations as Date, it has got rid of those ridiculous 1900-based years, however, it is obscenely complicated, still relies on the old Date class and maintains a lot of the Date lunacy such as 0-based months. Happily the documentation in  Java version 1.2 is better, though ambiguity whether local or UTC parameters are wanted still plagues. Sun tends to be careless about documenting units of measure. For example in early JDK ’s you never knew if TimeZone offsets were measured in milliseconds, seconds or minutes. getTimeZoneOffset returns minutes, but GregorianCalendar.get(Calendar.ZONE_OFFSET) returns milliseconds. See essay on Dates and Calendars .

New Date-Time classes

In Java 1.8 there are new Date-Time classes. They are thread-safe and immutable.

Learning More

Oracle’s Javadoc on Date class : available:

This page is posted
on the web at:

Optional Replicator mirror
on local hard disk J:

Canadian Mind Products
Please the feedback from other visitors, or your own feedback about the site.
Contact Roedy. Please feel free to link to this page without explicit permission.

Your face IP:[]
You are visitor number