[icu-design] Fw: ICU API: createSystemTimeZone(C) / getSystemTimeZone(J)

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

I filed a new bug related to the proposal below - 8346 ICU 
createTimeZone/getTimezone should use zone ID "Etc/Unknown" as the final 
fallback

My proposal for ticket#8300 below is probably not too bad, but if we 
return "Etc/Unknown" as time zone ID in create/getTimeZone, it should be 
sufficient for users to understand that the specified ID was not 
recognized (unknown).

While looking into #8300, I was thinking if we can make TimeZone class 
immutable. Because of two setters (setID / setRawOffset), TimeZone class 
is currently mutable. I filed another bug - 8345 Make TimeZone Freezable. 
For most practical use case of system time zones, users would not change 
their ID/raw offset. So if we introduce a new TimeZone factory API, I 
thought we could return "frozen" instance. However, I found some 
difficulties to make TimeZone class freezable nicely.


Now, I want to keep #8300 on hold, until we find out how can make TimeZone 
object immutable. Instead, go ahead and fix #8346 (Etc/Unknown), which 
should at least satisfies the author of #8300. Do you have any objections?

Thanks,
Yoshito


----- Forwarded by Yoshito Umaoka/Westford/IBM on 02/15/2011 10:46 AM 
-----

From:   yos...@us...
To:     icu-design <icu...@li...>
Date:   02/11/2011 02:10 PM
Subject:        [icu-design] ICU API: createSystemTimeZone(C) / 
getSystemTimeZone(J)



This API proposal is corresponding to ICU ticket#8300 

The current implementation of TimeZone factory method in ICU - 
createTimeZone in C / getTimeZone in J - always returns an instance of 
TimeZone even when the input ID is bogus (in this case, UTC is returned). 
When UTC is returned as a fallback, it usually does not make sense. Some 
users really want to do their own error handling, rather than returning 
UTC. 

The new proposed APIs only support system time zone IDs, such as 
"America/Los_Angeles", "EST5EDT"... (Note: I'm not sure the term "system 
ID" is appropriate or not. This term is used in other places in our 
documentation for the type of IDs coming from the Olson tz database + 
ICU's own legacy IDs). When a custom time zone (syntax based zone ID - 
such as GMT+03:00) or unknown ID is specified, the method return error 
status (U_ILLEGAL_ARGUMENT_ERROR in ICU4C / throws 
IllegalArgumentException in ICU4J) 

ICU4C 

    /** 
     * Creates a <code>TimeZone</code> for the given system ID. 
     * This method does not support custom IDs such as "GMT-08:00". 
     * Unlike <code>createTimeZone</code>, this method returns NULL with 
     * error code <code>U_ILLEGAL_ARGUMENT_ERROR</code> when the specified 

     * ID is not a known system time zone ID. 
     * @param systemID the system ID for a <code>TimeZone</code>, such as 
"America/Los_Angeles". 
     * @param status Output param to filled in with a success or an error. 

     * @return the specified <code>TimeZone</code> or NULL when the given 
system ID 
     * is unknown. 
     * @draft ICU 4.8 
     */ 
    static TimeZone* U_EXPORT2 createSystemTimeZone(const UnicodeString& 
systemID, UErrorCode& status); 

ICU4J 

    /** 
     * Gets a <code>TimeZone</code> for the given system ID. 
     * This method does not support custom IDs such as "GMT-08:00". 
     * Unlike {@link #getTimeZone(String)}, this method throws {@link 
IllegalArgumentException} 
     * when the specified ID is not a known system time zone ID. 
     * @param systemID the system ID for a <code>TimeZone</code>, such as 
"America/Los_Angeles". 
     * @return the specified <code>TimeZone</code> 
     * @throw IllegalArgumentException if <code>systemID</code> is not a 
known system ID. 
     * 
     * @draft ICU 4.8 
     * @provisional This API might change or be removed in a future 
release. 
     */ 
    public static TimeZone getSytemTimeZone(String systemID) 


Note: 

- Another option is to return null for error case, rather than returning 
error status U_ILLEGAL_ARGUMENT_ERROR (C) / throwing 
IllegalArgumentException (J). 
- ICU4C error status might be used also for other purpose (malloc failure 
/ missing resource) 


ICU Trac Ticket: 8300
Designated API reviewer: Markus Scherer 

Please provide feedback by next Wednesday, 2011-02-16 

-Yoshito
------------------------------------------------------------------------------
The ultimate all-in-one performance toolkit: Intel(R) Parallel Studio XE:
Pinpoint memory and threading errors before they happen.
Find and fix more than 250 security defects in the development cycle.
Locate bottlenecks in serial and parallel code that limit performance.
http://p.sf.net/sfu/intel-dev2devfeb
_______________________________________________
icu-design mailing list
icu...@li...
To Un/Subscribe: https://lists.sourceforge.net/lists/listinfo/icu-design