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

[Stuart Marks]

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