RFR: 8024704: Improve API documentation of ClassLoader and ServiceLoader with respect to enumeration of resources.

[Daniel Fuchs]

Hi,

Thank you all for the nice & valuable feedback!

I have updated the webrev with Alan's correction.

The ClassLoader api note now reads:

"When overriding this method it is recommended that an
  implementation ensures that ... "

(and also fixed indentation)

<http://cr.openjdk.java.net/~dfuchs/webrev_8024704/webrev.01/>

-- daniel

On 10/8/13 10:06 PM, Alan Bateman wrote:
> On 08/10/2013 18:19, Daniel Fuchs wrote:
>> Hi,
>>
>> Please find below a fix for:
>>
>> 8024704: Improve API documentation of ClassLoader and ServiceLoader
>>          with respect to enumeration of resources.
>> <https://bugs.openjdk.java.net/browse/JDK-8024704>
>>
>> This is a clarification of the implementation of the
>> ServiceLoader.iterator() method, as well as non normative advice
>> for ClassLoader subclasses overriding getResource() or getResources()
>> to consider overriding the other method in order to keep them
>> consistent with each other.
>>
>> <http://cr.openjdk.java.net/~dfuchs/webrev_8024704/webrev.00/>
> As background to others, the motive for this one stems from a small
> compatibility issue that arose with the JAXP changes to use
> ServiceLoader (it was previous foraging for service configuration files
> itself). The compatibility issue arises with ClassLoader implementations
> where getResource and getResources are inconsistent, and in the JAXP
> case uncovered a server that located an unexpected XML parser.
>
> Daniel - in the @apiNote on getResource it reads "the implementations
> ensure" where it should be "the implementation ensures" or
> "implementations should ensure". Otherwise the wording looks okay to me.
> Conventions haven't been established yet but I would think that @apiNote
> is a case where you can use the full
> line.
>
> -Alan.