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 time zone 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 coordinate 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 accommodate 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 time zone UTC:0, New Yorkers EST/UTC-5, Seattle PST/UTC-8. In other words, to get Seattle time, you take UTC (Coordinated Universal Time/Temps Universel Coordonné) (similar to GMT (Greenwich Mean 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 time zone. It also depends the particular location within that time zone was using DST at the time. Java uses micro-time zones, 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 calendar 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 emitted by excited atoms or even a single atom, originally cesium 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

DST 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 (Systèm Internationale (metric)) 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-8601 (International Standards Organisation # 8601 (date/time)). 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-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

Coordinated Universal Time/Temps Universel Coordonné

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, this will be a negative number. Also Oceania (aka Oceania) in the Pacific Ocean east of the International 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

Here in how to display today’s date.

Displaying A Date

This program will convert a date to a String for display, using the default date format. That format depends on what the user has configured as his preferred date format in the OS (Operating System).

ISO-8601 Date Format Rant

DateFormat: Displaying A Date With Precise Control

If you want precise control of how your date looks, you can use a mask like this:

Zulu Time

Here is how to display today’s date in Zulu ISO-8601 format.

Local Time

Here is how to display local time, to the millisecond.

Parsing/Validating A Date

To convert a date from a String to internal format is quite a production. This technique will also validate a date. Just catch the ParseException.

• 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

Have a look at this example program to calculate how many hours until the next presidential inauguration.

• 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?

This sounds like a simple problem. Programmers posted many different solutions to the  comp.lang.java.programmer  newsgroup before the gurus stopped finding holes in the logic. Part of the problem is that the question can have many different legitimate answers.

Taking A Timestamp Apart

Building A Timestamp from the Pieces

// building a timestamp using default TimeZone.
GregorianCalendar stamp = new GregorianCalendar();
stamp.clear();
stamp.set( year, month-1, day, hour, minute, second );
long timestamp = 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 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 (Java Development Kit) 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 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. You must specify the Calendar twice, once indirectly as a Date.
• If the user has not configured his time zone 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 time zone instead.

Designing a Calendar

Designing calendars is an inherently messy problem.

• You are try to measure years, days, lunar cycles, each of which only approximates a constant unit of measure. There is no way to do it with a single scheme.
• You also need a measure that is not connect to astronomy, something as invariant as possible for doing things like measuring the wavelength of light emitted by various excited atoms.
• Tradition clings to calendars long after they have proved unworkable.
• Religious people and other zealots think they have the right to redefine calendars.
• Roman politicians meddled, stealing days from February to make July and August longer.
• Unix has defined a simple system of measure in milliseconds plus or minus 1970-01-01T00:00. It is effectively a day-counting system. It needs no months, weeks, years or other complicated structure. Perhaps over time it will supplant the other calendars. You can use simple addition and subtraction to do date calculation.

TimeZones

Here is a list of available time zones:

Standard : (DaylightSaving) : TimeZone

Here is a list of available TimeZones:

If, TZ, the above TimeZones Java Applet (that can also be run as an application) does not work…

1. If Copy/Paste (Ctrl-C/Ctrl-V) do not work, you can turn them back on by modifying your java.policy file. This is not for the novice or faint of heart. instructions Your alternative is to download this program and run it without a browser.
2. Often problems can be fixed simply by clicking the reload button on your browser.
3. Make sure you have both JavaScript and Java enabled in your browser.
4. This Java Applet (that can also be run as an application) needs 32-bit (not 64-bit) Java 1.6 or later. For best results use the older 1.7.0_17 not the latest buggy 1.7.0_21. In the Java Control Panel, configure medium security to allow vanilla unsigned applets to run.
5. You also need a recent browser.
6. It works under any operating system that supports Java e.g. W2K/XP/W2003/Vista/W2008/W7-32/W7-64/W8-32/W8-64/Linux/LinuxARM/LinuxX86/LinuxX64/Ubuntu/Solaris/SolarisSPARC/SolarisSPARC64/SolarisX86/SolarisX64/OSX
7. You should see the Applet hybrid above looking much like this screenshot. If you don’t, the following hints should help you get it working:
8. Especially if this Applet hybrid has worked before, try clearing the browser cache and rebooting.
9. 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.
10. If the above Applet hybrid does not work, check the Java console for error messages.
11. If the above Applet hybrid does not work, you might have better luck with the downloadable version available below.
12. 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.
13. If you are using Microsoft Internet Explorer 7, 8 or 9, try another browser. Seriously. Microsoft has taken great pains, over and over, to screw up Java and every other multi-platform standardisation.
14. If you are using Microsoft Internet Explorer 7, 8 or 9, you must click to 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.
15. If you are using Microsoft Internet Explorer 9, makes sure the Java Plug-In SSV helper add-in is installed and enabled. If it is not, try reinstalling the Java JRE.
16. If you have Windows 7 64-bit and Internet Explorer 64-bit, in theory you can use 64-bit Java, but I never been able to get it to work.
17. Try upgrading to a more recent version of your browser, or try a different browser e.g. Firefox, SeaMonkey, Safari or Avant.
18. If you still can’t get the program working click HELP for more detail.
19. If you can’t get the above Applet hybrid 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  

• 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 time zone. 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 time zone 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 time zone. 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
	by	Edward M. Reingold and Nachum Dershowitz	978-0-521-70238-6	paperback
	birth	1945 age: 67	978-0-521-88540-9	hardcover
	publisher	Cambridge University
	published	2007-12-10
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 anz abe books.co.uk amazon.cn amazon.co.uk abe books.de abe books.ca amazon.de amazon.ca amazon.es Chapters Indigo iberlibro.com abe books.com abe books.fr amazon.com amazon.fr Barnes & Noble abe books.it Google play amazon.it O’Reilly Safari junglee.com Powells Kobo Sony eBooks other stores
Greyed out stores probably do not have the item in stock. Try looking for it with a bookfinder.

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