[loc-en-dev] Revised Locale API proposal

[Doug Felt]

Looks good to me.  I can edit the text for readability in some places,
but there's nothing significant.  I suggest not documenting
NullPointerExceptions, but instead only documenting places where null
is _accepted_ as a value, since you have to document what it means
anyway, and this is in general rarer.

Other comments::
- Do we want LocaleNameProvider to be able to return a display name
for a full locale?  It seems eventually data could provide more
natural display names.

- The Builder idiom (from Josh Bloch) uses 'build' instead of 'create'
as the name for the method that returns the product of the builder.
We should probably follow this.

Doug

On Tue, Sep 8, 2009 at 10:51 AM, Mark Davis ⌛<mark at macchiato.com> wrote:
> General: We should not be directly referencing ISO standards, because they
> are unstable. We can often reference BCP 47 and the iana registry, but it is
> more accurate to reference Unicode Locale Identifiers (LDML).
>
> Examples:
>
> ===
>
> getISOCountries
>
> public static java.lang.String[] getISOCountries()
>
> Returns a list of all 2-letter country codes defined in ISO 3166. Can be
> used to create Locales.
> Should be: returns all region codes in the iana registry, including both 2
> letter ISO codes (current and deprecated) and 3 digit UN M.49 codes. (Either
> that or we need to add a "real" method to get all the valid ones.)
>
> getISOLanguages
>
> public static java.lang.String[] getISOLanguages()
>
> Returns a list of all 2-letter language codes defined in ISO 639. Can be
> used to create Locales. [NOTE: ISO 639 is not a stable standard-- some
> languages' codes have changed. The list this function returns includes both
> the new and the old codes for the languages whose codes have changed.]
>
> Should be: returns a list of all primary language codes defined in the iana
> registry (includes 2 and 3 letter ISO 639 codes). (Either that or we need to
> add a "real" method to get all the valid ones.)
>
> getVariant
>
> public java.lang.String getVariant()
>
> Returns the variant code for this locale, which should either be the empty
> string or a conforming BCP47 variant string.
> What about variants like "rozaj_biske"? [see
> http://www.iana.org/assignments/language-subtag-registry] Does this method
> return only the first subtag, or all? [My preference would be all, in
> alphabetical order.] Similar issue for LocaleBuilder.setVariant
>
>
> Mark
>
>
> On Tue, Sep 8, 2009 at 10:07, Yoshito Umaoka <y.umaoka at gmail.com> wrote:
>>
>> Hi all,
>>
>> I reviewed the proposed API docs and updated followings -
>>
>> 1. Locale class description: Reorganized and provided more comprehensive
>> explanation for logical locale fields.
>> 2. Variant: Removed syntactical restrictions on variant, provided some
>> note about BCP47 compatibility.
>> 3. Mics changes: Consistent terminology, removed "New API", etc...
>>
>> I'm attaching a zip file in this message.  Please take a look if this
>> version is good enough for submitting a proposal to OpenJDK.
>>
>> I'll add some explanation about the updated behavior for candidate list in
>> ResourceBundle.Control and LocaleServiceProvider, but these are behavior
>> changes, not adding/changing APIs.
>>
>> -Yoshito
>
>