1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * https://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19 package org.apache.commons.compress.utils;
20
21 import java.io.ByteArrayOutputStream;
22 import java.io.Closeable;
23 import java.io.EOFException;
24 import java.io.File;
25 import java.io.IOException;
26 import java.io.InputStream;
27 import java.io.OutputStream;
28 import java.nio.ByteBuffer;
29 import java.nio.channels.ReadableByteChannel;
30 import java.nio.file.Files;
31 import java.nio.file.LinkOption;
32
33 import org.apache.commons.io.FileUtils;
34 import org.apache.commons.io.output.NullOutputStream;
35
36 /**
37 * Utility functions.
38 *
39 * @Immutable (has mutable data but it is write-only).
40 */
41 public final class IOUtils {
42
43 /**
44 * Empty array of type {@link LinkOption}.
45 *
46 * @since 1.21
47 */
48 public static final LinkOption[] EMPTY_LINK_OPTIONS = {};
49
50 /**
51 * Closes the given Closeable and swallows any IOException that may occur.
52 *
53 * @param c Closeable to close, can be null
54 * @since 1.7
55 * @deprecated Use {@link org.apache.commons.io.IOUtils#closeQuietly(Closeable)}.
56 */
57 @Deprecated
58 public static void closeQuietly(final Closeable c) {
59 org.apache.commons.io.IOUtils.closeQuietly(c);
60 }
61
62 /**
63 * Copies the source file to the given output stream.
64 *
65 * @param sourceFile The file to read.
66 * @param outputStream The output stream to write.
67 * @throws IOException if an I/O error occurs when reading or writing.
68 * @since 1.21
69 * @deprecated Use {@link FileUtils#copyFile(File, OutputStream)}.
70 */
71 @Deprecated
72 public static void copy(final File sourceFile, final OutputStream outputStream) throws IOException {
73 FileUtils.copyFile(sourceFile, outputStream);
74 }
75
76 /**
77 * Copies the content of a InputStream into an OutputStream. Uses a default buffer size of 8192 bytes.
78 *
79 * @param input the InputStream to copy
80 * @param output the target
81 * @return the number of bytes copied, or -1 if greater than {@link Integer#MAX_VALUE}
82 * @throws IOException if an error occurs
83 * @throws NullPointerException if the {@code input} or the {@code output} is {@code null}
84 * @deprecated Use {@link org.apache.commons.io.IOUtils#copy(InputStream, OutputStream)}.
85 */
86 @Deprecated
87 public static long copy(final InputStream input, final OutputStream output) throws IOException {
88 return org.apache.commons.io.IOUtils.copy(input, output);
89 }
90
91 /**
92 * Copies the content of a InputStream into an OutputStream
93 *
94 * @param input the InputStream to copy
95 * @param output the target
96 * @param bufferSize the buffer size to use, must be bigger than 0
97 * @return the number of bytes copied
98 * @throws IOException if an error occurs
99 * @throws NullPointerException if the {@code input} or the {@code output} is {@code null}
100 * @deprecated Use {@link org.apache.commons.io.IOUtils#copy(InputStream, OutputStream, int)}.
101 */
102 @Deprecated
103 public static long copy(final InputStream input, final OutputStream output, final int bufferSize) throws IOException {
104 return org.apache.commons.io.IOUtils.copy(input, output, bufferSize);
105 }
106
107 /**
108 * Copies part of the content of a InputStream into an OutputStream. Uses a default buffer size of 8192 bytes.
109 *
110 * @param input the InputStream to copy
111 * @param output the target Stream
112 * @param len maximum amount of bytes to copy
113 * @return the number of bytes copied
114 * @throws IOException if an error occurs
115 * @since 1.21
116 * @deprecated Use {@link org.apache.commons.io.IOUtils#copyLarge(InputStream, OutputStream, long, long)}.
117 */
118 @Deprecated
119 public static long copyRange(final InputStream input, final long len, final OutputStream output) throws IOException {
120 return org.apache.commons.io.IOUtils.copyLarge(input, output, 0, len);
121 }
122
123 /**
124 * Copies part of the content of a InputStream into an OutputStream
125 *
126 * @param input the InputStream to copy
127 * @param length maximum amount of bytes to copy
128 * @param output the target, may be null to simulate output to dev/null on Linux and NUL on Windows
129 * @param bufferSize the buffer size to use, must be bigger than 0
130 * @return the number of bytes copied
131 * @throws IOException if an error occurs
132 * @throws IllegalArgumentException if bufferSize is smaller than or equal to 0
133 * @since 1.21
134 * @deprecated No longer used.
135 */
136 @Deprecated
137 public static long copyRange(final InputStream input, final long length, final OutputStream output, final int bufferSize) throws IOException {
138 if (bufferSize < 1) {
139 throw new IllegalArgumentException("bufferSize must be bigger than 0");
140 }
141 final byte[] buffer = new byte[(int) Math.min(bufferSize, Math.max(0, length))];
142 return org.apache.commons.io.IOUtils.copyLarge(input, output != null ? output : NullOutputStream.INSTANCE, 0, length, buffer);
143 }
144
145 /**
146 * Reads as much from the file as possible to fill the given array.
147 * <p>
148 * This method may invoke read repeatedly to fill the array and only read less bytes than the length of the array if the end of the stream has been reached.
149 * </p>
150 *
151 * @param file file to read
152 * @param array buffer to fill
153 * @return the number of bytes actually read
154 * @throws IOException on error
155 * @since 1.20
156 * @deprecated Use {@link Files#readAllBytes(java.nio.file.Path)}.
157 */
158 @Deprecated
159 public static int read(final File file, final byte[] array) throws IOException {
160 try (InputStream inputStream = Files.newInputStream(file.toPath())) {
161 return readFully(inputStream, array, 0, array.length);
162 }
163 }
164
165 /**
166 * Reads as much from input as possible to fill the given array.
167 * <p>
168 * This method may invoke read repeatedly to fill the array and only read less bytes than the length of the array if the end of the stream has been reached.
169 * </p>
170 *
171 * @param input stream to read from
172 * @param array buffer to fill
173 * @return the number of bytes actually read
174 * @throws IOException on error
175 */
176 public static int readFully(final InputStream input, final byte[] array) throws IOException {
177 return readFully(input, array, 0, array.length);
178 }
179
180 /**
181 * Reads as much from input as possible to fill the given array with the given amount of bytes.
182 * <p>
183 * This method may invoke read repeatedly to read the bytes and only read less bytes than the requested length if the end of the stream has been reached.
184 * </p>
185 *
186 * @param input stream to read from
187 * @param array buffer to fill
188 * @param offset offset into the buffer to start filling at
189 * @param length of bytes to read
190 * @return the number of bytes actually read
191 * @throws IOException if an I/O error has occurred
192 */
193 public static int readFully(final InputStream input, final byte[] array, final int offset, final int length) throws IOException {
194 if (length < 0 || offset < 0 || length + offset > array.length || length + offset < 0) {
195 throw new IndexOutOfBoundsException();
196 }
197 return org.apache.commons.io.IOUtils.read(input, array, offset, length);
198 }
199
200 /**
201 * Reads {@code b.remaining()} bytes from the given channel starting at the current channel's position.
202 * <p>
203 * This method reads repeatedly from the channel until the requested number of bytes are read. This method blocks until the requested number of bytes are
204 * read, the end of the channel is detected, or an exception is thrown.
205 * </p>
206 *
207 * @param channel the channel to read from
208 * @param byteBuffer the buffer into which the data is read.
209 * @throws IOException if an I/O error occurs.
210 * @throws EOFException if the channel reaches the end before reading all the bytes.
211 */
212 public static void readFully(final ReadableByteChannel channel, final ByteBuffer byteBuffer) throws IOException {
213 final int expectedLength = byteBuffer.remaining();
214 final int read = org.apache.commons.io.IOUtils.read(channel, byteBuffer);
215 if (read < expectedLength) {
216 throw new EOFException();
217 }
218 }
219
220 /**
221 * Gets part of the contents of an {@code InputStream} as a {@code byte[]}.
222 *
223 * @param input the {@code InputStream} to read from
224 * @param length maximum amount of bytes to copy
225 * @return the requested byte array
226 * @throws NullPointerException if the input is null
227 * @throws IOException if an I/O error occurs
228 * @since 1.21
229 */
230 public static byte[] readRange(final InputStream input, final int length) throws IOException {
231 final ByteArrayOutputStream output = new ByteArrayOutputStream();
232 org.apache.commons.io.IOUtils.copyLarge(input, output, 0, length);
233 return output.toByteArray();
234 }
235
236 /**
237 * Gets part of the contents of an {@code ReadableByteChannel} as a {@code byte[]}.
238 *
239 * @param input the {@code ReadableByteChannel} to read from
240 * @param length maximum amount of bytes to copy
241 * @return the requested byte array
242 * @throws NullPointerException if the input is null
243 * @throws IOException if an I/O error occurs
244 * @since 1.21
245 */
246 public static byte[] readRange(final ReadableByteChannel input, final int length) throws IOException {
247 final ByteArrayOutputStream output = new ByteArrayOutputStream();
248 final ByteBuffer byteBuffer = ByteBuffer.allocate(Math.min(length, org.apache.commons.io.IOUtils.DEFAULT_BUFFER_SIZE));
249 int read = 0;
250 while (read < length) {
251 // Make sure we never read more than len bytes
252 byteBuffer.limit(Math.min(length - read, byteBuffer.capacity()));
253 final int readCount = input.read(byteBuffer);
254 if (readCount <= 0) {
255 break;
256 }
257 output.write(byteBuffer.array(), 0, readCount);
258 byteBuffer.rewind();
259 read += readCount;
260 }
261 return output.toByteArray();
262 }
263
264 /**
265 * Skips bytes from an input byte stream.
266 * <p>
267 * This method will only skip less than the requested number of bytes if the end of the input stream has been reached.
268 * </p>
269 *
270 * @param input stream to skip bytes in
271 * @param toSkip the number of bytes to skip
272 * @return the number of bytes actually skipped
273 * @throws IOException on error
274 */
275 public static long skip(final InputStream input, final long toSkip) throws IOException {
276 return org.apache.commons.io.IOUtils.skip(input, toSkip, org.apache.commons.io.IOUtils::byteArray);
277 }
278
279 /**
280 * Gets the contents of an {@code InputStream} as a {@code byte[]}.
281 * <p>
282 * This method buffers the input internally, so there is no need to use a {@code BufferedInputStream}.
283 * </p>
284 *
285 * @param input the {@code InputStream} to read from
286 * @return the requested byte array
287 * @throws NullPointerException if the input is null
288 * @throws IOException if an I/O error occurs or reads more than {@link Integer#MAX_VALUE} occurs
289 * @since 1.5
290 * @deprecated Use {@link org.apache.commons.io.IOUtils#toByteArray(InputStream)}.
291 */
292 @Deprecated
293 public static byte[] toByteArray(final InputStream input) throws IOException {
294 return org.apache.commons.io.IOUtils.toByteArray(input);
295 }
296
297 /** Private constructor to prevent instantiation of this utility class. */
298 private IOUtils() {
299 }
300
301 }