RFR: JDK-8134373: explore potential uses of convenience factories within the JDK

[Stuart Marks]

Hi Naoto,

Great, thanks for confirming this.

s'marks

On 10/11/16 4:13 PM, Naoto Sato wrote:
> +1 for removing the link to Collections#unmodifiableList in the spec. I don't
> see any particular reason to specify in the javadoc and don't believe it would
> break any existing apps.
>
> Naoto
>
> On 10/11/16 4:03 PM, Stuart Marks wrote:
>>
>>
>> On 10/10/16 11:26 PM, Andrej Golovnin wrote:
>>> src/java.base/share/classes/java/util/ResourceBundle.java
>>>
>>> 2490     public static class Control {
>>> 2491         /**
>>> 2492          * The default format <code>List</code>, which contains
>>> the strings
>>> 2493          * <code>"java.class"</code> and
>>> <code>"java.properties"</code>, in
>>> 2494          * this order. This <code>List</code> is {@linkplain
>>> 2495          * Collections#unmodifiableList(List) unmodifiable}.
>>> 2496          *
>>> 2497          * @see #getFormats(String)
>>> 2498          */
>>> 2499         public static final List<String> FORMAT_DEFAULT =
>>> List.of("java.class", "java.properties");
>>>
>>> I think you should also change the JavaDocs in the
>>> ResourceBundle.Control class for the constants FORMAT_CLASS,
>>> FORMAT_DEFAULT and FORMAT_PROPERTIES, because the JavaDocs for this
>>> constants explicitly mentions, that the lists are created by using
>>> Collections#unmodifiableList(List). Or you cannot change this
>>> constants at all because they are part of the Public API and existed
>>> in this form for a long time. Please ask someone from Oracle for help.
>>> They can explain it better when it is OK to change and when not. Maybe
>>> Stuart can do that.
>>
>> Hi Andrej,
>>
>> Thanks for pointing this out.
>>
>> It appears that the changes to remove the links to
>> Collections.unmodifiableList() was dropped from webrev.01 to webrev.02.
>> I've restored them, along with a couple other changes that were also
>> dropped. I also updated the ModuleFinder.java comment per a request from
>> Alan Bateman. The revised webrev is here:
>>
>> http://cr.openjdk.java.net/~smarks/reviews/8134373/webrev.03/
>>
>> In any case, yes, the specifications of the ResourceBundle.Control
>> fields should be changed to remove the links to
>> Collections.unmodifiableList(). It's unclear whether having a link this
>> way implies that it's part of the specification that these fields must
>> be instances returned from that method. Removing the link makes it clear
>> that saying the List is unmodifiable is merely a description of the
>> required behavior.
>>
>> I spoke with Joe Darcy (our compatibility guru) and we agreed that out
>> of an abundance of caution it would be wise to file a request to make
>> this change. (This is the "CCC" - basically an internal change control
>> process for Java SE specifications.) Doing this is mainly for tracking
>> purposes, as we believe this to be a compatible change.
>>
>> I've also included in this request a mention of the change to
>> CookieManager.get() which we had discussed previously. Even though we
>> believe this is also a compatible change, it's also a change that should
>> be tracked.
>>
>> I'll follow up when this bit of process is finished.
>>
>> s'marks