Calendar : Java Glossary

For newbies, dealing with dates and times are the probably the most confusing aspect of Java. There are three reasons for this:

1. The date and time classes are the most poorly designed of all the Sun class libraries.
2. The standard class libraries force you to deal with timezone and time of day, even when they are irrelevant to your problem.
3. The vocabulary used in the various date classes is inconsistent.

Review

The earth rotates every 24 hours. The sun is highest in the sky at solar noon, once each rotation, for any given spot on the earth. Railway schedules where hard to co-ordinate when towns even a few miles apart celebrated noon at a slightly different instant in time. So, Sir Sandford Fleming invented 24 time zones, within each, time was uniform. Astoundingly, he managed to sell the idea to the entire planet. The boundaries are essentially meridians every 360 ÷ 24 = 15 degrees (1 hour). There are jogs in them to accomodate political realities.

The earth rotates from west to east. This means the British see noon, 5 hours before New Yorkers who see it in turn 3 hours before the inhabitants of Seattle. London is is timezone UTC:0, New Yorkers EST/UTC-5, Seattle PST/UTC-8. In other words, to get Seattle time, you take UTC (Greenwich time) and subtract 8 hours.

Anyone who has flown over the Pacific ocean to Asia has crossed the International date line. When you cross it going west to east, the day of the week jumps ahead a day. The planet does not simultaneously flip from Monday to Tuesday. The people living just east of the International Date Line flip first, then an hour later the people living 15 degrees east of that flip, and finally 23 hours later the people living just west of the International Date Line flip. So Tuesday washes over the earth like a wave.

The entire planet is never entirely on Tuesday.

During wars, politicians wanted people to get up earlier to conserve electricity in the evening. They came up with the bizarre idea of adjusting the clocks to trick people into compliance. This was originally called war time, then later DST Daylight Saving Time. It created chaos in many ways. Part of the problem is the days for changing clocks forward and back and whether DST is used at all are completely non-standard. Java has to maintain giant tables to track what each city on the planet does with DST, and the history of what they have done in past.

The most important fact to drill into your brain is it makes no sense to ask what day of the week a given instant in time (i.e. Java long timestamp) is. You must ask what day of the week it was at that instant in a particular timezone. It also depends the particular location within that timezone was using DST at the time. Java uses micro-timezones, usually named after cities, each of which has a the same DST rules and history.

The moon rotates around the earth once every 27 days and 8 hours, one lunar month (moonth), The Gregorian solar calender we use today uses a month of 28 to 31 days.

The earth rotates around the sun once every 365.242190 days, or one solar year. We use a system of leap years with years of either 365 or 366 days so pretend a year is an even number of days.

Human biology is synchronised to the solar day, the lunar month and the solar year. The weirdness of our civil calendars come from trying to pretend that lunar months and solar years are actually even multiple of days.

Vocabulary

atomic clock

A highly accurate clock that monitors the frequency of light emited by excited atoms or even a single atom, originally caesium atoms, or clock that is accurately synched to such a clock.

day of month

The day of the month 1..31. Sometimes called the date.

day of week

Day of the week for a given date, e.g. Sunday = 1,… Saturday = 7.

DST offset

Daylight Saving Time offset. The number of milliseconds correction to account for daylight saving time, 0 if daylight saving time is not in effect for the timestamp specified. If a one-hour daylight saving is in effect, the offset will be 3600000. You add the DST offset and the zone offset to UTC to get local time.

GMT

A historic time standard derived by observing the sun at the prime meridian at the Royal Observatory, Greenwich, England. It has been supplanted by the more stable SI UTC standard based on an atomic clock.

Gregorian calendar

Pope Gregory’s calendar we use today that has leap year corrections every 4, 100 and 400 years.

ISO day of week

Day of the week 1 to 7 for this date according to the ISO standard ISO-8601. Monday = 1… Sunday = 7.

ISO week number

Week number 01 to 53 of the year this date falls in, according to the rules of ISO standard ISO-8601. Week 1 of any year is the week that contains 4 January, or equivalently week 1 of any year is the week that contains the first Thursday in January. A week that lies partly in one year and partly in another is assigned a number in the year in which most of its days lie. Most years have 52 weeks, but years that start on a Thursday and leap years that start on a Wednesday have 53 weeks. January 1 may well be in week 53 of the previous year! ISO specifies a lead 0 to create a 2-digit year. Java does not do that unless you code the display specially.

Julian Date

I know of eight different definitions.

leap second

