[icu-design] ICU API proposal - TimeZone.observesDaylightTime

[<yos...@us...>]

I would like to propose the following API for: ICU 49
Please provide feedback by: Tuesday, 2011-12-22
Designated API reviewer: Michael Ow
Ticket: http://bugs.icu-project.org/trac/ticket/8998

Background:

There is a new method in TimeZone class  'public boolean 
observesDaylightTime()' in Java 7. Another method 'public boolean 
useDaylightTime()" in JDK is somewhat defective. When JDK introduced olson 
time zone in JDK 1.4.2, Sun added a note in the API reference document as 
below:

>If an underlying TimeZone implementation subclass supports
>historical Daylight Saving Time schedule changes, the method
>refers to the latest Daylight Saving Time schedule information. 

This definition resulted something what people would not expect.

In the tz database, the last rule is described by either single transition 
rule or a pair of max rule. If the last is described by a single 
transition rule and if it's standard time, useDaylightTime() always 
returns false. For example, Fiji in 2011n below:


# Rule  NAME    FROM    TO      TYPE    IN      ON      AT      SAVE 
LETTER/S
Rule    Fiji    1998    1999    -       Nov     Sun>=1  2:00    1:00    S
Rule    Fiji    1999    2000    -       Feb     lastSun 3:00    0       -
Rule    Fiji    2009    only    -       Nov     29      2:00    1:00    S
Rule    Fiji    2010    only    -       Mar     lastSun 3:00    0       -
Rule    Fiji    2010    only    -       Oct     24      2:00    1:00    S
Rule    Fiji    2011    only    -       Mar     Sun>=1  3:00    0       -
Rule    Fiji    2011    only    -       Oct     23      2:00    1:00    S
Rule    Fiji    2012    only    -       Jan     22      3:00    0       -
# Zone  NAME            GMTOFF  RULES   FORMAT  [UNTIL]
Zone    Pacific/Fiji    11:53:40 -      LMT     1915 Oct 26     # Suva
                        12:00   Fiji    FJ%sT   # Fiji Time

At this moment, Fiji observes daylight saving time. However, because the 
last rule is on Jan 22, 2011 to standard time, TimeZone.useDaylightTime() 
returns false. Although, this is probably not what people expect, Oracle 
decided not to change the behavior of useDaylightTime() because the 
behavior is already clearly documented. Instead, they added 
observesDaylightTime() with the definition below -

-----------------------------------
public boolean observesDaylightTime()

Returns true if this TimeZone is currently in Daylight Saving Time, or if 
a transition from Standard Time to Daylight Saving Time occurs at any 
future time.

The default implementation returns true if useDaylightTime() or 
inDaylightTime(new Date()) returns true.

Returns:
    true if this TimeZone is currently in Daylight Saving Time, or if a 
transition from Standard Time to Daylight Saving Time occurs at any future 
time; false otherwise.
-----------------------------------

With this functional specification, observesDaylightTime() will return 
true for Pacific/Fiji now.


Side note:

BTW, In my opinion, the description 'The default implementation returns 
true if useDaylightTime() or inDaylightTime(new Date()) returns true.' is 
confusing. I think this is talking about the default implementation in 
TimeZone class, not the default implementation of TimeZone returned by 
TimeZone.getTimeZone(String). For example, if a city schedule a daylight 
saving time only next year (the last rule is a transition to standard 
time), but currently not in daylight saving time;
 
- daylight saving time occurs at any future time,
- but neither useDaylightTime() nor inDaylightTime(new Date()) return 
true.



Proposed API:


 com.ibm.icu.util.TimeZone
-----------------------------------
public boolean observesDaylightTime()

Returns true if this TimeZone is currently in Daylight Saving Time, or if 
a transition from Standard Time to Daylight Saving Time occurs at any 
future time.

The default implementation in TimeZone class returns true if 
useDaylightTime() or inDaylightTime(new Date()) returns true.
-----------------------------------

The description is pretty much same with Java 7, but I would add "in 
TimeZone class" to avoid unnecessary confusion. Also, because this API is 
for JDK compatibility, API signature won't be changed - therefore, it's a 
born @stable API.



Question:

The goal of this API is allowing users to consume ICU4J as a drop-in JDK 
replacement. I'm not sure we really need this API in ICU4C because

- It seems this API was added in Java for fixing undesired 
useDaylightTime() behavior.
- ICU's useDaylightTime() checks if daylight saving time is observed in 
the current calendar year, which is different from JDK implementation. 
ICU's useDaylightTime always return true if daylight saving time is 
observed at that time.
- ICU already provide features allowing users to check future/past time 
transitions.



Thanks,
Yoshito