[loc-en-dev] [Fwd: Updated JavaDoc]

[Yoshito Umaoka]

Fowarding the message from Mark Davis below -
-------------------------

Because a |Locale| object is just an identifier for a region, no 
validity check is performed when you construct a |Locale|.

Add text indicating that it is strongly recommended that only valid 
Unicode locale idenfiers be used in constructing locales.



|static java.lang.String[]| 	|*getISOCountries 
<http://sites.google.com/site/java/util/Locale.html#getISOCountries%28%29>*()| 

          Returns a list of all 2-letter country codes defined in ISO 3166.
|static java.lang.String[]| 	|*getISOLanguages 
<http://sites.google.com/site/java/util/Locale.html#getISOLanguages%28%29>*()| 

          Returns a list of all 2-letter language codes defined in ISO 639.


Deprecate these. Note in the text that while the original purpose of 
these was to supply the components used in forming Locales, the standard 
definition has moved beyond them.

Ideally, we would add also:
getBCP47BaseLanguages
getBCP47Scripts
getBCP47Regions
getBCP47Variants
but the OpenJDK group may not buy off on that. We could discuss it, however.


      SIMPLIFIED_CHINESE

public static final Locale <http://sites.google.com/site/java/util/Locale.html> *SIMPLIFIED_CHINESE*

    Useful constant for language. 

------------------------------------------------------------------------


      TRADITIONAL_CHINESE

public static final Locale <http://sites.google.com/site/java/util/Locale.html> *TRADITIONAL_CHINESE*

Useful constant for language.

Add notes that more properly speaking, these should be zh_Hans and 
zh_Hant. However, for backwards compatibility these can continue to be 
used. (I assume that the locale lookup is being changed to make these 
essentially equal in lookup.)

Update the language in various places, eg:

Returns the language code for this locale, which will either be the 
empty string or a lowercase ISO 639 code.
=> Returns the language code for this locale, which should either be the 
empty string or a Unicode region identifier code.

[Note, that language was always in conflict with the class description, 
which had no absolute requirements on the code.]


      getPrivateUse

public java.lang.String *getPrivateUse*()

    New API Returns the private use code for this locale. 
I don't understand this.

New API Returns a locale for the specified language tag string. If the 
specified language tag contains any invalid subtags, the first invalid 
subtag and all following subtags are ignored.

Ignoring is dangerous... If it is ill-formed, it should raise an exception.

More later.


Mark


On Tue, Mar 3, 2009 at 10:47, Yoshito Umaoka <y.umaoka at gmail.com 
<mailto:y.umaoka at gmail.com>> wrote:

    Hi Mark,

    If you have chance, please take a quick look for the proposed API
    changes in the links below.  Doug and I are trying to refine the
    details and provide better API documentation, but we do not expect
    any major changes from here.  (We are considering to add several
    APIs - boolean Locale#isEquivalentTo(Locale),
    LocaleBuilder#removeExtensions...)  If you have any comments, please
    post your comments directly to
    locale-enhancement-dev at openjdk.java.net
    <mailto:locale-enhancement-dev at openjdk.java.net>.

    Thanks,
    Yoshito

    -------- Original Message --------
    Subject: Updated JavaDoc
    Date: Fri, 27 Feb 2009 11:59:08 -0500
    From: Yoshito Umaoka <y.umaoka at gmail.com <mailto:y.umaoka at gmail.com>>
    To: locale-enhancement-dev at openjdk.java.net
    <mailto:locale-enhancement-dev at openjdk.java.net>

    http://sites.google.com/site/openjdklocale/apis

    I updated the JavaDoc based on things found during the implementation
    and some inputs from Doug.

    - Locale.LocaleExtension / Locale.LocaleKeywords are gone.
    - Setters in LocaleBuilder no longer throw an exception for a malformed
    input.
    - LocaleBuilder#create() - ignore malformed fields.
    - LocaleBuilder#createStrict() - return null when any malformed fields
    are found.

    -Yoshito



-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.openjdk.java.net/pipermail/locale-enhancement-dev/attachments/20090303/adff6555/attachment.html