<i18n dev> TimeZone API for getting raw offset and daylight saving amount

Yoshito Umaoka y.umaoka at gmail.com
Tue Aug 12 14:59:18 PDT 2008

Hello all,

I'm experiencing a problem for setting my own TimeZone implementation as 
system default time zone.  After some investigation, I think this 
problem is caused by the lack of API in java.util.TimeZone.

When TimeZone was introduced in JDK 1.1, it did not support historical 
GMT offsets/daylight saving time rules.  So "raw" offset is always same 
at anytime.  When JDK 1.4 implemented historic rules, APIs were not much 

With TimeZone methods, you can get GMT offset at the specified time. 
You can also see if the specified time is in daylight saving time or 
not.  HOWEVER, you have no way to know "raw" GMT offset and daylight 
saving amount.  This is usually not a problem, because you can still get 
the GMT offset (raw + dstsaving).  The problem shows up when TimeZone is 
used by Calendar.

Calendar has two fields - ZONE_OFFSET and DST_OFFSET.  Calendar 
implementation obviously needs to get the raw GMT offset and the 
daylight saving amount for setting these fields.  However, there are no 
such APIs in TimeZone class.  Calendar implementation calls my TimeZone 
subclass's getRawOffset()/getDSTSavings() instead.

getRawOffset() and getDSTSavings() are somewhat broken when the historic 
rule support was introduced.  The raw GMT offset and the daylight saving 
amount could change time to time.  But these APIs do not take any 
arguments specifying date.

Calendar code calls another method supporting historic raw/dst amount 
changes when the implementation class of TimeZone is JDK's own private 
one.  I think such API should be added in TimeZone as a public API, so 
Java users can implement their own TimeZone subclasses which work well 
with Calendar.

In our project (ICU4J), we added an API below in our TimeZone class -

public void getOffset(long date, boolean local, int[] offsets)

This API returns the raw offset in offsets[0] and the daylight saving 
amount in offsets[1] at the specified time.  I do not think the second 
argument (specifying whether 'date' is local wall time or GMT) is 
necessary.  I think JDK TimeZone also needs such method to resolve 
Calendar field calculation problem above.  The default implementation 
would be -

public void getOffset(long date, int[] offsets) {
     if (offsets == null || offsets.length < 2) {
         offsets = new int[2];
     if (inDaylightTime(new Date(date)) {
         offsets[1] = getDSTSavings();
         offsets[0] = getOffset(date) - offsets[1];
     } else {
         offsets[0] = getOffset(date);
         offsets[1] = 0;

I propose to add this method in java.util.TimeZone and use it in JDK 
Calendar implementation.  Any opinions?

Yoshito Umaoka (ICU Project)

More information about the i18n-dev mailing list