Date : Java Glossary

Date
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 .

Learning More

Oracle’s Javadoc on Date class : available:
BigDate for handling pure dates without times
Calendar: essay on Dates and Calendars
clock
Date gotchas
DateSpinner: free component to select a date using year/month/day spinners
DecimalFormat
GMT
gotchas
Gregorian Calendar gotchas
JDatePicker: component to select date by clicking a calendar
missing days
SimpleDateFormat
TAI
time
time sources
timestamp
UTC

CMP homejump to top

available on the web at:

http://mindprod.com/jgloss/date.html
  

optional Replicator mirror
of mindprod.com
on local hard disk J:

J:\mindprod\jgloss\date.html
logo
Please email your , letters to the editor, errors, omissions, typos, formatting errors, ambiguities, unclear wording, broken/redirected link reports, suggestions to improve this page or comments to Roedy Green : feedback email. If you want your message, your name or email kept confidential, not considered for public posting, please explicitly specify that. Unless you state otherwise, I will treat your message as a letter to the editor that I may or may not publish in the feedback section. After that, it will be too late to retract it. If you disagree with something I said, especially when sending an ad-hominem attack, a rant composed mainly of obscenities or a death threat, please quote the offending passage and cite the web page where you found it, tell me why you think it is wrong, and, if possible, provide some supporting evidence. I can’t very well fix erroneous or ambiguous text if I can’t find it.
Blog
IP:[65.110.21.43]
Your face IP:[107.22.127.92]
You are visitor number 59,473.