RFR(s): 8072726: add adapter to convert Enumeration to Iterator

[Paul Sandoz]

On May 19, 2015, at 12:45 AM, Stuart Marks <stuart.marks at oracle.com> wrote:
> On 5/18/15 3:20 AM, Paul Sandoz wrote:
>> I would like to suggest some tweaks to the specification to get across this method is transitioning control of traversal from enumeration to iterator. How about:
>> 
>>   Returns an iterator that traverses the remaining elements covered by this enumeration.
>>   Traversal is undefined if this enumeration is operated on after the call to {@code asIterator}.
> 
> OK, good. I tweaked it somewhat to say "if any method is called" instead of "operated on" to make it absolutely clear that the underlying Enumeration shouldn't be touched after the call to asIterator(). (Yes, that includes hasMoreElements.)
> 

Ok. FWIW "operated on" is a term we have used in Stream and Spliterator.

e.g.:

* <p>Traversal of elements should be accomplished through the spliterator.
* The behaviour of splitting and traversal is undefined if the iterator is
* operated on after the spliterator is returned.


>> I suspect the use of PermissionCollection in the apiNote is a little too obscure and highlighting an area that i don't think deserves so much attention :-)
> 
> Boy people really hate the java.security APIs. But perhaps not as much as they hate CORBA. :-)
> 

I suppose i have to tolerate both :-) each nowadays is not on the radar of most developers.


>> In your example i am not sure the source is IMMUTABLE, it's possible to add permissions if the collection is not marked read-only. It's not even clear whether ORDERED is relevant here, some implementations are backed by a HashMap (see BasicPermissionCollection) and the enumeration is derived from the map's values. Hence I am ambivalent about exposing such a Stream example, it exposes too many details that are tricky to get right.
>> 
>> ClassLoader.getResources would be better if it were not for IOException.
>> 
>> I would be inclined to go for Zip/JarFile.entries, and that would also give us the opportunity to highlight the stream returning method that could be used instead, therefore we can avoid mentioning about constructing a stream from an enumeration/iterator and move developers away from Enumeration altogether in this case.
> 
> OK, I went with JarFile, since the wildcard in ZipFile.entries() seems to cause some trouble.
> 

Ok.

I am still rooting for a mention of the Stream returning methods in JarFile but i won't push it, up to you and no need for another review in that case.


> I also deleted the stream example. It's fairly complex and as you note it's hard to get the details right.
> 
> I've posted an updated webrev here:
> 
> 	http://cr.openjdk.java.net/~smarks/reviews/8072726/webrev.1/
> 

+1

Paul.

> Changes include:
> 
> - updates to spec & examples per above
> - converted NOTE in class doc to @apiNote
> - Rémi's suggested simplifications
> - additional tests for remove()
> 
> s'marks