stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

8072726: add adapter to convert Enumeration to Iterator

Browse Source 
Reviewed-by: redestad, forax, chegar, dfuchs, psandoz, rriggs, briangoetz
This commit is contained in:
Stuart Marks 2015-06-04 18:28:14 -07:00
parent 31fe486b50
commit bc90fc9b01
3 changed files with 280 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

60
jdk/src/java.base/share/classes/java/util/Enumeration.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 1994, 2005, Oracle and/or its affiliates. All rights reserved.
* 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
@ -40,11 +40,14 @@ package java.util;
* 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.
*
* @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
@ -76,4 +79,49 @@ public interface Enumeration<E> {
* @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}
* instances. For example, the {@link java.util.jar.JarFile#entries
* JarFile.entries()} method returns an {@code Enumeration<JarEntry>}.
* This can be turned into an {@code Iterator}, and then the
* {@code forEachRemaining()} method can be used:
*
* <pre>{@code
* JarFile jarFile = ... ;
* jarFile.entries().asIterator().forEachRemaining(entry -> { ... });
* }</pre>
*
* (Note that there is also a {@link java.util.jar.JarFile#stream
* JarFile.stream()} method that returns a {@code Stream} of entries,
* which may be more convenient in some cases.)
*
* @implSpec
* The default implementation returns an {@code Iterator} whose
* {@link Iterator#hasNext hasNext} method calls this Enumeration's
* {@code hasMoreElements} method, whose {@link Iterator#next next}
* method calls this Enumeration's {@code nextElement} method, and
* whose {@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();
}
};
}
}

6
jdk/src/java.base/share/classes/java/util/Iterator.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1997, 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
@ -43,6 +43,10 @@ import java.util.function.Consumer;
* <a href="{@docRoot}/../technotes/guides/collections/index.html">
* Java Collections Framework</a>.
*
* @apiNote
* An {@link Enumeration} can be converted into an {@code Iterator} by
* using the {@link Enumeration#asIterator} method.
*
* @param <E> the type of elements returned by this iterator
*
* @author Josh Bloch

221
jdk/test/java/util/Collections/EnumerationAsIterator.java Normal file
View File

@ -0,0 +1,221 @@
/*
* Copyright (c) 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.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
/**
* @test
* @bug 8072726
* @summary Tests for Enumeration-to-Iterator conversion.
* @run testng EnumerationAsIterator
*/
import org.testng.annotations.DataProvider;
import org.testng.annotations.Test;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collection;
import java.util.Collections;
import java.util.Enumeration;
import java.util.Iterator;
import java.util.List;
import java.util.NoSuchElementException;
import java.util.concurrent.atomic.AtomicInteger;
import java.util.function.Supplier;
import static org.testng.Assert.*;
@Test
public class EnumerationAsIterator {
static Object[] of(String description, Supplier<Enumeration<?>> s, Collection<?> exp) {
return new Object[]{description, s, exp};
}
static Object[] of(String description, Collection<?> c, Collection<?> exp) {
return of(description, () -> Collections.enumeration(c), exp);
}
/**
* A wrapper Enumeration that doesn't override the
* default method on Enumeration.
*/
static <T> Enumeration<T> wrapInDefault(Enumeration<T> e) {
return new Enumeration<>() {
@Override
public boolean hasMoreElements() {
return e.hasMoreElements();
}
@Override
public T nextElement() {
return e.nextElement();
}
};
}
@DataProvider
public static Iterator<Object[]> unmodifiable() {
return Arrays.asList(
of("Default-wrapped ArrayList",
() -> wrapInDefault(
Collections.enumeration(new ArrayList<>(Arrays.asList("a")))),
Arrays.asList("a")),
of("Unmodifiable ArrayList",
Collections.unmodifiableList(new ArrayList<>(Arrays.asList("a"))),
Arrays.asList("a")),
of("Modifiable ArrayList",
new ArrayList<>(Arrays.asList("a")),
Arrays.asList("a"))
).iterator();
}
@DataProvider
public static Iterator<Object[]> others() {
return Arrays.asList(
of("Default Collections.emptyEnumeration()",
() -> wrapInDefault(Collections.emptyEnumeration()),
Collections.emptyList()),
of("Collections.emptyEnumeration()",
Collections::emptyEnumeration,
Collections.emptyList()),
of("Collections.emptyList()",
Collections.emptyList(),
Collections.emptyList()),
of("Collections.singletonList()",
Collections.singletonList("a"),
Collections.singletonList("a")),
of("Arrays.asList(...)",
Arrays.asList("a", "b", "c"),
Arrays.asList("a", "b", "c"))
).iterator();
}
@DataProvider
public static Iterator<Object[]> all() {
List<Object[]> all = new ArrayList<>();
unmodifiable().forEachRemaining(all::add);
others().forEachRemaining(all::add);
return all.iterator();
}
@Test(dataProvider = "all")
public void consumeByNext(String description, Supplier<Enumeration<?>> s, Collection<?> exp) {
Iterator<?> i = s.get().asIterator();
int count = 0;
while (i.hasNext()) {
assertTrue(i.hasNext());
i.next();
count++;
}
assertEquals(count, exp.size());
assertFalse(i.hasNext());
try {
i.next();
fail();
} catch (NoSuchElementException e) {
}
}
@Test(dataProvider = "all")
public void consumeByForEachRemaining(String description,
Supplier<Enumeration<?>> s,
Collection<?> exp) {
Iterator<?> i = s.get().asIterator();
AtomicInteger ai = new AtomicInteger();
i.forEachRemaining(e -> ai.getAndIncrement());
assertEquals(ai.get(), exp.size());
i.forEachRemaining(e -> ai.getAndIncrement());
assertEquals(ai.get(), exp.size());
assertFalse(i.hasNext());
try {
i.next();
fail();
} catch (NoSuchElementException e) {
}
}
@Test(dataProvider = "all")
public void consumeByNextThenForEachRemaining(String description,
Supplier<Enumeration<?>> s,
Collection<?> exp) {
Iterator<?> i = s.get().asIterator();
AtomicInteger ai = new AtomicInteger();
if (i.hasNext()) {
i.next();
ai.getAndIncrement();
}
i.forEachRemaining(e -> ai.getAndIncrement());
assertEquals(ai.get(), exp.size());
i.forEachRemaining(e -> ai.getAndIncrement());
assertEquals(ai.get(), exp.size());
assertFalse(i.hasNext());
try {
i.next();
fail();
} catch (NoSuchElementException e) {
}
}
@Test(dataProvider = "all")
public void contents(String description, Supplier<Enumeration<?>> s, Collection<?> exp) {
assertEquals(copy(s.get()), exp);
}
private List<?> copy(Enumeration<?> input) {
List<Object> output = new ArrayList<>();
input.asIterator().forEachRemaining(output::add);
return output;
}
@Test(dataProvider = "unmodifiable",
expectedExceptions=UnsupportedOperationException.class)
public void removeThrowsAfterAdvancingE(String description,
Supplier<Enumeration<?>> s,
Collection<?> exp) {
Enumeration<?> e = s.get();
e.nextElement();
e.asIterator().remove();
}
@Test(dataProvider = "unmodifiable",
expectedExceptions=UnsupportedOperationException.class)
public void removeThrowsAfterAdvancingI(String description,
Supplier<Enumeration<?>> s,
Collection<?> exp) {
Iterator<?> i = s.get().asIterator();
i.next();
i.remove();
}
}