[loc-en-dev] Removing Locale#getPrivateUse / Builder#setPrivateUse from the proposed APIs

[Yoshito Umaoka]

Hi folks,

Doug and I had a long discussion last week.  As the result, we agreed to 
remove these methods and make private use as a part of "extensions" and 
use Locale#getExtension('x') to access the value / 
Builder#setExtension('x', privateuseVal) to set the value.

The original question was whether Locale#getPrivateUse should return 
null or empty string.  I'm attaching the note below -

> Doug Felt wrote:
>> It doesn't matter what the implementation does internally, it matters 
>> what the user sees.  I still believe it makes sense to return empty 
>> string for the 'base locale' fields and null for everything else.  
>> Either that, or return the empty string / empty set everywhere 
>> instead of null.
>> I don't find the putative distinction between private use and 
>> extensions persuasive.  I don't think users will find this 
>> distinction as clear as you do.
>>
>> Doug
>>
>> On Thu, Mar 5, 2009 at 8:10 PM, Yoshito Umaoka <y.umaoka at gmail.com 
>> <mailto:y.umaoka at gmail.com>> wrote:
>>
>>     Hi Doug,
>>
>>     Last time we discussed about this, I agreed to change it to return
>>     null instead of the empty string.  Now I feel it's not what I
>>     want, because we changed the semantics of null argument in
>>     Builder#setXXX.  You pointed out that the behavior is consistent
>>     with getExtension.  But it differs from private use, because
>>     getExtension is paired with getExtensionKeys.  Like what I'm doing
>>     in the implementation code with Builder, when you set entire
>>     contents of a given intput locale, I call setXXX(loc.getXXX()) for
>>     all fields other than extensions.  For extensions, I call
>>     getExtensionKeys first to see if any extensions are available (I'm
>>     doing null check here), then call getExtension for each key (in
>>     this case, I do not need to check null, because it's always
>>     there..).  So, obviously, I do different operation for extensions
>>     only.
>>
>>     -Yoshito
>>
>>
> OK.  I see there are two interpretations.
>
> 1. BCP47 extensions are technically unordered map.  It also defines 
> canonical representation, but it does not disallow extension 'b' comes 
> before extension 'a'.  On the other hand, private use must be always 
> the last subtags and slightly relaxed syntactical requirement.  When 
> you directly map the design concept to Locale class, extensions and 
> private use are separated.
>
> 2. The java.util.Locale extensions are simply providing optional 
> fields.  Each field has its name and value.  Private use is a special 
> type of field, which is not reserved by anyone.  In this case, 
> information stored in LocaleExtension in the current implementation 
> are single plain map.
>
>
> My current design proposal is based on the 1st interpretation.  I 
> wanted to match the BCP47 language tag structure in java.util.Locale.  
> I thought it is better for Java user to understand what these new 
> items are trying to achieve.
>
> Your comments seems to base on the 2nd interpretation.  If we design 
> like this way, we do not need Locale#getPrivateUse.  Instead, we 
> probably want to define - public static final char PRIVATEUSE = 'x' 
> and Locale#getExtensions(PRIVATEUSE) to access the BCP47 private use 
> corresponding.
>
> Mark also questioned what Locale#getPrivateUse for.  I'm start feeling 
> the distinction between BCP47 extensions and privateuse in Locale 
> method.  Having the independent method just helps some users who 
> understand BCP47 structure to get the better insight.  But at the same 
> time, for those 'advanced' users, they should be able to understand 
> why it is handled as an extension in Locale (as the 2nd interpretation).
>
> So, here is what I want to do.  I'll remove Locale#getPrivateUse() / 
> Builder#setPrivateUse(String).  Instead, I'll add 'public static final 
> char PRIVATEUSE = 'x'; ' in Locale and use 
> getExtension/Builder#setExtension to get/set the field.  Do you have 
> any objections to this approach?
>
> Thanks,
> Yoshito

I've already updated the locale copy of Locale.java and other classes 
and will update the proposed API doc on Monday.  If you have any 
objections, please post your response.

Thanks,
Yoshito