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.Objects;
23 import java.util.function.Consumer;
24 import java.util.stream.Stream;
25
26 import org.apache.commons.io.IOExceptionList;
27 import org.apache.commons.io.IOIndexedException;
28
29 /**
30 * Like {@link Consumer} but throws {@link IOException}.
31 *
32 * @param <T> the type of the input to the operations.
33 * @since 2.7
34 */
35 @FunctionalInterface
36 public interface IOConsumer<T> {
37
38 /**
39 * Consider private.
40 */
41 IOConsumer<?> NOOP_IO_CONSUMER = t -> {
42 // noop
43 };
44
45 /**
46 * Performs an action for each element of the collection gathering any exceptions.
47 *
48 * @param action The action to apply to each input element.
49 * @param iterable The input to stream.
50 * @param <T> The element type.
51 * @throws IOExceptionList if any I/O errors occur.
52 * @since 2.12.0
53 */
54 static <T> void forAll(final IOConsumer<T> action, final Iterable<T> iterable) throws IOExceptionList {
55 IOStreams.forAll(IOStreams.of(iterable), action);
56 }
57
58 /**
59 * Performs an action for each element of the collection gathering any exceptions.
60 *
61 * @param action The action to apply to each input element.
62 * @param stream The input to stream.
63 * @param <T> The element type.
64 * @throws IOExceptionList if any I/O errors occur.
65 * @since 2.12.0
66 */
67 static <T> void forAll(final IOConsumer<T> action, final Stream<T> stream) throws IOExceptionList {
68 IOStreams.forAll(stream, action, IOIndexedException::new);
69 }
70
71 /**
72 * Performs an action for each element of the array, gathering any exceptions.
73 *
74 * @param action The action to apply to each input element.
75 * @param array The input to stream.
76 * @param <T> The element type.
77 * @throws IOExceptionList if any I/O errors occur.
78 * @since 2.12.0
79 */
80 @SafeVarargs
81 static <T> void forAll(final IOConsumer<T> action, final T... array) throws IOExceptionList {
82 IOStreams.forAll(IOStreams.of(array), action);
83 }
84
85 /**
86 * Performs an action for each element of the collection, stopping at the first exception.
87 *
88 * @param <T> The element type.
89 * @param iterable The input to stream.
90 * @param action The action to apply to each input element.
91 * @throws IOException if an I/O error occurs.
92 * @since 2.12.0
93 */
94 static <T> void forEach(final Iterable<T> iterable, final IOConsumer<T> action) throws IOException {
95 IOStreams.forEach(IOStreams.of(iterable), action);
96 }
97
98 /**
99 * Performs an action for each element of the stream, stopping at the first exception.
100 *
101 * @param <T> The element type.
102 * @param stream The input to stream.
103 * @param action The action to apply to each input element.
104 * @throws IOException if an I/O error occurs.
105 * @since 2.12.0
106 */
107 static <T> void forEach(final Stream<T> stream, final IOConsumer<T> action) throws IOException {
108 IOStreams.forEach(stream, action);
109 }
110
111 /**
112 * Performs an action for each element of this array, stopping at the first exception.
113 *
114 * @param <T> The element type.
115 * @param array The input to stream.
116 * @param action The action to apply to each input element.
117 * @throws IOException if an I/O error occurs.
118 * @since 2.12.0
119 */
120 static <T> void forEach(final T[] array, final IOConsumer<T> action) throws IOException {
121 IOStreams.forEach(IOStreams.of(array), action);
122 }
123
124 /**
125 * Returns the constant no-op consumer.
126 *
127 * @param <T> Type consumer type.
128 * @return a constant no-op consumer.
129 * @since 2.9.0
130 */
131 @SuppressWarnings("unchecked")
132 static <T> IOConsumer<T> noop() {
133 return (IOConsumer<T>) NOOP_IO_CONSUMER;
134 }
135
136 /**
137 * Performs this operation on the given argument.
138 *
139 * @param t the input argument
140 * @throws IOException if an I/O error occurs.
141 */
142 void accept(T t) throws IOException;
143
144 /**
145 * Returns a composed {@link IOConsumer} that performs, in sequence, this operation followed by the {@code after}
146 * operation. If performing either operation throws an exception, it is relayed to the caller of the composed operation.
147 * If performing this operation throws an exception, the {@code after} operation will not be performed.
148 *
149 * @param after the operation to perform after this operation
150 * @return a composed {@link Consumer} that performs in sequence this operation followed by the {@code after} operation
151 * @throws NullPointerException if {@code after} is null
152 */
153 default IOConsumer<T> andThen(final IOConsumer<? super T> after) {
154 Objects.requireNonNull(after, "after");
155 return (final T t) -> {
156 accept(t);
157 after.accept(t);
158 };
159 }
160
161 /**
162 * Creates a {@link Consumer} for this instance that throws {@link UncheckedIOException} instead of {@link IOException}.
163 *
164 * @return an UncheckedIOException Consumer.
165 * @since 2.12.0
166 */
167 default Consumer<T> asConsumer() {
168 return t -> Uncheck.accept(this, t);
169 }
170
171 }