This article delves into the deceptively simple method System.currentTimeMillis(). It tries to provide some insight into the meaning of the value it returns. In so doing it explains what is meant by the "current time" in Java. It also examines this concept in relation to the timezone and daylight savings configuration of the computer on which it is produced.

The javadoc for the method System.currentTimeMillis() explains the concept exactly; it says that the value is:

"the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC".

The diagram above represents two time synchronized computers in two different timezones whose "wall" clocks show different times. At the represented moment in time, computer A in America (Atlantic Standard Time) shows 5:00 o'clock in the morning and computer B in Australia (Western Standard Time) shows 4:00 o'clock in the afternoon.

If we were to call System.currentTimeMillis() on both of these computers in the same instant then the values returned from both calls would be theoretically equal to each other. This is shown in the diagram, where the value for System.currentTimeMillis() is the same for both computers

What actually happens is that each of the computers independently calculates what the current date and time is in UTC and then uses the derived value to determine the number of milliseconds which have elapsed since the epoch. Theoretically there is only ever one correct UTC time so they should both arrive at the same answer.

The calculation uses the system clock, the timezone and daylight savings configurations as inputs as well as no doubt taking into account some platform specific factors. Implementations are native so they will definitely vary across platforms and JVMs.

The mistake I used to make, and a mistake I think a lot of people make, is to assume that the System.currentTimeMillis value is provided in terms of the timezone that the computer is in (i.e. wall clock time), rather than in UTC. If this was the case, the value returned by computer B in Australia would be larger than the one returned by computer A in America. This misunderstanding is very damaging as it affects the way one understands the java.util.Date and java.util.Calendar classes too.

If you think about it, the way it actually works makes a lot of sense. It means that we can directly compare the time in milliseconds from two computers regardless of their timezones.

The following table presents the contrived data with the computers in America and Australia in more detail. It also adds some data for a computer in Greenwich in London. The last column indicates whether or not the "Automatically adjust clock for daylight savings changes" option has been set to on or off (This option is available on Windows).

As you can see in the table above that no matter what the settings for timezone and daylight savings adjustment, the System.currentTimeMillis() will always return the same value.

Bookmark

Email this

Comments (1)

Show/hide comments

Thank you for clarifying this.

Been developing Java for more than a decade and it NEVER dawned on me until today that I had no idea what the value from currentTimeMillis actually meant with regard to comparisons across timezones.

Digging around on the web I found a lot of people throwing around suggestions, but not a clear and concise answer.

your writeup was brilliant. Very straight forward and instead of making an equally vague claim and then running off (which I saw a lot in other forums), you sat down and explained, with examples, what is going on.

Really really appreciate you doing that; you saved me from some mild insanity.

Riyad Kalla , April 28, 2011

• 
• +3
• 
• 

Write comment

Show/hide comment form

Name

Email

Website

Title

Comment

smaller | bigger

I have read and agree to the Terms of Usage.

Add Comment Preview