On May 19, 2015, at 12:45 AM, Stuart Marks <stuart.ma...@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