an extra second added to the day every roughly every 3 to 7 years to keep the UTC clock in sync with the rotation of the earth.

leap year

an extra day added to the year to keep the calendar in sync with the revolution of the earth around the sun.

month of year

January to December. Note that in GregorianCalendar, January is month 0. In contrast, in DateFormat, January is month 1.

offset

How many milliseconds difference local time is from UTC. If you live is North America this will be a negative number. It is the sum of the zone offset and the DST offset. You add the DST offset and the zone offset to UTC to get local time.

summer time

In much of the world, people adjust their clocks to trick themselves into getting up an hour earlier in summer.

timestamp

An instant in cosmic time, expressed in milliseconds since 1970-01-01 0:00 in UTC. It can be a positive or negative 64-bit long number. These are sometimes called Dates and sometimes Times.

time zone

a region of the earth that keeps the same winter time. They may or may not all flip to summer time at the same time and some parts may not flip at all.

TimeZone

A TimeZone is a Java class for a region of the earth that keeps the same time. If they keep different time in summer and winter, everyone is the region flips together. The TimeZone class describes the offset from UTC in summer and winter time and when the flips occur of a given time zone.

UTC

UTC stands for Coordinated Universal Time, huh? not CUT? It was a weird compromise acronym half way between French and English. It is a refinement of GMT. The SI (Systeme Internationale) UTC standard based on a stable atomic clock. UTC is the time system used internally in Java for Date, Calendar and System. currentTimeMillis. Windows NT/W2K/XP/W2K3/Vista/W7 use UTC internally to track file dates.

week of year

There are many possible definitions. The default GregorianCalendar definition depends on whether you consider Sunday or Monday as the first day of the week setFirstDayOfWeek, (the default is locale specific) and how many days you insist must be present in the first week of the year setMinimalDaysInFirstWeek, (default 1). The first week of the year is week 1. January 1 may sometimes be considered week 53 of the previous year.

zone offset

milliseconds difference that local time is from UTC if you ignore any daylight saving time correction. West of the prime meridian that runs through Greenwich England, i.e. in west Africa and North and South America America, this will be a negative number. Also Oceania (aka Oceana) in the Pacific Ocean east of the Interational Date line will also have a negative offset. You add the DST offset and the zone offset to UTC to get local time.

The Cast

Today’s Date

Displaying A Date

DateFormat: Displaying A Date With Precise Control

Zulu Time

Local Time

Parsing/Validating A Date

• Be very careful with TimeZones. If you don’t specify one, your date will be interpreted using the local default TimeZone. If the user has not configured it correctly in his OS, you may get Pacific Standard time or GMT, without warning.

Elapsed Time in Years, Months and Days

Elapsed Time In Hours Between Two Timestamps

• You specify the timestamp with GregorianCalendar.set in terms of Eastern Standard time, not UTC. Internally the timestamp is stored as UTC.
• You don’t create the TimeZone object with new.
• The getTime().getTime() is not an error. The first getTime retrieves a Date object from the GregorianCalendar, and the second retrieves a timestamp from the Date object.
• Elapsed time in days is not simply hours / 24. It is much more complicated than that.

How Long Until Christmas, Daddy?

Taking A Timestamp Apart

//taking a timestamp apart using default timezone.
GregorianCalendar cal = new GregorianCalendar();
cal.setTimeInMillis( timestamp );
int year = cal.get( Calendar.YEAR );
int month = cal.get( Calendar.MONTH ) + 1;
int day = cal.get( Calendar.DAY_OF_MONTH );
int hour24 = cal.get( Calendar.HOUR_OF_DAY );
int hour12 = cal.get( Calendar.HOUR );
int amIs0OrPmIs1 = cal.get( Calendar.AM_PM );
int minute = cal.get( Calendar.MINUTE );
int second = cal.get( Calendar.SECOND );

Building A Timestamp from the Pieces

// buiding a timestamp using default timezone.
GregorianCalendar stamp = new GregorianCalendar();
stamp.clear();
stamp.set( year, month-1, day, hour, minute, second );
longtimestamp = stamp.getTimeInMillis();

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 back one hour at 2 AM there are two different instants in time both called 1:30 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 1.3 there is a 2001 bug. Consider the following code:

  GregorianCalendar gc = new GregorianCalendar();
  gc.setLenient( false );
  /* Bug only manifests if lenient set false */
  gc.set( 2001, 1, 1, 1, 0, 0 );
  int year = 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 timezone 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. You must specify the Calendar twice, once indirectly as a Date.
