1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 package org.apache.commons.io.function; 19 20 import java.io.IOException; 21 import java.io.UncheckedIOException; 22 import java.util.Iterator; 23 import java.util.NoSuchElementException; 24 import java.util.Objects; 25 import java.util.function.Consumer; 26 27 /** 28 * Like {@link Iterator} but throws {@link IOException}. 29 * 30 * @param <E> the type of elements returned by this iterator. 31 * @since 2.12.0 32 */ 33 public interface IOIterator<E> { 34 35 /** 36 * Adapts the given Iterator as an IOIterator. 37 * 38 * @param <E> the type of the stream elements. 39 * @param iterator The iterator to adapt 40 * @return A new IOIterator 41 */ adapt(final Iterator<E> iterator)42 static <E> IOIterator<E> adapt(final Iterator<E> iterator) { 43 return IOIteratorAdapter.adapt(iterator); 44 } 45 46 /** 47 * Creates an {@link Iterator} for this instance that throws {@link UncheckedIOException} instead of 48 * {@link IOException}. 49 * 50 * @return an {@link UncheckedIOException} {@link Iterator}. 51 */ asIterator()52 default Iterator<E> asIterator() { 53 return new UncheckedIOIterator<>(this); 54 } 55 56 /** 57 * Like {@link Iterator#forEachRemaining(Consumer)}. 58 * 59 * @param action See delegate. 60 * @throws IOException if an I/O error occurs. 61 */ forEachRemaining(final IOConsumer<? super E> action)62 default void forEachRemaining(final IOConsumer<? super E> action) throws IOException { 63 Objects.requireNonNull(action); 64 while (hasNext()) { 65 action.accept(next()); 66 } 67 } 68 69 /** 70 * Like {@link Iterator#hasNext()}. 71 * 72 * @return See delegate. 73 * @throws IOException if an I/O error occurs. 74 */ hasNext()75 boolean hasNext() throws IOException; 76 77 /** 78 * Like {@link Iterator#next()}. 79 * 80 * @return See delegate. 81 * @throws IOException if an I/O error occurs. 82 * @throws NoSuchElementException if the iteration has no more elements 83 */ next()84 E next() throws IOException; 85 86 /** 87 * Like {@link Iterator#remove()}. 88 * 89 * @throws IOException if an I/O error occurs. 90 */ 91 @SuppressWarnings("unused") remove()92 default void remove() throws IOException { 93 unwrap().remove(); 94 } 95 96 /** 97 * Unwraps this instance and returns the underlying {@link Iterator}. 98 * <p> 99 * Implementations may not have anything to unwrap and that behavior is undefined for now. 100 * </p> 101 * @return the underlying Iterator. 102 */ unwrap()103 Iterator<E> unwrap(); 104 105 } 106