001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017 018package org.apache.commons.io.function; 019 020import java.io.IOException; 021import java.io.UncheckedIOException; 022import java.util.Iterator; 023import java.util.NoSuchElementException; 024import java.util.Objects; 025import java.util.function.Consumer; 026 027/** 028 * Like {@link Iterator} but throws {@link IOException}. 029 * 030 * @param <E> the type of elements returned by this iterator. 031 * @since 2.12.0 032 */ 033public interface IOIterator<E> { 034 035 /** 036 * Adapts the given Iterator as an IOIterator. 037 * 038 * @param <E> the type of the stream elements. 039 * @param iterator The iterator to adapt 040 * @return A new IOIterator 041 */ 042 static <E> IOIterator<E> adapt(final Iterator<E> iterator) { 043 return IOIteratorAdapter.adapt(iterator); 044 } 045 046 /** 047 * Creates an {@link Iterator} for this instance that throws {@link UncheckedIOException} instead of 048 * {@link IOException}. 049 * 050 * @return an {@link UncheckedIOException} {@link Iterator}. 051 */ 052 default Iterator<E> asIterator() { 053 return new UncheckedIOIterator<>(this); 054 } 055 056 /** 057 * Like {@link Iterator#forEachRemaining(Consumer)}. 058 * 059 * @param action See delegate. 060 * @throws IOException if an I/O error occurs. 061 */ 062 default void forEachRemaining(final IOConsumer<? super E> action) throws IOException { 063 Objects.requireNonNull(action); 064 while (hasNext()) { 065 action.accept(next()); 066 } 067 } 068 069 /** 070 * Like {@link Iterator#hasNext()}. 071 * 072 * @return See delegate. 073 * @throws IOException if an I/O error occurs. 074 */ 075 boolean hasNext() throws IOException; 076 077 /** 078 * Like {@link Iterator#next()}. 079 * 080 * @return See delegate. 081 * @throws IOException if an I/O error occurs. 082 * @throws NoSuchElementException if the iteration has no more elements 083 */ 084 E next() throws IOException; 085 086 /** 087 * Like {@link Iterator#remove()}. 088 * 089 * @throws IOException if an I/O error occurs. 090 */ 091 @SuppressWarnings("unused") 092 default void remove() throws IOException { 093 unwrap().remove(); 094 } 095 096 /** 097 * Unwraps this instance and returns the underlying {@link Iterator}. 098 * <p> 099 * Implementations may not have anything to unwrap and that behavior is undefined for now. 100 * </p> 101 * @return the underlying Iterator. 102 */ 103 Iterator<E> unwrap(); 104 105}