• If the user has not configured his timezone correctly it will default quietly to either PST or GMT.
• 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.
• Locale.setDefault ( Locale. ITALY) will not have any effect on SimpleDateFormat objects already created. You need to set the default Locale before creating your SimpleDateFormat objects or use the SimpleDateFormat constructor that takes a Locale.
• Beware, in JavaScript, the parsing of dates is not properly defined. How it works varies from browser. launch = Date.parse("Fri, 20 Nov 1998 00:20:00 CST"); will, in Opera, for example, be interpreted ignoring the CST, taking the default timezone instead.

TimeZones

Here is a list of available timezones:

Standard : (DaylightSaving) : TimeZone

If, tz, the above TimeZones Java Applet does not work…

1. This Java Applet needs Java 1.6 or later, version 1.6.0_17 recommended and a recent browser.
2. You should see the Applet above looking much like the screenshot. If you don’t, the following should help you get it working:
3. If you are using Microsoft Internet Explorer, try another browser. Seriously. Microsoft has taken great pains, over and over, to screw up Java and every other multi-platform standardisation.
4. If you are using Internet Explorer 7 or 8, you must allow blocked content permission for Active X to run. This also gives permission to Java to run. Click the Information bar, and then click Allow blocked content. Unfortunately, this also allows dangerous ActiveX code to run. However, you must do this in order to get access to perfectly-safe Java Applets running in a sandbox. This is part of Microsoft’s war on Java. Don’t put up with it! Use a different browser.
5. Especially if this Applet has worked before, try clearing the browser cache and rebooting.
6. To ensure your Java is up to date, check with Wassup. First, download it and run it as an application independent of your browser, then run it online as an Applet to add the complication of your browser.
7. If the above Applet does not work, check the Java console for error messages.
8. If the above Applet does not work, you might have better luck with the downloadable version.
9. If you are using Mac OS X and would like an improved Look and Feel, download the QuaQua look & feel from randelshofer.ch/quaqua. UnZip the contained quaqua.jar and install it in ~/Library/Java/Extensions or one of the other ext dirs.
10. If you still can’t get the program working click HELP for more detail.
11. If you can’t get the above Applet working after trying the advice above and from the HELP button below, have bugs to report or ideas to improve the program or its documentation, please send me an email at.

   Get New Java  Get New Browser   Help

• Add column 1 in hours to UTC to get local standard time.
• Add column 2 in hours to UTC to get local daylight saving time.
• Use UTC when you want no time zone at all.
• Use Asia/Riyadh for Arabia Standard Time. Asia/Riyadh87, Asia/Riyadh88 and Asia/Riyadh89 are 3 hours and 7 minutes east of UTC. This is the offset used in 1987 to 1989. Actually it was 3 hours 7 minutes and 4 seconds to approximate solar time. Prior to 1950 they used 3:06:52. In the period 1951— 1986 and 1990 onward they used a simple 3 hour difference. In Islamic tradition, the day starts at sunset.
• Note how much many aliases there are for the same timezone. I speculate there are two reasons for this:
  1. To anticipate some geographical region adopting a quirky daylight saving rule in future. There would be no need adjust to a new split timezone to adopt the new rule. Only the tables built into Java would need to be adjusted.
  2. It makes it easier for people to find their own timezone. They need find only a nearby city without having to consult a map to find a distant city on the same longitude. Often they can find their own city directly.

Books

	recommend book⇒Calendrical Calculations
		paperback	hardcover
	ISBN13:	978-0-521-70238-6	978-0-521-88540-9
	publisher:	Cambridge University Press
	published:	2007-12-10
	by:	Edward M. Reingold and Nachum Dershowitz
How to compute solstices, equinoxes, new moons, Western, Chinese and Muslim holidays. Has been reissued several times. Make sure you get the most recent edition.
abe books.co.uk abe books.ca amazon.co.uk amazon.ca abe books.de chapters.indigo.ca amazon.de abe books.com abe books.fr amazon.com amazon.fr barnes and noble.com abe books.it powells.com iberlibro.com sony e-books abe books anz

Learning More

Dealing with pure dates is much simpler using the BigDate class. You can download it from http://mindprod.com/products1.html#BIGDATE

Sun is going to try redesigning Date/Time a third time, in Java 1.7, this time based on Joda Time, so you can also have dates without times (like BigDate), times without dates, intervals…

You need to use quite a few different classes to solve even a simple problem involving dates. Examine the