001/* 002 * Licensed to the Apache Software Foundation (ASF) under one 003 * or more contributor license agreements. See the NOTICE file 004 * distributed with this work for additional information 005 * regarding copyright ownership. The ASF licenses this file 006 * to you under the Apache License, Version 2.0 (the 007 * "License"); you may not use this file except in compliance 008 * with the License. You may obtain a copy of the License at 009 * 010 * https://www.apache.org/licenses/LICENSE-2.0 011 * 012 * Unless required by applicable law or agreed to in writing, 013 * software distributed under the License is distributed on an 014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 015 * KIND, either express or implied. See the License for the 016 * specific language governing permissions and limitations 017 * under the License. 018 */ 019package org.apache.commons.compress.utils; 020 021import java.io.ByteArrayOutputStream; 022import java.io.Closeable; 023import java.io.EOFException; 024import java.io.File; 025import java.io.IOException; 026import java.io.InputStream; 027import java.io.OutputStream; 028import java.nio.ByteBuffer; 029import java.nio.channels.ReadableByteChannel; 030import java.nio.file.Files; 031import java.nio.file.LinkOption; 032 033import org.apache.commons.io.FileUtils; 034import org.apache.commons.io.output.NullOutputStream; 035 036/** 037 * Utility functions. 038 * 039 * @Immutable (has mutable data but it is write-only). 040 */ 041public final class IOUtils { 042 043 /** 044 * Empty array of type {@link LinkOption}. 045 * 046 * @since 1.21 047 */ 048 public static final LinkOption[] EMPTY_LINK_OPTIONS = {}; 049 050 /** 051 * Closes the given Closeable and swallows any IOException that may occur. 052 * 053 * @param c Closeable to close, can be null 054 * @since 1.7 055 * @deprecated Use {@link org.apache.commons.io.IOUtils#closeQuietly(Closeable)}. 056 */ 057 @Deprecated 058 public static void closeQuietly(final Closeable c) { 059 org.apache.commons.io.IOUtils.closeQuietly(c); 060 } 061 062 /** 063 * Copies the source file to the given output stream. 064 * 065 * @param sourceFile The file to read. 066 * @param outputStream The output stream to write. 067 * @throws IOException if an I/O error occurs when reading or writing. 068 * @since 1.21 069 * @deprecated Use {@link FileUtils#copyFile(File, OutputStream)}. 070 */ 071 @Deprecated 072 public static void copy(final File sourceFile, final OutputStream outputStream) throws IOException { 073 FileUtils.copyFile(sourceFile, outputStream); 074 } 075 076 /** 077 * Copies the content of a InputStream into an OutputStream. Uses a default buffer size of 8192 bytes. 078 * 079 * @param input the InputStream to copy 080 * @param output the target 081 * @return the number of bytes copied, or -1 if greater than {@link Integer#MAX_VALUE} 082 * @throws IOException if an error occurs 083 * @throws NullPointerException if the {@code input} or the {@code output} is {@code null} 084 * @deprecated Use {@link org.apache.commons.io.IOUtils#copy(InputStream, OutputStream)}. 085 */ 086 @Deprecated 087 public static long copy(final InputStream input, final OutputStream output) throws IOException { 088 return org.apache.commons.io.IOUtils.copy(input, output); 089 } 090 091 /** 092 * Copies the content of a InputStream into an OutputStream 093 * 094 * @param input the InputStream to copy 095 * @param output the target 096 * @param bufferSize the buffer size to use, must be bigger than 0 097 * @return the number of bytes copied 098 * @throws IOException if an error occurs 099 * @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}