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.)
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. :-)
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.
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/
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
A good stream-ification task would be to identify cases in the JDK where only
an Enumeration is returned and additionally provide stream-returning methods,
so perhaps PermissionCollection and ClassLoader are good candidates.
Paul.
On May 16, 2015, at 2:37 AM, Stuart Marks <stuart.ma...@oracle.com> wrote:
Hi all,
Please review this small API enhancement to add a default method "asIterator()"
to Enumeration that converts it into an Iterator.
Webrev:
http://cr.openjdk.java.net/~smarks/reviews/8072726/webrev.0/
Bug:
https://bugs.openjdk.java.net/browse/JDK-8072726
Thanks,
s'marks
