< prev index next >
src/java.base/share/classes/java/util/Enumeration.java
Print this page
rev 11962 : 8072726: add adapter to convert Enumeration to Iterator
Reviewed-by: redestad, forax, chegar, dfuchs, psandoz
*** 1,7 ****
/*
! * Copyright (c) 1994, 2005, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
--- 1,7 ----
/*
! * Copyright (c) 1994, 2015, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
*** 38,52 ****
* <p>
* Methods are provided to enumerate through the elements of a
* vector, the keys of a hashtable, and the values in a hashtable.
* Enumerations are also used to specify the input streams to a
* <code>SequenceInputStream</code>.
! * <p>
! * NOTE: The functionality of this interface is duplicated by the Iterator
! * interface. In addition, Iterator adds an optional remove operation, and
! * has shorter method names. New implementations should consider using
! * Iterator in preference to Enumeration.
*
* @see java.util.Iterator
* @see java.io.SequenceInputStream
* @see java.util.Enumeration#nextElement()
* @see java.util.Hashtable
--- 38,55 ----
* <p>
* Methods are provided to enumerate through the elements of a
* vector, the keys of a hashtable, and the values in a hashtable.
* Enumerations are also used to specify the input streams to a
* <code>SequenceInputStream</code>.
! *
! * @apiNote
! * The functionality of this interface is duplicated by the {@link Iterator}
! * interface. In addition, {@code Iterator} adds an optional remove operation,
! * and has shorter method names. New implementations should consider using
! * {@code Iterator} in preference to {@code Enumeration}. It is possible to
! * adapt an {@code Enumeration} to an {@code Iterator} by using the
! * {@link #asIterator} method.
*
* @see java.util.Iterator
* @see java.io.SequenceInputStream
* @see java.util.Enumeration#nextElement()
* @see java.util.Hashtable
*** 74,79 ****
--- 77,129 ----
*
* @return the next element of this enumeration.
* @exception NoSuchElementException if no more elements exist.
*/
E nextElement();
+
+ /**
+ * Returns an {@link Iterator} that traverses the remaining elements
+ * covered by this enumeration. Traversal is undefined if any methods
+ * are called on this enumeration after the call to {@code asIterator}.
+ *
+ * @apiNote
+ * This method is intended to help adapt code that produces
+ * {@code Enumeration} instances to code that consumes {@code Iterator}
+ * or {@code Iterable} instances. For example, the
+ * {@link java.util.jar.JarFile#entries JarFile.entries()}
+ * method returns an {@code Enumeration<JarEntry>}. This can be adapted
+ * for use in an enhanced-for loop as follows:
+ *
+ * <pre>{@code
+ * JarFile jf = ... ;
+ * Iterable<JarEntry> entries = () -> jf.entries().asIterator();
+ * for (JarEntry je : entries) {
+ * doSomethingWithEntry(je);
+ * }
+ * }</pre>
+ *
+ * Note that the lambda expression being used as an {@code Iterable}
+ * fetches a new {@code Enumeration} each time, so that the resulting
+ * {@code Iterator} instances do not interfere with each other.
+ *
+ * @implSpec
+ * The returned Iterator's {@link Iterator#hasNext hasNext} method calls and returns
+ * the value from this Enumeration's {@code hasMoreElements} method; its
+ * {@link Iterator#next next} method calls and returns the value from this Enumeration's
+ * {@code nextElement} method; and its {@link Iterator#remove remove} method throws
+ * {@code UnsupportedOperationException}.
+ *
+ * @return an Iterator representing the remaining elements of this Enumeration
+ *
+ * @since 1.9
+ */
+ default Iterator<E> asIterator() {
+ return new Iterator<>() {
+ @Override public boolean hasNext() {
+ return hasMoreElements();
+ }
+ @Override public E next() {
+ return nextElement();
+ }
+ };
+ }
}
< prev index next >