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