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 */ 017package org.apache.commons.io; 018 019import java.io.BufferedInputStream; 020import java.io.BufferedOutputStream; 021import java.io.BufferedReader; 022import java.io.BufferedWriter; 023import java.io.ByteArrayInputStream; 024import java.io.CharArrayWriter; 025import java.io.Closeable; 026import java.io.EOFException; 027import java.io.File; 028import java.io.IOException; 029import java.io.InputStream; 030import java.io.InputStreamReader; 031import java.io.OutputStream; 032import java.io.OutputStreamWriter; 033import java.io.Reader; 034import java.io.UncheckedIOException; 035import java.io.Writer; 036import java.net.HttpURLConnection; 037import java.net.ServerSocket; 038import java.net.Socket; 039import java.net.URI; 040import java.net.URL; 041import java.net.URLConnection; 042import java.nio.ByteBuffer; 043import java.nio.CharBuffer; 044import java.nio.channels.Channels; 045import java.nio.channels.ReadableByteChannel; 046import java.nio.channels.Selector; 047import java.nio.charset.Charset; 048import java.nio.charset.StandardCharsets; 049import java.nio.file.Files; 050import java.util.Arrays; 051import java.util.Collection; 052import java.util.Iterator; 053import java.util.List; 054import java.util.Objects; 055import java.util.function.Consumer; 056import java.util.function.Supplier; 057import java.util.stream.Collectors; 058import java.util.stream.Stream; 059import java.util.zip.InflaterInputStream; 060 061import org.apache.commons.io.function.IOConsumer; 062import org.apache.commons.io.function.IOSupplier; 063import org.apache.commons.io.function.IOTriFunction; 064import org.apache.commons.io.input.QueueInputStream; 065import org.apache.commons.io.output.AppendableWriter; 066import org.apache.commons.io.output.ByteArrayOutputStream; 067import org.apache.commons.io.output.NullOutputStream; 068import org.apache.commons.io.output.NullWriter; 069import org.apache.commons.io.output.StringBuilderWriter; 070import org.apache.commons.io.output.ThresholdingOutputStream; 071import org.apache.commons.io.output.UnsynchronizedByteArrayOutputStream; 072 073/** 074 * General IO stream manipulation utilities. 075 * <p> 076 * This class provides static utility methods for input/output operations. 077 * </p> 078 * <ul> 079 * <li>closeQuietly - these methods close a stream ignoring nulls and exceptions 080 * <li>toXxx/read - these methods read data from a stream 081 * <li>write - these methods write data to a stream 082 * <li>copy - these methods copy all the data from one stream to another 083 * <li>contentEquals - these methods compare the content of two streams 084 * </ul> 085 * <p> 086 * The byte-to-char methods and char-to-byte methods involve a conversion step. 087 * Two methods are provided in each case, one that uses the platform default 088 * encoding and the other which allows you to specify an encoding. You are 089 * encouraged to always specify an encoding because relying on the platform 090 * default can lead to unexpected results, for example when moving from 091 * development to production. 092 * </p> 093 * <p> 094 * All the methods in this class that read a stream are buffered internally. 095 * This means that there is no cause to use a {@link BufferedInputStream} 096 * or {@link BufferedReader}. The default buffer size of 4K has been shown 097 * to be efficient in tests. 098 * </p> 099 * <p> 100 * The various copy methods all delegate the actual copying to one of the following methods: 101 * </p> 102 * <ul> 103 * <li>{@link #copyLarge(InputStream, OutputStream, byte[])}</li> 104 * <li>{@link #copyLarge(InputStream, OutputStream, long, long, byte[])}</li> 105 * <li>{@link #copyLarge(Reader, Writer, char[])}</li> 106 * <li>{@link #copyLarge(Reader, Writer, long, long, char[])}</li> 107 * </ul> 108 * For example, {@link #copy(InputStream, OutputStream)} calls {@link #copyLarge(InputStream, OutputStream)} 109 * which calls {@link #copy(InputStream, OutputStream, int)} which creates the buffer and calls 110 * {@link #copyLarge(InputStream, OutputStream, byte[])}. 111 * <p> 112 * Applications can re-use buffers by using the underlying methods directly. 113 * This may improve performance for applications that need to do a lot of copying. 114 * </p> 115 * <p> 116 * Wherever possible, the methods in this class do <em>not</em> flush or close 117 * the stream. This is to avoid making non-portable assumptions about the 118 * streams' origin and further use. Thus the caller is still responsible for 119 * closing streams after use. 120 * </p> 121 * <p> 122 * Provenance: Excalibur. 123 * </p> 124 */ 125public class IOUtils { 126 // NOTE: This class is focused on InputStream, OutputStream, Reader and 127 // Writer. Each method should take at least one of these as a parameter, 128 // or return one of them. 129 130 /** 131 * CR char. 132 * 133 * @since 2.9.0 134 */ 135 public static final int CR = '\r'; 136 137 /** 138 * The default buffer size ({@value}) to use in copy methods. 139 */ 140 public static final int DEFAULT_BUFFER_SIZE = 8192; 141 142 /** 143 * The system directory separator character. 144 */ 145 public static final char DIR_SEPARATOR = File.separatorChar; 146 147 /** 148 * The Unix directory separator character. 149 */ 150 public static final char DIR_SEPARATOR_UNIX = '/'; 151 152 /** 153 * The Windows directory separator character. 154 */ 155 public static final char DIR_SEPARATOR_WINDOWS = '\\'; 156 157 /** 158 * A singleton empty byte array. 159 * 160 * @since 2.9.0 161 */ 162 public static final byte[] EMPTY_BYTE_ARRAY = {}; 163 164 /** 165 * Represents the end-of-file (or stream). 166 * @since 2.5 (made public) 167 */ 168 public static final int EOF = -1; 169 170 /** 171 * LF char. 172 * 173 * @since 2.9.0 174 */ 175 public static final int LF = '\n'; 176 177 /** 178 * The system line separator string. 179 * 180 * @deprecated Use {@link System#lineSeparator()}. 181 */ 182 @Deprecated 183 public static final String LINE_SEPARATOR = System.lineSeparator(); 184 185 /** 186 * The Unix line separator string. 187 * 188 * @see StandardLineSeparator#LF 189 */ 190 public static final String LINE_SEPARATOR_UNIX = StandardLineSeparator.LF.getString(); 191 192 /** 193 * The Windows line separator string. 194 * 195 * @see StandardLineSeparator#CRLF 196 */ 197 public static final String LINE_SEPARATOR_WINDOWS = StandardLineSeparator.CRLF.getString(); 198 199 /** 200 * Internal byte array buffer, intended for both reading and writing. 201 */ 202 private static final ThreadLocal<byte[]> SCRATCH_BYTE_BUFFER_RW = ThreadLocal.withInitial(IOUtils::byteArray); 203 204 /** 205 * Internal byte array buffer, intended for write only operations. 206 */ 207 private static final byte[] SCRATCH_BYTE_BUFFER_WO = byteArray(); 208 209 /** 210 * Internal char array buffer, intended for both reading and writing. 211 */ 212 private static final ThreadLocal<char[]> SCRATCH_CHAR_BUFFER_RW = ThreadLocal.withInitial(IOUtils::charArray); 213 214 /** 215 * Internal char array buffer, intended for write only operations. 216 */ 217 private static final char[] SCRATCH_CHAR_BUFFER_WO = charArray(); 218 219 /** 220 * Returns the given InputStream if it is already a {@link BufferedInputStream}, otherwise creates a 221 * BufferedInputStream from the given InputStream. 222 * 223 * @param inputStream the InputStream to wrap or return (not null) 224 * @return the given InputStream or a new {@link BufferedInputStream} for the given InputStream 225 * @throws NullPointerException if the input parameter is null 226 * @since 2.5 227 */ 228 @SuppressWarnings("resource") // parameter null check 229 public static BufferedInputStream buffer(final InputStream inputStream) { 230 // reject null early on rather than waiting for IO operation to fail 231 // not checked by BufferedInputStream 232 Objects.requireNonNull(inputStream, "inputStream"); 233 return inputStream instanceof BufferedInputStream ? 234 (BufferedInputStream) inputStream : new BufferedInputStream(inputStream); 235 } 236 237 /** 238 * Returns the given InputStream if it is already a {@link BufferedInputStream}, otherwise creates a 239 * BufferedInputStream from the given InputStream. 240 * 241 * @param inputStream the InputStream to wrap or return (not null) 242 * @param size the buffer size, if a new BufferedInputStream is created. 243 * @return the given InputStream or a new {@link BufferedInputStream} for the given InputStream 244 * @throws NullPointerException if the input parameter is null 245 * @since 2.5 246 */ 247 @SuppressWarnings("resource") // parameter null check 248 public static BufferedInputStream buffer(final InputStream inputStream, final int size) { 249 // reject null early on rather than waiting for IO operation to fail 250 // not checked by BufferedInputStream 251 Objects.requireNonNull(inputStream, "inputStream"); 252 return inputStream instanceof BufferedInputStream ? 253 (BufferedInputStream) inputStream : new BufferedInputStream(inputStream, size); 254 } 255 256 /** 257 * Returns the given OutputStream if it is already a {@link BufferedOutputStream}, otherwise creates a 258 * BufferedOutputStream from the given OutputStream. 259 * 260 * @param outputStream the OutputStream to wrap or return (not null) 261 * @return the given OutputStream or a new {@link BufferedOutputStream} for the given OutputStream 262 * @throws NullPointerException if the input parameter is null 263 * @since 2.5 264 */ 265 @SuppressWarnings("resource") // parameter null check 266 public static BufferedOutputStream buffer(final OutputStream outputStream) { 267 // reject null early on rather than waiting for IO operation to fail 268 // not checked by BufferedInputStream 269 Objects.requireNonNull(outputStream, "outputStream"); 270 return outputStream instanceof BufferedOutputStream ? 271 (BufferedOutputStream) outputStream : new BufferedOutputStream(outputStream); 272 } 273 274 /** 275 * Returns the given OutputStream if it is already a {@link BufferedOutputStream}, otherwise creates a 276 * BufferedOutputStream from the given OutputStream. 277 * 278 * @param outputStream the OutputStream to wrap or return (not null) 279 * @param size the buffer size, if a new BufferedOutputStream is created. 280 * @return the given OutputStream or a new {@link BufferedOutputStream} for the given OutputStream 281 * @throws NullPointerException if the input parameter is null 282 * @since 2.5 283 */ 284 @SuppressWarnings("resource") // parameter null check 285 public static BufferedOutputStream buffer(final OutputStream outputStream, final int size) { 286 // reject null early on rather than waiting for IO operation to fail 287 // not checked by BufferedInputStream 288 Objects.requireNonNull(outputStream, "outputStream"); 289 return outputStream instanceof BufferedOutputStream ? 290 (BufferedOutputStream) outputStream : new BufferedOutputStream(outputStream, size); 291 } 292 293 /** 294 * Returns the given reader if it is already a {@link BufferedReader}, otherwise creates a BufferedReader from 295 * the given reader. 296 * 297 * @param reader the reader to wrap or return (not null) 298 * @return the given reader or a new {@link BufferedReader} for the given reader 299 * @throws NullPointerException if the input parameter is null 300 * @since 2.5 301 */ 302 public static BufferedReader buffer(final Reader reader) { 303 return reader instanceof BufferedReader ? (BufferedReader) reader : new BufferedReader(reader); 304 } 305 306 /** 307 * Returns the given reader if it is already a {@link BufferedReader}, otherwise creates a BufferedReader from the 308 * given reader. 309 * 310 * @param reader the reader to wrap or return (not null) 311 * @param size the buffer size, if a new BufferedReader is created. 312 * @return the given reader or a new {@link BufferedReader} for the given reader 313 * @throws NullPointerException if the input parameter is null 314 * @since 2.5 315 */ 316 public static BufferedReader buffer(final Reader reader, final int size) { 317 return reader instanceof BufferedReader ? (BufferedReader) reader : new BufferedReader(reader, size); 318 } 319 320 /** 321 * Returns the given Writer if it is already a {@link BufferedWriter}, otherwise creates a BufferedWriter from the 322 * given Writer. 323 * 324 * @param writer the Writer to wrap or return (not null) 325 * @return the given Writer or a new {@link BufferedWriter} for the given Writer 326 * @throws NullPointerException if the input parameter is null 327 * @since 2.5 328 */ 329 public static BufferedWriter buffer(final Writer writer) { 330 return writer instanceof BufferedWriter ? (BufferedWriter) writer : new BufferedWriter(writer); 331 } 332 333 /** 334 * Returns the given Writer if it is already a {@link BufferedWriter}, otherwise creates a BufferedWriter from the 335 * given Writer. 336 * 337 * @param writer the Writer to wrap or return (not null) 338 * @param size the buffer size, if a new BufferedWriter is created. 339 * @return the given Writer or a new {@link BufferedWriter} for the given Writer 340 * @throws NullPointerException if the input parameter is null 341 * @since 2.5 342 */ 343 public static BufferedWriter buffer(final Writer writer, final int size) { 344 return writer instanceof BufferedWriter ? (BufferedWriter) writer : new BufferedWriter(writer, size); 345 } 346 347 /** 348 * Returns a new byte array of size {@link #DEFAULT_BUFFER_SIZE}. 349 * 350 * @return a new byte array of size {@link #DEFAULT_BUFFER_SIZE}. 351 * @since 2.9.0 352 */ 353 public static byte[] byteArray() { 354 return byteArray(DEFAULT_BUFFER_SIZE); 355 } 356 357 /** 358 * Returns a new byte array of the given size. 359 * 360 * TODO Consider guarding or warning against large allocations... 361 * 362 * @param size array size. 363 * @return a new byte array of the given size. 364 * @throws NegativeArraySizeException if the size is negative. 365 * @since 2.9.0 366 */ 367 public static byte[] byteArray(final int size) { 368 return new byte[size]; 369 } 370 371 /** 372 * Returns a new char array of size {@link #DEFAULT_BUFFER_SIZE}. 373 * 374 * @return a new char array of size {@link #DEFAULT_BUFFER_SIZE}. 375 * @since 2.9.0 376 */ 377 private static char[] charArray() { 378 return charArray(DEFAULT_BUFFER_SIZE); 379 } 380 381 /** 382 * Returns a new char array of the given size. 383 * 384 * TODO Consider guarding or warning against large allocations... 385 * 386 * @param size array size. 387 * @return a new char array of the given size. 388 * @since 2.9.0 389 */ 390 private static char[] charArray(final int size) { 391 return new char[size]; 392 } 393 394 /** 395 * Clears any state. 396 * <ul> 397 * <li>Removes the current thread's value for thread-local variables.</li> 398 * <li>Sets static scratch arrays to 0s.</li> 399 * </ul> 400 * @see IO#clear() 401 */ 402 static void clear() { 403 SCRATCH_BYTE_BUFFER_RW.remove(); 404 SCRATCH_CHAR_BUFFER_RW.remove(); 405 Arrays.fill(SCRATCH_BYTE_BUFFER_WO, (byte) 0); 406 Arrays.fill(SCRATCH_CHAR_BUFFER_WO, (char) 0); 407 } 408 409 /** 410 * Closes the given {@link Closeable} as a null-safe operation. 411 * 412 * @param closeable The resource to close, may be null. 413 * @throws IOException if an I/O error occurs. 414 * @since 2.7 415 */ 416 public static void close(final Closeable closeable) throws IOException { 417 if (closeable != null) { 418 closeable.close(); 419 } 420 } 421 422 /** 423 * Closes the given {@link Closeable}s as null-safe operations. 424 * 425 * @param closeables The resource(s) to close, may be null. 426 * @throws IOExceptionList if an I/O error occurs. 427 * @since 2.8.0 428 */ 429 public static void close(final Closeable... closeables) throws IOExceptionList { 430 IOConsumer.forAll(IOUtils::close, closeables); 431 } 432 433 /** 434 * Closes the given {@link Closeable} as a null-safe operation. 435 * 436 * @param closeable The resource to close, may be null. 437 * @param consumer Consume the IOException thrown by {@link Closeable#close()}. 438 * @throws IOException if an I/O error occurs. 439 * @since 2.7 440 */ 441 public static void close(final Closeable closeable, final IOConsumer<IOException> consumer) throws IOException { 442 if (closeable != null) { 443 try { 444 closeable.close(); 445 } catch (final IOException e) { 446 if (consumer != null) { 447 consumer.accept(e); 448 } 449 } 450 } 451 } 452 453 /** 454 * Closes a URLConnection. 455 * 456 * @param conn the connection to close. 457 * @since 2.4 458 */ 459 public static void close(final URLConnection conn) { 460 if (conn instanceof HttpURLConnection) { 461 ((HttpURLConnection) conn).disconnect(); 462 } 463 } 464 465 /** 466 * Avoids the need to type cast. 467 * 468 * @param closeable the object to close, may be null 469 */ 470 private static void closeQ(final Closeable closeable) { 471 closeQuietly(closeable, null); 472 } 473 474 /** 475 * Closes a {@link Closeable} unconditionally. 476 * 477 * <p> 478 * Equivalent to {@link Closeable#close()}, except any exceptions will be ignored. This is typically used in 479 * finally blocks. 480 * <p> 481 * Example code: 482 * </p> 483 * <pre> 484 * Closeable closeable = null; 485 * try { 486 * closeable = new FileReader("foo.txt"); 487 * // process closeable 488 * closeable.close(); 489 * } catch (Exception e) { 490 * // error handling 491 * } finally { 492 * IOUtils.closeQuietly(closeable); 493 * } 494 * </pre> 495 * <p> 496 * Closing all streams: 497 * </p> 498 * <pre> 499 * try { 500 * return IOUtils.copy(inputStream, outputStream); 501 * } finally { 502 * IOUtils.closeQuietly(inputStream); 503 * IOUtils.closeQuietly(outputStream); 504 * } 505 * </pre> 506 * <p> 507 * Also consider using a try-with-resources statement where appropriate. 508 * </p> 509 * 510 * @param closeable the objects to close, may be null or already closed 511 * @since 2.0 512 * 513 * @see Throwable#addSuppressed(Throwable) 514 */ 515 public static void closeQuietly(final Closeable closeable) { 516 closeQuietly(closeable, null); 517 } 518 519 /** 520 * Closes a {@link Closeable} unconditionally. 521 * <p> 522 * Equivalent to {@link Closeable#close()}, except any exceptions will be ignored. 523 * <p> 524 * This is typically used in finally blocks to ensure that the closeable is closed 525 * even if an Exception was thrown before the normal close statement was reached. 526 * <br> 527 * <b>It should not be used to replace the close statement(s) 528 * which should be present for the non-exceptional case.</b> 529 * <br> 530 * It is only intended to simplify tidying up where normal processing has already failed 531 * and reporting close failure as well is not necessary or useful. 532 * <p> 533 * Example code: 534 * </p> 535 * <pre> 536 * Closeable closeable = null; 537 * try { 538 * closeable = new FileReader("foo.txt"); 539 * // processing using the closeable; may throw an Exception 540 * closeable.close(); // Normal close - exceptions not ignored 541 * } catch (Exception e) { 542 * // error handling 543 * } finally { 544 * <b>IOUtils.closeQuietly(closeable); // In case normal close was skipped due to Exception</b> 545 * } 546 * </pre> 547 * <p> 548 * Closing all streams: 549 * <br> 550 * <pre> 551 * try { 552 * return IOUtils.copy(inputStream, outputStream); 553 * } finally { 554 * IOUtils.closeQuietly(inputStream, outputStream); 555 * } 556 * </pre> 557 * <p> 558 * Also consider using a try-with-resources statement where appropriate. 559 * </p> 560 * @param closeables the objects to close, may be null or already closed 561 * @see #closeQuietly(Closeable) 562 * @since 2.5 563 * @see Throwable#addSuppressed(Throwable) 564 */ 565 public static void closeQuietly(final Closeable... closeables) { 566 if (closeables != null) { 567 closeQuietly(Arrays.stream(closeables)); 568 } 569 } 570 571 /** 572 * Closes the given {@link Closeable} as a null-safe operation while consuming IOException by the given {@code consumer}. 573 * 574 * @param closeable The resource to close, may be null. 575 * @param consumer Consumes the IOException thrown by {@link Closeable#close()}. 576 * @since 2.7 577 */ 578 public static void closeQuietly(final Closeable closeable, final Consumer<IOException> consumer) { 579 if (closeable != null) { 580 try { 581 closeable.close(); 582 } catch (final IOException e) { 583 if (consumer != null) { 584 consumer.accept(e); 585 } 586 } 587 } 588 } 589 590 /** 591 * Closes an {@link InputStream} unconditionally. 592 * <p> 593 * Equivalent to {@link InputStream#close()}, except any exceptions will be ignored. 594 * This is typically used in finally blocks. 595 * </p> 596 * <p> 597 * Example code: 598 * </p> 599 * <pre> 600 * byte[] data = new byte[1024]; 601 * InputStream in = null; 602 * try { 603 * in = new FileInputStream("foo.txt"); 604 * in.read(data); 605 * in.close(); //close errors are handled 606 * } catch (Exception e) { 607 * // error handling 608 * } finally { 609 * IOUtils.closeQuietly(in); 610 * } 611 * </pre> 612 * <p> 613 * Also consider using a try-with-resources statement where appropriate. 614 * </p> 615 * 616 * @param input the InputStream to close, may be null or already closed 617 * @see Throwable#addSuppressed(Throwable) 618 */ 619 public static void closeQuietly(final InputStream input) { 620 closeQ(input); 621 } 622 623 /** 624 * Closes an iterable of {@link Closeable} unconditionally. 625 * <p> 626 * Equivalent calling {@link Closeable#close()} on each element, except any exceptions will be ignored. 627 * </p> 628 * 629 * @param closeables the objects to close, may be null or already closed 630 * @see #closeQuietly(Closeable) 631 * @since 2.12.0 632 */ 633 public static void closeQuietly(final Iterable<Closeable> closeables) { 634 if (closeables != null) { 635 closeables.forEach(IOUtils::closeQuietly); 636 } 637 } 638 639 /** 640 * Closes an {@link OutputStream} unconditionally. 641 * <p> 642 * Equivalent to {@link OutputStream#close()}, except any exceptions will be ignored. 643 * This is typically used in finally blocks. 644 * </p> 645 * <p> 646 * Example code: 647 * </p> 648 * <pre> 649 * byte[] data = "Hello, World".getBytes(); 650 * 651 * OutputStream out = null; 652 * try { 653 * out = new FileOutputStream("foo.txt"); 654 * out.write(data); 655 * out.close(); //close errors are handled 656 * } catch (IOException e) { 657 * // error handling 658 * } finally { 659 * IOUtils.closeQuietly(out); 660 * } 661 * </pre> 662 * <p> 663 * Also consider using a try-with-resources statement where appropriate. 664 * </p> 665 * 666 * @param output the OutputStream to close, may be null or already closed 667 * @see Throwable#addSuppressed(Throwable) 668 */ 669 public static void closeQuietly(final OutputStream output) { 670 closeQ(output); 671 } 672 673 /** 674 * Closes an {@link Reader} unconditionally. 675 * <p> 676 * Equivalent to {@link Reader#close()}, except any exceptions will be ignored. 677 * This is typically used in finally blocks. 678 * </p> 679 * <p> 680 * Example code: 681 * </p> 682 * <pre> 683 * char[] data = new char[1024]; 684 * Reader in = null; 685 * try { 686 * in = new FileReader("foo.txt"); 687 * in.read(data); 688 * in.close(); //close errors are handled 689 * } catch (Exception e) { 690 * // error handling 691 * } finally { 692 * IOUtils.closeQuietly(in); 693 * } 694 * </pre> 695 * <p> 696 * Also consider using a try-with-resources statement where appropriate. 697 * </p> 698 * 699 * @param reader the Reader to close, may be null or already closed 700 * @see Throwable#addSuppressed(Throwable) 701 */ 702 public static void closeQuietly(final Reader reader) { 703 closeQ(reader); 704 } 705 706 /** 707 * Closes a {@link Selector} unconditionally. 708 * <p> 709 * Equivalent to {@link Selector#close()}, except any exceptions will be ignored. 710 * This is typically used in finally blocks. 711 * </p> 712 * <p> 713 * Example code: 714 * </p> 715 * <pre> 716 * Selector selector = null; 717 * try { 718 * selector = Selector.open(); 719 * // process socket 720 * 721 * } catch (Exception e) { 722 * // error handling 723 * } finally { 724 * IOUtils.closeQuietly(selector); 725 * } 726 * </pre> 727 * <p> 728 * Also consider using a try-with-resources statement where appropriate. 729 * </p> 730 * 731 * @param selector the Selector to close, may be null or already closed 732 * @since 2.2 733 * @see Throwable#addSuppressed(Throwable) 734 */ 735 public static void closeQuietly(final Selector selector) { 736 closeQ(selector); 737 } 738 739 /** 740 * Closes a {@link ServerSocket} unconditionally. 741 * <p> 742 * Equivalent to {@link ServerSocket#close()}, except any exceptions will be ignored. 743 * This is typically used in finally blocks. 744 * </p> 745 * <p> 746 * Example code: 747 * </p> 748 * <pre> 749 * ServerSocket socket = null; 750 * try { 751 * socket = new ServerSocket(); 752 * // process socket 753 * socket.close(); 754 * } catch (Exception e) { 755 * // error handling 756 * } finally { 757 * IOUtils.closeQuietly(socket); 758 * } 759 * </pre> 760 * <p> 761 * Also consider using a try-with-resources statement where appropriate. 762 * </p> 763 * 764 * @param serverSocket the ServerSocket to close, may be null or already closed 765 * @since 2.2 766 * @see Throwable#addSuppressed(Throwable) 767 */ 768 public static void closeQuietly(final ServerSocket serverSocket) { 769 closeQ(serverSocket); 770 } 771 772 /** 773 * Closes a {@link Socket} unconditionally. 774 * <p> 775 * Equivalent to {@link Socket#close()}, except any exceptions will be ignored. 776 * This is typically used in finally blocks. 777 * </p> 778 * <p> 779 * Example code: 780 * </p> 781 * <pre> 782 * Socket socket = null; 783 * try { 784 * socket = new Socket("http://www.foo.com/", 80); 785 * // process socket 786 * socket.close(); 787 * } catch (Exception e) { 788 * // error handling 789 * } finally { 790 * IOUtils.closeQuietly(socket); 791 * } 792 * </pre> 793 * <p> 794 * Also consider using a try-with-resources statement where appropriate. 795 * </p> 796 * 797 * @param socket the Socket to close, may be null or already closed 798 * @since 2.0 799 * @see Throwable#addSuppressed(Throwable) 800 */ 801 public static void closeQuietly(final Socket socket) { 802 closeQ(socket); 803 } 804 805 /** 806 * Closes a stream of {@link Closeable} unconditionally. 807 * <p> 808 * Equivalent calling {@link Closeable#close()} on each element, except any exceptions will be ignored. 809 * </p> 810 * 811 * @param closeables the objects to close, may be null or already closed 812 * @see #closeQuietly(Closeable) 813 * @since 2.12.0 814 */ 815 public static void closeQuietly(final Stream<Closeable> closeables) { 816 if (closeables != null) { 817 closeables.forEach(IOUtils::closeQuietly); 818 } 819 } 820 821 /** 822 * Closes an {@link Writer} unconditionally. 823 * <p> 824 * Equivalent to {@link Writer#close()}, except any exceptions will be ignored. 825 * This is typically used in finally blocks. 826 * </p> 827 * <p> 828 * Example code: 829 * </p> 830 * <pre> 831 * Writer out = null; 832 * try { 833 * out = new StringWriter(); 834 * out.write("Hello World"); 835 * out.close(); //close errors are handled 836 * } catch (Exception e) { 837 * // error handling 838 * } finally { 839 * IOUtils.closeQuietly(out); 840 * } 841 * </pre> 842 * <p> 843 * Also consider using a try-with-resources statement where appropriate. 844 * </p> 845 * 846 * @param writer the Writer to close, may be null or already closed 847 * @see Throwable#addSuppressed(Throwable) 848 */ 849 public static void closeQuietly(final Writer writer) { 850 closeQ(writer); 851 } 852 853 /** 854 * Consumes bytes from a {@link InputStream} and ignores them. 855 * <p> 856 * The buffer size is given by {@link #DEFAULT_BUFFER_SIZE}. 857 * </p> 858 * 859 * @param input the {@link InputStream} to read. 860 * @return the number of bytes copied. or {@code 0} if {@code input is null}. 861 * @throws NullPointerException if the InputStream is {@code null}. 862 * @throws IOException if an I/O error occurs. 863 * @since 2.8.0 864 */ 865 public static long consume(final InputStream input) throws IOException { 866 return copyLarge(input, NullOutputStream.INSTANCE); 867 } 868 869 /** 870 * Consumes characters from a {@link Reader} and ignores them. 871 * <p> 872 * The buffer size is given by {@link #DEFAULT_BUFFER_SIZE}. 873 * </p> 874 * 875 * @param input the {@link Reader} to read. 876 * @return the number of bytes copied. or {@code 0} if {@code input is null}. 877 * @throws NullPointerException if the Reader is {@code null}. 878 * @throws IOException if an I/O error occurs. 879 * @since 2.12.0 880 */ 881 public static long consume(final Reader input) throws IOException { 882 return copyLarge(input, NullWriter.INSTANCE); 883 } 884 885 /** 886 * Compares the contents of two Streams to determine if they are equal or 887 * not. 888 * <p> 889 * This method buffers the input internally using 890 * {@link BufferedInputStream} if they are not already buffered. 891 * </p> 892 * 893 * @param input1 the first stream 894 * @param input2 the second stream 895 * @return true if the content of the streams are equal or they both don't 896 * exist, false otherwise 897 * @throws IOException if an I/O error occurs 898 */ 899 public static boolean contentEquals(final InputStream input1, final InputStream input2) throws IOException { 900 // Before making any changes, please test with 901 // org.apache.commons.io.jmh.IOUtilsContentEqualsInputStreamsBenchmark 902 if (input1 == input2) { 903 return true; 904 } 905 if (input1 == null || input2 == null) { 906 return false; 907 } 908 909 // reuse one 910 final byte[] array1 = getScratchByteArray(); 911 // allocate another 912 final byte[] array2 = byteArray(); 913 int pos1; 914 int pos2; 915 int count1; 916 int count2; 917 while (true) { 918 pos1 = 0; 919 pos2 = 0; 920 for (int index = 0; index < DEFAULT_BUFFER_SIZE; index++) { 921 if (pos1 == index) { 922 do { 923 count1 = input1.read(array1, pos1, DEFAULT_BUFFER_SIZE - pos1); 924 } while (count1 == 0); 925 if (count1 == EOF) { 926 return pos2 == index && input2.read() == EOF; 927 } 928 pos1 += count1; 929 } 930 if (pos2 == index) { 931 do { 932 count2 = input2.read(array2, pos2, DEFAULT_BUFFER_SIZE - pos2); 933 } while (count2 == 0); 934 if (count2 == EOF) { 935 return pos1 == index && input1.read() == EOF; 936 } 937 pos2 += count2; 938 } 939 if (array1[index] != array2[index]) { 940 return false; 941 } 942 } 943 } 944 } 945 946 // TODO Consider making public 947 private static boolean contentEquals(final Iterator<?> iterator1, final Iterator<?> iterator2) { 948 while (iterator1.hasNext()) { 949 if (!iterator2.hasNext()) { 950 return false; 951 } 952 if (!Objects.equals(iterator1.next(), iterator2.next())) { 953 return false; 954 } 955 } 956 return !iterator2.hasNext(); 957 } 958 959 /** 960 * Compares the contents of two Readers to determine if they are equal or not. 961 * <p> 962 * This method buffers the input internally using {@link BufferedReader} if they are not already buffered. 963 * </p> 964 * 965 * @param input1 the first reader 966 * @param input2 the second reader 967 * @return true if the content of the readers are equal or they both don't exist, false otherwise 968 * @throws NullPointerException if either input is null 969 * @throws IOException if an I/O error occurs 970 * @since 1.1 971 */ 972 public static boolean contentEquals(final Reader input1, final Reader input2) throws IOException { 973 if (input1 == input2) { 974 return true; 975 } 976 if (input1 == null || input2 == null) { 977 return false; 978 } 979 980 // reuse one 981 final char[] array1 = getScratchCharArray(); 982 // but allocate another 983 final char[] array2 = charArray(); 984 int pos1; 985 int pos2; 986 int count1; 987 int count2; 988 while (true) { 989 pos1 = 0; 990 pos2 = 0; 991 for (int index = 0; index < DEFAULT_BUFFER_SIZE; index++) { 992 if (pos1 == index) { 993 do { 994 count1 = input1.read(array1, pos1, DEFAULT_BUFFER_SIZE - pos1); 995 } while (count1 == 0); 996 if (count1 == EOF) { 997 return pos2 == index && input2.read() == EOF; 998 } 999 pos1 += count1; 1000 } 1001 if (pos2 == index) { 1002 do { 1003 count2 = input2.read(array2, pos2, DEFAULT_BUFFER_SIZE - pos2); 1004 } while (count2 == 0); 1005 if (count2 == EOF) { 1006 return pos1 == index && input1.read() == EOF; 1007 } 1008 pos2 += count2; 1009 } 1010 if (array1[index] != array2[index]) { 1011 return false; 1012 } 1013 } 1014 } 1015 } 1016 1017 // TODO Consider making public 1018 private static boolean contentEquals(final Stream<?> stream1, final Stream<?> stream2) { 1019 if (stream1 == stream2) { 1020 return true; 1021 } 1022 if (stream1 == null || stream2 == null) { 1023 return false; 1024 } 1025 return contentEquals(stream1.iterator(), stream2.iterator()); 1026 } 1027 1028 // TODO Consider making public 1029 private static boolean contentEqualsIgnoreEOL(final BufferedReader reader1, final BufferedReader reader2) { 1030 if (reader1 == reader2) { 1031 return true; 1032 } 1033 if (reader1 == null || reader2 == null) { 1034 return false; 1035 } 1036 return contentEquals(reader1.lines(), reader2.lines()); 1037 } 1038 1039 /** 1040 * Compares the contents of two Readers to determine if they are equal or 1041 * not, ignoring EOL characters. 1042 * <p> 1043 * This method buffers the input internally using 1044 * {@link BufferedReader} if they are not already buffered. 1045 * </p> 1046 * 1047 * @param reader1 the first reader 1048 * @param reader2 the second reader 1049 * @return true if the content of the readers are equal (ignoring EOL differences), false otherwise 1050 * @throws NullPointerException if either input is null 1051 * @throws UncheckedIOException if an I/O error occurs 1052 * @since 2.2 1053 */ 1054 @SuppressWarnings("resource") 1055 public static boolean contentEqualsIgnoreEOL(final Reader reader1, final Reader reader2) throws UncheckedIOException { 1056 if (reader1 == reader2) { 1057 return true; 1058 } 1059 if (reader1 == null || reader2 == null) { 1060 return false; 1061 } 1062 return contentEqualsIgnoreEOL(toBufferedReader(reader1), toBufferedReader(reader2)); 1063 } 1064 1065 /** 1066 * Copies bytes from an {@link InputStream} to an {@link OutputStream}. 1067 * <p> 1068 * This method buffers the input internally, so there is no need to use a {@link BufferedInputStream}. 1069 * </p> 1070 * <p> 1071 * Large streams (over 2GB) will return a bytes copied value of {@code -1} after the copy has completed since 1072 * the correct number of bytes cannot be returned as an int. For large streams use the 1073 * {@link #copyLarge(InputStream, OutputStream)} method. 1074 * </p> 1075 * 1076 * @param inputStream the {@link InputStream} to read. 1077 * @param outputStream the {@link OutputStream} to write. 1078 * @return the number of bytes copied, or -1 if greater than {@link Integer#MAX_VALUE}. 1079 * @throws NullPointerException if the InputStream is {@code null}. 1080 * @throws NullPointerException if the OutputStream is {@code null}. 1081 * @throws IOException if an I/O error occurs. 1082 * @since 1.1 1083 */ 1084 public static int copy(final InputStream inputStream, final OutputStream outputStream) throws IOException { 1085 final long count = copyLarge(inputStream, outputStream); 1086 return count > Integer.MAX_VALUE ? EOF : (int) count; 1087 } 1088 1089 /** 1090 * Copies bytes from an {@link InputStream} to an {@link OutputStream} using an internal buffer of the 1091 * given size. 1092 * <p> 1093 * This method buffers the input internally, so there is no need to use a {@link BufferedInputStream}. 1094 * </p> 1095 * 1096 * @param inputStream the {@link InputStream} to read. 1097 * @param outputStream the {@link OutputStream} to write to 1098 * @param bufferSize the bufferSize used to copy from the input to the output 1099 * @return the number of bytes copied. 1100 * @throws NullPointerException if the InputStream is {@code null}. 1101 * @throws NullPointerException if the OutputStream is {@code null}. 1102 * @throws IOException if an I/O error occurs. 1103 * @since 2.5 1104 */ 1105 public static long copy(final InputStream inputStream, final OutputStream outputStream, final int bufferSize) 1106 throws IOException { 1107 return copyLarge(inputStream, outputStream, IOUtils.byteArray(bufferSize)); 1108 } 1109 1110 /** 1111 * Copies bytes from an {@link InputStream} to chars on a 1112 * {@link Writer} using the default character encoding of the platform. 1113 * <p> 1114 * This method buffers the input internally, so there is no need to use a 1115 * {@link BufferedInputStream}. 1116 * </p> 1117 * <p> 1118 * This method uses {@link InputStreamReader}. 1119 * </p> 1120 * 1121 * @param input the {@link InputStream} to read 1122 * @param writer the {@link Writer} to write to 1123 * @throws NullPointerException if the input or output is null 1124 * @throws IOException if an I/O error occurs 1125 * @since 1.1 1126 * @deprecated 2.5 use {@link #copy(InputStream, Writer, Charset)} instead 1127 */ 1128 @Deprecated 1129 public static void copy(final InputStream input, final Writer writer) 1130 throws IOException { 1131 copy(input, writer, Charset.defaultCharset()); 1132 } 1133 1134 /** 1135 * Copies bytes from an {@link InputStream} to chars on a 1136 * {@link Writer} using the specified character encoding. 1137 * <p> 1138 * This method buffers the input internally, so there is no need to use a 1139 * {@link BufferedInputStream}. 1140 * </p> 1141 * <p> 1142 * This method uses {@link InputStreamReader}. 1143 * </p> 1144 * 1145 * @param input the {@link InputStream} to read 1146 * @param writer the {@link Writer} to write to 1147 * @param inputCharset the charset to use for the input stream, null means platform default 1148 * @throws NullPointerException if the input or output is null 1149 * @throws IOException if an I/O error occurs 1150 * @since 2.3 1151 */ 1152 public static void copy(final InputStream input, final Writer writer, final Charset inputCharset) 1153 throws IOException { 1154 final InputStreamReader reader = new InputStreamReader(input, Charsets.toCharset(inputCharset)); 1155 copy(reader, writer); 1156 } 1157 1158 /** 1159 * Copies bytes from an {@link InputStream} to chars on a 1160 * {@link Writer} using the specified character encoding. 1161 * <p> 1162 * This method buffers the input internally, so there is no need to use a 1163 * {@link BufferedInputStream}. 1164 * </p> 1165 * <p> 1166 * Character encoding names can be found at 1167 * <a href="http://www.iana.org/assignments/character-sets">IANA</a>. 1168 * </p> 1169 * <p> 1170 * This method uses {@link InputStreamReader}. 1171 * </p> 1172 * 1173 * @param input the {@link InputStream} to read 1174 * @param writer the {@link Writer} to write to 1175 * @param inputCharsetName the name of the requested charset for the InputStream, null means platform default 1176 * @throws NullPointerException if the input or output is null 1177 * @throws IOException if an I/O error occurs 1178 * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io 1179 * .UnsupportedEncodingException} in version 2.2 if the 1180 * encoding is not supported. 1181 * @since 1.1 1182 */ 1183 public static void copy(final InputStream input, final Writer writer, final String inputCharsetName) 1184 throws IOException { 1185 copy(input, writer, Charsets.toCharset(inputCharsetName)); 1186 } 1187 1188 /** 1189 * Copies bytes from a {@link java.io.ByteArrayOutputStream} to a {@link QueueInputStream}. 1190 * <p> 1191 * Unlike using JDK {@link java.io.PipedInputStream} and {@link java.io.PipedOutputStream} for this, this 1192 * solution works safely in a single thread environment. 1193 * </p> 1194 * <p> 1195 * Example usage: 1196 * </p> 1197 * 1198 * <pre> 1199 * ByteArrayOutputStream outputStream = new ByteArrayOutputStream(); 1200 * outputStream.writeBytes("hello world".getBytes(StandardCharsets.UTF_8)); 1201 * 1202 * InputStream inputStream = IOUtils.copy(outputStream); 1203 * </pre> 1204 * 1205 * @param outputStream the {@link java.io.ByteArrayOutputStream} to read. 1206 * @return the {@link QueueInputStream} filled with the content of the outputStream. 1207 * @throws NullPointerException if the {@link java.io.ByteArrayOutputStream} is {@code null}. 1208 * @throws IOException if an I/O error occurs. 1209 * @since 2.12 1210 */ 1211 @SuppressWarnings("resource") // streams are closed by the caller. 1212 public static QueueInputStream copy(final java.io.ByteArrayOutputStream outputStream) throws IOException { 1213 Objects.requireNonNull(outputStream, "outputStream"); 1214 final QueueInputStream in = new QueueInputStream(); 1215 outputStream.writeTo(in.newQueueOutputStream()); 1216 return in; 1217 } 1218 1219 /** 1220 * Copies chars from a {@link Reader} to a {@link Appendable}. 1221 * <p> 1222 * This method buffers the input internally, so there is no need to use a 1223 * {@link BufferedReader}. 1224 * </p> 1225 * <p> 1226 * Large streams (over 2GB) will return a chars copied value of 1227 * {@code -1} after the copy has completed since the correct 1228 * number of chars cannot be returned as an int. For large streams 1229 * use the {@link #copyLarge(Reader, Writer)} method. 1230 * </p> 1231 * 1232 * @param reader the {@link Reader} to read 1233 * @param output the {@link Appendable} to write to 1234 * @return the number of characters copied, or -1 if > Integer.MAX_VALUE 1235 * @throws NullPointerException if the input or output is null 1236 * @throws IOException if an I/O error occurs 1237 * @since 2.7 1238 */ 1239 public static long copy(final Reader reader, final Appendable output) throws IOException { 1240 return copy(reader, output, CharBuffer.allocate(DEFAULT_BUFFER_SIZE)); 1241 } 1242 1243 /** 1244 * Copies chars from a {@link Reader} to an {@link Appendable}. 1245 * <p> 1246 * This method uses the provided buffer, so there is no need to use a 1247 * {@link BufferedReader}. 1248 * </p> 1249 * 1250 * @param reader the {@link Reader} to read 1251 * @param output the {@link Appendable} to write to 1252 * @param buffer the buffer to be used for the copy 1253 * @return the number of characters copied 1254 * @throws NullPointerException if the input or output is null 1255 * @throws IOException if an I/O error occurs 1256 * @since 2.7 1257 */ 1258 public static long copy(final Reader reader, final Appendable output, final CharBuffer buffer) throws IOException { 1259 long count = 0; 1260 int n; 1261 while (EOF != (n = reader.read(buffer))) { 1262 buffer.flip(); 1263 output.append(buffer, 0, n); 1264 count += n; 1265 } 1266 return count; 1267 } 1268 1269 /** 1270 * Copies chars from a {@link Reader} to bytes on an 1271 * {@link OutputStream} using the default character encoding of the 1272 * platform, and calling flush. 1273 * <p> 1274 * This method buffers the input internally, so there is no need to use a 1275 * {@link BufferedReader}. 1276 * </p> 1277 * <p> 1278 * Due to the implementation of OutputStreamWriter, this method performs a 1279 * flush. 1280 * </p> 1281 * <p> 1282 * This method uses {@link OutputStreamWriter}. 1283 * </p> 1284 * 1285 * @param reader the {@link Reader} to read 1286 * @param output the {@link OutputStream} to write to 1287 * @throws NullPointerException if the input or output is null 1288 * @throws IOException if an I/O error occurs 1289 * @since 1.1 1290 * @deprecated 2.5 use {@link #copy(Reader, OutputStream, Charset)} instead 1291 */ 1292 @Deprecated 1293 public static void copy(final Reader reader, final OutputStream output) 1294 throws IOException { 1295 copy(reader, output, Charset.defaultCharset()); 1296 } 1297 1298 /** 1299 * Copies chars from a {@link Reader} to bytes on an 1300 * {@link OutputStream} using the specified character encoding, and 1301 * calling flush. 1302 * <p> 1303 * This method buffers the input internally, so there is no need to use a 1304 * {@link BufferedReader}. 1305 * </p> 1306 * <p> 1307 * Due to the implementation of OutputStreamWriter, this method performs a 1308 * flush. 1309 * </p> 1310 * <p> 1311 * This method uses {@link OutputStreamWriter}. 1312 * </p> 1313 * 1314 * @param reader the {@link Reader} to read 1315 * @param output the {@link OutputStream} to write to 1316 * @param outputCharset the charset to use for the OutputStream, null means platform default 1317 * @throws NullPointerException if the input or output is null 1318 * @throws IOException if an I/O error occurs 1319 * @since 2.3 1320 */ 1321 public static void copy(final Reader reader, final OutputStream output, final Charset outputCharset) 1322 throws IOException { 1323 final OutputStreamWriter writer = new OutputStreamWriter(output, Charsets.toCharset(outputCharset)); 1324 copy(reader, writer); 1325 // XXX Unless anyone is planning on rewriting OutputStreamWriter, 1326 // we have to flush here. 1327 writer.flush(); 1328 } 1329 1330 /** 1331 * Copies chars from a {@link Reader} to bytes on an 1332 * {@link OutputStream} using the specified character encoding, and 1333 * calling flush. 1334 * <p> 1335 * This method buffers the input internally, so there is no need to use a 1336 * {@link BufferedReader}. 1337 * </p> 1338 * <p> 1339 * Character encoding names can be found at 1340 * <a href="http://www.iana.org/assignments/character-sets">IANA</a>. 1341 * </p> 1342 * <p> 1343 * Due to the implementation of OutputStreamWriter, this method performs a 1344 * flush. 1345 * </p> 1346 * <p> 1347 * This method uses {@link OutputStreamWriter}. 1348 * </p> 1349 * 1350 * @param reader the {@link Reader} to read 1351 * @param output the {@link OutputStream} to write to 1352 * @param outputCharsetName the name of the requested charset for the OutputStream, null means platform default 1353 * @throws NullPointerException if the input or output is null 1354 * @throws IOException if an I/O error occurs 1355 * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io 1356 * .UnsupportedEncodingException} in version 2.2 if the 1357 * encoding is not supported. 1358 * @since 1.1 1359 */ 1360 public static void copy(final Reader reader, final OutputStream output, final String outputCharsetName) 1361 throws IOException { 1362 copy(reader, output, Charsets.toCharset(outputCharsetName)); 1363 } 1364 1365 /** 1366 * Copies chars from a {@link Reader} to a {@link Writer}. 1367 * <p> 1368 * This method buffers the input internally, so there is no need to use a 1369 * {@link BufferedReader}. 1370 * </p> 1371 * <p> 1372 * Large streams (over 2GB) will return a chars copied value of 1373 * {@code -1} after the copy has completed since the correct 1374 * number of chars cannot be returned as an int. For large streams 1375 * use the {@link #copyLarge(Reader, Writer)} method. 1376 * </p> 1377 * 1378 * @param reader the {@link Reader} to read. 1379 * @param writer the {@link Writer} to write. 1380 * @return the number of characters copied, or -1 if > Integer.MAX_VALUE 1381 * @throws NullPointerException if the input or output is null 1382 * @throws IOException if an I/O error occurs 1383 * @since 1.1 1384 */ 1385 public static int copy(final Reader reader, final Writer writer) throws IOException { 1386 final long count = copyLarge(reader, writer); 1387 if (count > Integer.MAX_VALUE) { 1388 return EOF; 1389 } 1390 return (int) count; 1391 } 1392 1393 /** 1394 * Copies bytes from a {@link URL} to an {@link OutputStream}. 1395 * <p> 1396 * This method buffers the input internally, so there is no need to use a {@link BufferedInputStream}. 1397 * </p> 1398 * <p> 1399 * The buffer size is given by {@link #DEFAULT_BUFFER_SIZE}. 1400 * </p> 1401 * 1402 * @param url the {@link URL} to read. 1403 * @param file the {@link OutputStream} to write. 1404 * @return the number of bytes copied. 1405 * @throws NullPointerException if the URL is {@code null}. 1406 * @throws NullPointerException if the OutputStream is {@code null}. 1407 * @throws IOException if an I/O error occurs. 1408 * @since 2.9.0 1409 */ 1410 public static long copy(final URL url, final File file) throws IOException { 1411 try (OutputStream outputStream = Files.newOutputStream(Objects.requireNonNull(file, "file").toPath())) { 1412 return copy(url, outputStream); 1413 } 1414 } 1415 1416 /** 1417 * Copies bytes from a {@link URL} to an {@link OutputStream}. 1418 * <p> 1419 * This method buffers the input internally, so there is no need to use a {@link BufferedInputStream}. 1420 * </p> 1421 * <p> 1422 * The buffer size is given by {@link #DEFAULT_BUFFER_SIZE}. 1423 * </p> 1424 * 1425 * @param url the {@link URL} to read. 1426 * @param outputStream the {@link OutputStream} to write. 1427 * @return the number of bytes copied. 1428 * @throws NullPointerException if the URL is {@code null}. 1429 * @throws NullPointerException if the OutputStream is {@code null}. 1430 * @throws IOException if an I/O error occurs. 1431 * @since 2.9.0 1432 */ 1433 public static long copy(final URL url, final OutputStream outputStream) throws IOException { 1434 try (InputStream inputStream = Objects.requireNonNull(url, "url").openStream()) { 1435 return copyLarge(inputStream, outputStream); 1436 } 1437 } 1438 1439 /** 1440 * Copies bytes from a large (over 2GB) {@link InputStream} to an 1441 * {@link OutputStream}. 1442 * <p> 1443 * This method buffers the input internally, so there is no need to use a 1444 * {@link BufferedInputStream}. 1445 * </p> 1446 * <p> 1447 * The buffer size is given by {@link #DEFAULT_BUFFER_SIZE}. 1448 * </p> 1449 * 1450 * @param inputStream the {@link InputStream} to read. 1451 * @param outputStream the {@link OutputStream} to write. 1452 * @return the number of bytes copied. 1453 * @throws NullPointerException if the InputStream is {@code null}. 1454 * @throws NullPointerException if the OutputStream is {@code null}. 1455 * @throws IOException if an I/O error occurs. 1456 * @since 1.3 1457 */ 1458 public static long copyLarge(final InputStream inputStream, final OutputStream outputStream) 1459 throws IOException { 1460 return copy(inputStream, outputStream, DEFAULT_BUFFER_SIZE); 1461 } 1462 1463 /** 1464 * Copies bytes from a large (over 2GB) {@link InputStream} to an 1465 * {@link OutputStream}. 1466 * <p> 1467 * This method uses the provided buffer, so there is no need to use a 1468 * {@link BufferedInputStream}. 1469 * </p> 1470 * 1471 * @param inputStream the {@link InputStream} to read. 1472 * @param outputStream the {@link OutputStream} to write. 1473 * @param buffer the buffer to use for the copy 1474 * @return the number of bytes copied. 1475 * @throws NullPointerException if the InputStream is {@code null}. 1476 * @throws NullPointerException if the OutputStream is {@code null}. 1477 * @throws IOException if an I/O error occurs. 1478 * @since 2.2 1479 */ 1480 @SuppressWarnings("resource") // streams are closed by the caller. 1481 public static long copyLarge(final InputStream inputStream, final OutputStream outputStream, final byte[] buffer) 1482 throws IOException { 1483 Objects.requireNonNull(inputStream, "inputStream"); 1484 Objects.requireNonNull(outputStream, "outputStream"); 1485 long count = 0; 1486 int n; 1487 while (EOF != (n = inputStream.read(buffer))) { 1488 outputStream.write(buffer, 0, n); 1489 count += n; 1490 } 1491 return count; 1492 } 1493 1494 /** 1495 * Copies some or all bytes from a large (over 2GB) {@link InputStream} to an 1496 * {@link OutputStream}, optionally skipping input bytes. 1497 * <p> 1498 * This method buffers the input internally, so there is no need to use a 1499 * {@link BufferedInputStream}. 1500 * </p> 1501 * <p> 1502 * Note that the implementation uses {@link #skip(InputStream, long)}. 1503 * This means that the method may be considerably less efficient than using the actual skip implementation, 1504 * this is done to guarantee that the correct number of characters are skipped. 1505 * </p> 1506 * The buffer size is given by {@link #DEFAULT_BUFFER_SIZE}. 1507 * 1508 * @param input the {@link InputStream} to read 1509 * @param output the {@link OutputStream} to write to 1510 * @param inputOffset : number of bytes to skip from input before copying 1511 * -ve values are ignored 1512 * @param length : number of bytes to copy. -ve means all 1513 * @return the number of bytes copied 1514 * @throws NullPointerException if the input or output is null 1515 * @throws IOException if an I/O error occurs 1516 * @since 2.2 1517 */ 1518 public static long copyLarge(final InputStream input, final OutputStream output, final long inputOffset, 1519 final long length) throws IOException { 1520 return copyLarge(input, output, inputOffset, length, getScratchByteArray()); 1521 } 1522 1523 /** 1524 * Copies some or all bytes from a large (over 2GB) {@link InputStream} to an 1525 * {@link OutputStream}, optionally skipping input bytes. 1526 * <p> 1527 * This method uses the provided buffer, so there is no need to use a 1528 * {@link BufferedInputStream}. 1529 * </p> 1530 * <p> 1531 * Note that the implementation uses {@link #skip(InputStream, long)}. 1532 * This means that the method may be considerably less efficient than using the actual skip implementation, 1533 * this is done to guarantee that the correct number of characters are skipped. 1534 * </p> 1535 * 1536 * @param input the {@link InputStream} to read 1537 * @param output the {@link OutputStream} to write to 1538 * @param inputOffset : number of bytes to skip from input before copying 1539 * -ve values are ignored 1540 * @param length : number of bytes to copy. -ve means all 1541 * @param buffer the buffer to use for the copy 1542 * @return the number of bytes copied 1543 * @throws NullPointerException if the input or output is null 1544 * @throws IOException if an I/O error occurs 1545 * @since 2.2 1546 */ 1547 public static long copyLarge(final InputStream input, final OutputStream output, 1548 final long inputOffset, final long length, final byte[] buffer) throws IOException { 1549 if (inputOffset > 0) { 1550 skipFully(input, inputOffset); 1551 } 1552 if (length == 0) { 1553 return 0; 1554 } 1555 final int bufferLength = buffer.length; 1556 int bytesToRead = bufferLength; 1557 if (length > 0 && length < bufferLength) { 1558 bytesToRead = (int) length; 1559 } 1560 int read; 1561 long totalRead = 0; 1562 while (bytesToRead > 0 && EOF != (read = input.read(buffer, 0, bytesToRead))) { 1563 output.write(buffer, 0, read); 1564 totalRead += read; 1565 if (length > 0) { // only adjust length if not reading to the end 1566 // Note the cast must work because buffer.length is an integer 1567 bytesToRead = (int) Math.min(length - totalRead, bufferLength); 1568 } 1569 } 1570 return totalRead; 1571 } 1572 1573 /** 1574 * Copies chars from a large (over 2GB) {@link Reader} to a {@link Writer}. 1575 * <p> 1576 * This method buffers the input internally, so there is no need to use a 1577 * {@link BufferedReader}. 1578 * </p> 1579 * <p> 1580 * The buffer size is given by {@link #DEFAULT_BUFFER_SIZE}. 1581 * </p> 1582 * 1583 * @param reader the {@link Reader} to source. 1584 * @param writer the {@link Writer} to target. 1585 * @return the number of characters copied 1586 * @throws NullPointerException if the input or output is null 1587 * @throws IOException if an I/O error occurs 1588 * @since 1.3 1589 */ 1590 public static long copyLarge(final Reader reader, final Writer writer) throws IOException { 1591 return copyLarge(reader, writer, getScratchCharArray()); 1592 } 1593 1594 /** 1595 * Copies chars from a large (over 2GB) {@link Reader} to a {@link Writer}. 1596 * <p> 1597 * This method uses the provided buffer, so there is no need to use a 1598 * {@link BufferedReader}. 1599 * </p> 1600 * 1601 * @param reader the {@link Reader} to source. 1602 * @param writer the {@link Writer} to target. 1603 * @param buffer the buffer to be used for the copy 1604 * @return the number of characters copied 1605 * @throws NullPointerException if the input or output is null 1606 * @throws IOException if an I/O error occurs 1607 * @since 2.2 1608 */ 1609 public static long copyLarge(final Reader reader, final Writer writer, final char[] buffer) throws IOException { 1610 long count = 0; 1611 int n; 1612 while (EOF != (n = reader.read(buffer))) { 1613 writer.write(buffer, 0, n); 1614 count += n; 1615 } 1616 return count; 1617 } 1618 1619 /** 1620 * Copies some or all chars from a large (over 2GB) {@link InputStream} to an 1621 * {@link OutputStream}, optionally skipping input chars. 1622 * <p> 1623 * This method buffers the input internally, so there is no need to use a 1624 * {@link BufferedReader}. 1625 * </p> 1626 * <p> 1627 * The buffer size is given by {@link #DEFAULT_BUFFER_SIZE}. 1628 * </p> 1629 * 1630 * @param reader the {@link Reader} to read 1631 * @param writer the {@link Writer} to write to 1632 * @param inputOffset : number of chars to skip from input before copying 1633 * -ve values are ignored 1634 * @param length : number of chars to copy. -ve means all 1635 * @return the number of chars copied 1636 * @throws NullPointerException if the input or output is null 1637 * @throws IOException if an I/O error occurs 1638 * @since 2.2 1639 */ 1640 public static long copyLarge(final Reader reader, final Writer writer, final long inputOffset, final long length) 1641 throws IOException { 1642 return copyLarge(reader, writer, inputOffset, length, getScratchCharArray()); 1643 } 1644 1645 /** 1646 * Copies some or all chars from a large (over 2GB) {@link InputStream} to an 1647 * {@link OutputStream}, optionally skipping input chars. 1648 * <p> 1649 * This method uses the provided buffer, so there is no need to use a 1650 * {@link BufferedReader}. 1651 * </p> 1652 * 1653 * @param reader the {@link Reader} to read 1654 * @param writer the {@link Writer} to write to 1655 * @param inputOffset : number of chars to skip from input before copying 1656 * -ve values are ignored 1657 * @param length : number of chars to copy. -ve means all 1658 * @param buffer the buffer to be used for the copy 1659 * @return the number of chars copied 1660 * @throws NullPointerException if the input or output is null 1661 * @throws IOException if an I/O error occurs 1662 * @since 2.2 1663 */ 1664 public static long copyLarge(final Reader reader, final Writer writer, final long inputOffset, final long length, 1665 final char[] buffer) 1666 throws IOException { 1667 if (inputOffset > 0) { 1668 skipFully(reader, inputOffset); 1669 } 1670 if (length == 0) { 1671 return 0; 1672 } 1673 int bytesToRead = buffer.length; 1674 if (length > 0 && length < buffer.length) { 1675 bytesToRead = (int) length; 1676 } 1677 int read; 1678 long totalRead = 0; 1679 while (bytesToRead > 0 && EOF != (read = reader.read(buffer, 0, bytesToRead))) { 1680 writer.write(buffer, 0, read); 1681 totalRead += read; 1682 if (length > 0) { // only adjust length if not reading to the end 1683 // Note the cast must work because buffer.length is an integer 1684 bytesToRead = (int) Math.min(length - totalRead, buffer.length); 1685 } 1686 } 1687 return totalRead; 1688 } 1689 1690 /** 1691 * Fills the given array with 0s. 1692 * 1693 * @param arr The array to fill. 1694 * @return The given array. 1695 */ 1696 private static byte[] fill0(final byte[] arr) { 1697 Arrays.fill(arr, (byte) 0); 1698 return arr; 1699 } 1700 1701 /** 1702 * Fills the given array with 0s. 1703 * 1704 * @param arr The array to fill. 1705 * @return The given array. 1706 */ 1707 private static char[] fill0(final char[] arr) { 1708 Arrays.fill(arr, (char) 0); 1709 return arr; 1710 } 1711 1712 /** 1713 * Gets the internal byte array buffer, intended for both reading and writing. 1714 * 1715 * @return the internal byte array buffer, intended for both reading and writing. 1716 */ 1717 static byte[] getScratchByteArray() { 1718 return fill0(SCRATCH_BYTE_BUFFER_RW.get()); 1719 } 1720 1721 /** 1722 * Gets the internal byte array intended for write only operations. 1723 * 1724 * @return the internal byte array intended for write only operations. 1725 */ 1726 static byte[] getScratchByteArrayWriteOnly() { 1727 return fill0(SCRATCH_BYTE_BUFFER_WO); 1728 } 1729 1730 /** 1731 * Gets the char byte array buffer, intended for both reading and writing. 1732 * 1733 * @return the char byte array buffer, intended for both reading and writing. 1734 */ 1735 static char[] getScratchCharArray() { 1736 return fill0(SCRATCH_CHAR_BUFFER_RW.get()); 1737 } 1738 1739 /** 1740 * Gets the internal char array intended for write only operations. 1741 * 1742 * @return the internal char array intended for write only operations. 1743 */ 1744 static char[] getScratchCharArrayWriteOnly() { 1745 return fill0(SCRATCH_CHAR_BUFFER_WO); 1746 } 1747 1748 /** 1749 * Returns the length of the given array in a null-safe manner. 1750 * 1751 * @param array an array or null 1752 * @return the array length -- or 0 if the given array is null. 1753 * @since 2.7 1754 */ 1755 public static int length(final byte[] array) { 1756 return array == null ? 0 : array.length; 1757 } 1758 1759 /** 1760 * Returns the length of the given array in a null-safe manner. 1761 * 1762 * @param array an array or null 1763 * @return the array length -- or 0 if the given array is null. 1764 * @since 2.7 1765 */ 1766 public static int length(final char[] array) { 1767 return array == null ? 0 : array.length; 1768 } 1769 1770 /** 1771 * Returns the length of the given CharSequence in a null-safe manner. 1772 * 1773 * @param csq a CharSequence or null 1774 * @return the CharSequence length -- or 0 if the given CharSequence is null. 1775 * @since 2.7 1776 */ 1777 public static int length(final CharSequence csq) { 1778 return csq == null ? 0 : csq.length(); 1779 } 1780 1781 /** 1782 * Returns the length of the given array in a null-safe manner. 1783 * 1784 * @param array an array or null 1785 * @return the array length -- or 0 if the given array is null. 1786 * @since 2.7 1787 */ 1788 public static int length(final Object[] array) { 1789 return array == null ? 0 : array.length; 1790 } 1791 1792 /** 1793 * Returns an Iterator for the lines in an {@link InputStream}, using 1794 * the character encoding specified (or default encoding if null). 1795 * <p> 1796 * {@link LineIterator} holds a reference to the open 1797 * {@link InputStream} specified here. When you have finished with 1798 * the iterator you should close the stream to free internal resources. 1799 * This can be done by using a try-with-resources block, closing the stream directly, or by calling 1800 * {@link LineIterator#close()}. 1801 * </p> 1802 * <p> 1803 * The recommended usage pattern is: 1804 * </p> 1805 * <pre> 1806 * try { 1807 * LineIterator it = IOUtils.lineIterator(stream, charset); 1808 * while (it.hasNext()) { 1809 * String line = it.nextLine(); 1810 * /// do something with line 1811 * } 1812 * } finally { 1813 * IOUtils.closeQuietly(stream); 1814 * } 1815 * </pre> 1816 * 1817 * @param input the {@link InputStream} to read, not null 1818 * @param charset the charset to use, null means platform default 1819 * @return an Iterator of the lines in the reader, never null 1820 * @throws IllegalArgumentException if the input is null 1821 * @since 2.3 1822 */ 1823 public static LineIterator lineIterator(final InputStream input, final Charset charset) { 1824 return new LineIterator(new InputStreamReader(input, Charsets.toCharset(charset))); 1825 } 1826 1827 /** 1828 * Returns an Iterator for the lines in an {@link InputStream}, using 1829 * the character encoding specified (or default encoding if null). 1830 * <p> 1831 * {@link LineIterator} holds a reference to the open 1832 * {@link InputStream} specified here. When you have finished with 1833 * the iterator you should close the stream to free internal resources. 1834 * This can be done by using a try-with-resources block, closing the stream directly, or by calling 1835 * {@link LineIterator#close()}. 1836 * </p> 1837 * <p> 1838 * The recommended usage pattern is: 1839 * </p> 1840 * <pre> 1841 * try { 1842 * LineIterator it = IOUtils.lineIterator(stream, StandardCharsets.UTF_8.name()); 1843 * while (it.hasNext()) { 1844 * String line = it.nextLine(); 1845 * /// do something with line 1846 * } 1847 * } finally { 1848 * IOUtils.closeQuietly(stream); 1849 * } 1850 * </pre> 1851 * 1852 * @param input the {@link InputStream} to read, not null 1853 * @param charsetName the encoding to use, null means platform default 1854 * @return an Iterator of the lines in the reader, never null 1855 * @throws IllegalArgumentException if the input is null 1856 * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io 1857 * .UnsupportedEncodingException} in version 2.2 if the 1858 * encoding is not supported. 1859 * @since 1.2 1860 */ 1861 public static LineIterator lineIterator(final InputStream input, final String charsetName) { 1862 return lineIterator(input, Charsets.toCharset(charsetName)); 1863 } 1864 1865 /** 1866 * Returns an Iterator for the lines in a {@link Reader}. 1867 * <p> 1868 * {@link LineIterator} holds a reference to the open 1869 * {@link Reader} specified here. When you have finished with the 1870 * iterator you should close the reader to free internal resources. 1871 * This can be done by using a try-with-resources block, closing the reader directly, or by calling 1872 * {@link LineIterator#close()}. 1873 * </p> 1874 * <p> 1875 * The recommended usage pattern is: 1876 * </p> 1877 * <pre> 1878 * try { 1879 * LineIterator it = IOUtils.lineIterator(reader); 1880 * while (it.hasNext()) { 1881 * String line = it.nextLine(); 1882 * /// do something with line 1883 * } 1884 * } finally { 1885 * IOUtils.closeQuietly(reader); 1886 * } 1887 * </pre> 1888 * 1889 * @param reader the {@link Reader} to read, not null 1890 * @return an Iterator of the lines in the reader, never null 1891 * @throws NullPointerException if the reader is null 1892 * @since 1.2 1893 */ 1894 public static LineIterator lineIterator(final Reader reader) { 1895 return new LineIterator(reader); 1896 } 1897 1898 /** 1899 * Reads bytes from an input stream. 1900 * This implementation guarantees that it will read as many bytes 1901 * as possible before giving up; this may not always be the case for 1902 * subclasses of {@link InputStream}. 1903 * 1904 * @param input where to read input from 1905 * @param buffer destination 1906 * @return actual length read; may be less than requested if EOF was reached 1907 * @throws IOException if a read error occurs 1908 * @since 2.2 1909 */ 1910 public static int read(final InputStream input, final byte[] buffer) throws IOException { 1911 return read(input, buffer, 0, buffer.length); 1912 } 1913 1914 /** 1915 * Reads bytes from an input stream. 1916 * This implementation guarantees that it will read as many bytes 1917 * as possible before giving up; this may not always be the case for 1918 * subclasses of {@link InputStream}. 1919 * 1920 * @param input where to read input 1921 * @param buffer destination 1922 * @param offset initial offset into buffer 1923 * @param length length to read, must be >= 0 1924 * @return actual length read; may be less than requested if EOF was reached 1925 * @throws IllegalArgumentException if length is negative 1926 * @throws IOException if a read error occurs 1927 * @since 2.2 1928 */ 1929 public static int read(final InputStream input, final byte[] buffer, final int offset, final int length) 1930 throws IOException { 1931 if (length == 0) { 1932 return 0; 1933 } 1934 return read(input::read, buffer, offset, length); 1935 } 1936 1937 /** 1938 * Reads bytes from an input. This implementation guarantees that it will read as many bytes as possible before giving up; this may not always be the case 1939 * for subclasses of {@link InputStream}. 1940 * 1941 * @param input How to read input 1942 * @param buffer destination 1943 * @param offset initial offset into buffer 1944 * @param length length to read, must be >= 0 1945 * @return actual length read; may be less than requested if EOF was reached 1946 * @throws IllegalArgumentException if length is negative 1947 * @throws IOException if a read error occurs 1948 * @since 2.2 1949 */ 1950 static int read(final IOTriFunction<byte[], Integer, Integer, Integer> input, final byte[] buffer, final int offset, final int length) 1951 throws IOException { 1952 if (length < 0) { 1953 throw new IllegalArgumentException("Length must not be negative: " + length); 1954 } 1955 int remaining = length; 1956 while (remaining > 0) { 1957 final int location = length - remaining; 1958 final int count = input.apply(buffer, offset + location, remaining); 1959 if (EOF == count) { 1960 break; 1961 } 1962 remaining -= count; 1963 } 1964 return length - remaining; 1965 } 1966 1967 /** 1968 * Reads bytes from a ReadableByteChannel. 1969 * <p> 1970 * This implementation guarantees that it will read as many bytes 1971 * as possible before giving up; this may not always be the case for 1972 * subclasses of {@link ReadableByteChannel}. 1973 * </p> 1974 * 1975 * @param input the byte channel to read 1976 * @param buffer byte buffer destination 1977 * @return the actual length read; may be less than requested if EOF was reached 1978 * @throws IOException if a read error occurs 1979 * @since 2.5 1980 */ 1981 public static int read(final ReadableByteChannel input, final ByteBuffer buffer) throws IOException { 1982 final int length = buffer.remaining(); 1983 while (buffer.remaining() > 0) { 1984 final int count = input.read(buffer); 1985 if (EOF == count) { // EOF 1986 break; 1987 } 1988 } 1989 return length - buffer.remaining(); 1990 } 1991 1992 /** 1993 * Reads characters from an input character stream. 1994 * This implementation guarantees that it will read as many characters 1995 * as possible before giving up; this may not always be the case for 1996 * subclasses of {@link Reader}. 1997 * 1998 * @param reader where to read input from 1999 * @param buffer destination 2000 * @return actual length read; may be less than requested if EOF was reached 2001 * @throws IOException if a read error occurs 2002 * @since 2.2 2003 */ 2004 public static int read(final Reader reader, final char[] buffer) throws IOException { 2005 return read(reader, buffer, 0, buffer.length); 2006 } 2007 2008 /** 2009 * Reads characters from an input character stream. 2010 * This implementation guarantees that it will read as many characters 2011 * as possible before giving up; this may not always be the case for 2012 * subclasses of {@link Reader}. 2013 * 2014 * @param reader where to read input from 2015 * @param buffer destination 2016 * @param offset initial offset into buffer 2017 * @param length length to read, must be >= 0 2018 * @return actual length read; may be less than requested if EOF was reached 2019 * @throws IllegalArgumentException if length is negative 2020 * @throws IOException if a read error occurs 2021 * @since 2.2 2022 */ 2023 public static int read(final Reader reader, final char[] buffer, final int offset, final int length) 2024 throws IOException { 2025 if (length < 0) { 2026 throw new IllegalArgumentException("Length must not be negative: " + length); 2027 } 2028 int remaining = length; 2029 while (remaining > 0) { 2030 final int location = length - remaining; 2031 final int count = reader.read(buffer, offset + location, remaining); 2032 if (EOF == count) { // EOF 2033 break; 2034 } 2035 remaining -= count; 2036 } 2037 return length - remaining; 2038 } 2039 2040 /** 2041 * Reads the requested number of bytes or fail if there are not enough left. 2042 * <p> 2043 * This allows for the possibility that {@link InputStream#read(byte[], int, int)} may 2044 * not read as many bytes as requested (most likely because of reaching EOF). 2045 * </p> 2046 * 2047 * @param input where to read input from 2048 * @param buffer destination 2049 * 2050 * @throws IOException if there is a problem reading the file 2051 * @throws IllegalArgumentException if length is negative 2052 * @throws EOFException if the number of bytes read was incorrect 2053 * @since 2.2 2054 */ 2055 public static void readFully(final InputStream input, final byte[] buffer) throws IOException { 2056 readFully(input, buffer, 0, buffer.length); 2057 } 2058 2059 /** 2060 * Reads the requested number of bytes or fail if there are not enough left. 2061 * <p> 2062 * This allows for the possibility that {@link InputStream#read(byte[], int, int)} may 2063 * not read as many bytes as requested (most likely because of reaching EOF). 2064 * </p> 2065 * 2066 * @param input where to read input from 2067 * @param buffer destination 2068 * @param offset initial offset into buffer 2069 * @param length length to read, must be >= 0 2070 * 2071 * @throws IOException if there is a problem reading the file 2072 * @throws IllegalArgumentException if length is negative 2073 * @throws EOFException if the number of bytes read was incorrect 2074 * @since 2.2 2075 */ 2076 public static void readFully(final InputStream input, final byte[] buffer, final int offset, final int length) 2077 throws IOException { 2078 final int actual = read(input, buffer, offset, length); 2079 if (actual != length) { 2080 throw new EOFException("Length to read: " + length + " actual: " + actual); 2081 } 2082 } 2083 2084 /** 2085 * Reads the requested number of bytes or fail if there are not enough left. 2086 * <p> 2087 * This allows for the possibility that {@link InputStream#read(byte[], int, int)} may 2088 * not read as many bytes as requested (most likely because of reaching EOF). 2089 * </p> 2090 * 2091 * @param input where to read input from 2092 * @param length length to read, must be >= 0 2093 * @return the bytes read from input 2094 * @throws IOException if there is a problem reading the file 2095 * @throws IllegalArgumentException if length is negative 2096 * @throws EOFException if the number of bytes read was incorrect 2097 * @since 2.5 2098 */ 2099 public static byte[] readFully(final InputStream input, final int length) throws IOException { 2100 final byte[] buffer = byteArray(length); 2101 readFully(input, buffer, 0, buffer.length); 2102 return buffer; 2103 } 2104 2105 /** 2106 * Reads the requested number of bytes or fail if there are not enough left. 2107 * <p> 2108 * This allows for the possibility that {@link ReadableByteChannel#read(ByteBuffer)} may 2109 * not read as many bytes as requested (most likely because of reaching EOF). 2110 * </p> 2111 * 2112 * @param input the byte channel to read 2113 * @param buffer byte buffer destination 2114 * @throws IOException if there is a problem reading the file 2115 * @throws EOFException if the number of bytes read was incorrect 2116 * @since 2.5 2117 */ 2118 public static void readFully(final ReadableByteChannel input, final ByteBuffer buffer) throws IOException { 2119 final int expected = buffer.remaining(); 2120 final int actual = read(input, buffer); 2121 if (actual != expected) { 2122 throw new EOFException("Length to read: " + expected + " actual: " + actual); 2123 } 2124 } 2125 2126 /** 2127 * Reads the requested number of characters or fail if there are not enough left. 2128 * <p> 2129 * This allows for the possibility that {@link Reader#read(char[], int, int)} may 2130 * not read as many characters as requested (most likely because of reaching EOF). 2131 * </p> 2132 * 2133 * @param reader where to read input from 2134 * @param buffer destination 2135 * @throws IOException if there is a problem reading the file 2136 * @throws IllegalArgumentException if length is negative 2137 * @throws EOFException if the number of characters read was incorrect 2138 * @since 2.2 2139 */ 2140 public static void readFully(final Reader reader, final char[] buffer) throws IOException { 2141 readFully(reader, buffer, 0, buffer.length); 2142 } 2143 2144 /** 2145 * Reads the requested number of characters or fail if there are not enough left. 2146 * <p> 2147 * This allows for the possibility that {@link Reader#read(char[], int, int)} may 2148 * not read as many characters as requested (most likely because of reaching EOF). 2149 * </p> 2150 * 2151 * @param reader where to read input from 2152 * @param buffer destination 2153 * @param offset initial offset into buffer 2154 * @param length length to read, must be >= 0 2155 * @throws IOException if there is a problem reading the file 2156 * @throws IllegalArgumentException if length is negative 2157 * @throws EOFException if the number of characters read was incorrect 2158 * @since 2.2 2159 */ 2160 public static void readFully(final Reader reader, final char[] buffer, final int offset, final int length) 2161 throws IOException { 2162 final int actual = read(reader, buffer, offset, length); 2163 if (actual != length) { 2164 throw new EOFException("Length to read: " + length + " actual: " + actual); 2165 } 2166 } 2167 2168 /** 2169 * Gets the contents of an {@link InputStream} as a list of Strings, 2170 * one entry per line, using the default character encoding of the platform. 2171 * <p> 2172 * This method buffers the input internally, so there is no need to use a 2173 * {@link BufferedInputStream}. 2174 * </p> 2175 * 2176 * @param input the {@link InputStream} to read, not null 2177 * @return the list of Strings, never null 2178 * @throws NullPointerException if the input is null 2179 * @throws UncheckedIOException if an I/O error occurs 2180 * @since 1.1 2181 * @deprecated 2.5 use {@link #readLines(InputStream, Charset)} instead 2182 */ 2183 @Deprecated 2184 public static List<String> readLines(final InputStream input) throws UncheckedIOException { 2185 return readLines(input, Charset.defaultCharset()); 2186 } 2187 2188 /** 2189 * Gets the contents of an {@link InputStream} as a list of Strings, 2190 * one entry per line, using the specified character encoding. 2191 * <p> 2192 * This method buffers the input internally, so there is no need to use a 2193 * {@link BufferedInputStream}. 2194 * </p> 2195 * 2196 * @param input the {@link InputStream} to read, not null 2197 * @param charset the charset to use, null means platform default 2198 * @return the list of Strings, never null 2199 * @throws NullPointerException if the input is null 2200 * @throws UncheckedIOException if an I/O error occurs 2201 * @since 2.3 2202 */ 2203 public static List<String> readLines(final InputStream input, final Charset charset) throws UncheckedIOException { 2204 return readLines(new InputStreamReader(input, Charsets.toCharset(charset))); 2205 } 2206 2207 /** 2208 * Gets the contents of an {@link InputStream} as a list of Strings, 2209 * one entry per line, using the specified character encoding. 2210 * <p> 2211 * Character encoding names can be found at 2212 * <a href="http://www.iana.org/assignments/character-sets">IANA</a>. 2213 * </p> 2214 * <p> 2215 * This method buffers the input internally, so there is no need to use a 2216 * {@link BufferedInputStream}. 2217 * </p> 2218 * 2219 * @param input the {@link InputStream} to read, not null 2220 * @param charsetName the name of the requested charset, null means platform default 2221 * @return the list of Strings, never null 2222 * @throws NullPointerException if the input is null 2223 * @throws UncheckedIOException if an I/O error occurs 2224 * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io 2225 * .UnsupportedEncodingException} in version 2.2 if the 2226 * encoding is not supported. 2227 * @since 1.1 2228 */ 2229 public static List<String> readLines(final InputStream input, final String charsetName) throws UncheckedIOException { 2230 return readLines(input, Charsets.toCharset(charsetName)); 2231 } 2232 2233 /** 2234 * Gets the contents of a {@link Reader} as a list of Strings, 2235 * one entry per line. 2236 * <p> 2237 * This method buffers the input internally, so there is no need to use a 2238 * {@link BufferedReader}. 2239 * </p> 2240 * 2241 * @param reader the {@link Reader} to read, not null 2242 * @return the list of Strings, never null 2243 * @throws NullPointerException if the input is null 2244 * @throws UncheckedIOException if an I/O error occurs 2245 * @since 1.1 2246 */ 2247 @SuppressWarnings("resource") // reader wraps input and is the responsibility of the caller. 2248 public static List<String> readLines(final Reader reader) throws UncheckedIOException { 2249 return toBufferedReader(reader).lines().collect(Collectors.toList()); 2250 } 2251 2252 /** 2253 * Gets the contents of a resource as a byte array. 2254 * <p> 2255 * Delegates to {@link #resourceToByteArray(String, ClassLoader) resourceToByteArray(String, null)}. 2256 * </p> 2257 * 2258 * @param name The resource name. 2259 * @return the requested byte array 2260 * @throws IOException if an I/O error occurs or the resource is not found. 2261 * @see #resourceToByteArray(String, ClassLoader) 2262 * @since 2.6 2263 */ 2264 public static byte[] resourceToByteArray(final String name) throws IOException { 2265 return resourceToByteArray(name, null); 2266 } 2267 2268 /** 2269 * Gets the contents of a resource as a byte array. 2270 * <p> 2271 * Delegates to {@link #resourceToURL(String, ClassLoader)}. 2272 * </p> 2273 * 2274 * @param name The resource name. 2275 * @param classLoader the class loader that the resolution of the resource is delegated to 2276 * @return the requested byte array 2277 * @throws IOException if an I/O error occurs or the resource is not found. 2278 * @see #resourceToURL(String, ClassLoader) 2279 * @since 2.6 2280 */ 2281 public static byte[] resourceToByteArray(final String name, final ClassLoader classLoader) throws IOException { 2282 return toByteArray(resourceToURL(name, classLoader)); 2283 } 2284 2285 /** 2286 * Gets the contents of a resource as a String using the specified character encoding. 2287 * <p> 2288 * Delegates to {@link #resourceToString(String, Charset, ClassLoader) resourceToString(String, Charset, null)}. 2289 * </p> 2290 * 2291 * @param name The resource name. 2292 * @param charset the charset to use, null means platform default 2293 * @return the requested String 2294 * @throws IOException if an I/O error occurs or the resource is not found. 2295 * @see #resourceToString(String, Charset, ClassLoader) 2296 * @since 2.6 2297 */ 2298 public static String resourceToString(final String name, final Charset charset) throws IOException { 2299 return resourceToString(name, charset, null); 2300 } 2301 2302 /** 2303 * Gets the contents of a resource as a String using the specified character encoding. 2304 * <p> 2305 * Delegates to {@link #resourceToURL(String, ClassLoader)}. 2306 * </p> 2307 * 2308 * @param name The resource name. 2309 * @param charset the Charset to use, null means platform default 2310 * @param classLoader the class loader that the resolution of the resource is delegated to 2311 * @return the requested String 2312 * @throws IOException if an I/O error occurs. 2313 * @see #resourceToURL(String, ClassLoader) 2314 * @since 2.6 2315 */ 2316 public static String resourceToString(final String name, final Charset charset, final ClassLoader classLoader) throws IOException { 2317 return toString(resourceToURL(name, classLoader), charset); 2318 } 2319 2320 /** 2321 * Gets a URL pointing to the given resource. 2322 * <p> 2323 * Delegates to {@link #resourceToURL(String, ClassLoader) resourceToURL(String, null)}. 2324 * </p> 2325 * 2326 * @param name The resource name. 2327 * @return A URL object for reading the resource. 2328 * @throws IOException if the resource is not found. 2329 * @since 2.6 2330 */ 2331 public static URL resourceToURL(final String name) throws IOException { 2332 return resourceToURL(name, null); 2333 } 2334 2335 /** 2336 * Gets a URL pointing to the given resource. 2337 * <p> 2338 * If the {@code classLoader} is not null, call {@link ClassLoader#getResource(String)}, otherwise call 2339 * {@link Class#getResource(String) IOUtils.class.getResource(name)}. 2340 * </p> 2341 * 2342 * @param name The resource name. 2343 * @param classLoader Delegate to this class loader if not null 2344 * @return A URL object for reading the resource. 2345 * @throws IOException if the resource is not found. 2346 * @since 2.6 2347 */ 2348 public static URL resourceToURL(final String name, final ClassLoader classLoader) throws IOException { 2349 // What about the thread context class loader? 2350 // What about the system class loader? 2351 final URL resource = classLoader == null ? IOUtils.class.getResource(name) : classLoader.getResource(name); 2352 if (resource == null) { 2353 throw new IOException("Resource not found: " + name); 2354 } 2355 return resource; 2356 } 2357 2358 /** 2359 * Skips bytes from an input byte stream. 2360 * This implementation guarantees that it will read as many bytes 2361 * as possible before giving up; this may not always be the case for 2362 * skip() implementations in subclasses of {@link InputStream}. 2363 * <p> 2364 * Note that the implementation uses {@link InputStream#read(byte[], int, int)} rather 2365 * than delegating to {@link InputStream#skip(long)}. 2366 * This means that the method may be considerably less efficient than using the actual skip implementation, 2367 * this is done to guarantee that the correct number of bytes are skipped. 2368 * </p> 2369 * 2370 * @param input byte stream to skip 2371 * @param toSkip number of bytes to skip. 2372 * @return number of bytes actually skipped. 2373 * @throws IOException if there is a problem reading the file 2374 * @throws IllegalArgumentException if toSkip is negative 2375 * @see InputStream#skip(long) 2376 * @see <a href="https://issues.apache.org/jira/browse/IO-203">IO-203 - Add skipFully() method for InputStreams</a> 2377 * @since 2.0 2378 */ 2379 public static long skip(final InputStream input, final long toSkip) throws IOException { 2380 return skip(input, toSkip, IOUtils::getScratchByteArrayWriteOnly); 2381 } 2382 2383 /** 2384 * Skips bytes from an input byte stream. 2385 * <p> 2386 * Intended for special cases when customization of the temporary buffer is needed because, for example, a nested input stream has requirements for the 2387 * bytes read. For example, when using {@link InflaterInputStream}s from multiple threads. 2388 * </p> 2389 * <p> 2390 * This implementation guarantees that it will read as many bytes as possible before giving up; this may not always be the case for skip() implementations 2391 * in subclasses of {@link InputStream}. 2392 * </p> 2393 * <p> 2394 * Note that the implementation uses {@link InputStream#read(byte[], int, int)} rather than delegating to {@link InputStream#skip(long)}. This means that 2395 * the method may be considerably less efficient than using the actual skip implementation, this is done to guarantee that the correct number of bytes are 2396 * skipped. 2397 * </p> 2398 * 2399 * @param input byte stream to skip 2400 * @param toSkip number of bytes to skip. 2401 * @param skipBufferSupplier Supplies the buffer to use for reading. 2402 * @return number of bytes actually skipped. 2403 * @throws IOException if there is a problem reading the file 2404 * @throws IllegalArgumentException if toSkip is negative 2405 * @see InputStream#skip(long) 2406 * @see <a href="https://issues.apache.org/jira/browse/IO-203">IO-203 - Add skipFully() method for InputStreams</a> 2407 * @since 2.14.0 2408 */ 2409 public static long skip(final InputStream input, final long toSkip, final Supplier<byte[]> skipBufferSupplier) throws IOException { 2410 if (toSkip < 0) { 2411 throw new IllegalArgumentException("Skip count must be non-negative, actual: " + toSkip); 2412 } 2413 // 2414 // No need to synchronize access to SCRATCH_BYTE_BUFFER_WO: We don't care if the buffer is written multiple 2415 // times or in parallel since the data is ignored. We reuse the same buffer, if the buffer size were variable or read-write, 2416 // we would need to synch or use a thread local to ensure some other thread safety. 2417 // 2418 long remain = toSkip; 2419 while (remain > 0) { 2420 final byte[] skipBuffer = skipBufferSupplier.get(); 2421 // See https://issues.apache.org/jira/browse/IO-203 for why we use read() rather than delegating to skip() 2422 final long n = input.read(skipBuffer, 0, (int) Math.min(remain, skipBuffer.length)); 2423 if (n < 0) { // EOF 2424 break; 2425 } 2426 remain -= n; 2427 } 2428 return toSkip - remain; 2429 } 2430 2431 /** 2432 * Skips bytes from a ReadableByteChannel. 2433 * This implementation guarantees that it will read as many bytes 2434 * as possible before giving up. 2435 * 2436 * @param input ReadableByteChannel to skip 2437 * @param toSkip number of bytes to skip. 2438 * @return number of bytes actually skipped. 2439 * @throws IOException if there is a problem reading the ReadableByteChannel 2440 * @throws IllegalArgumentException if toSkip is negative 2441 * @since 2.5 2442 */ 2443 public static long skip(final ReadableByteChannel input, final long toSkip) throws IOException { 2444 if (toSkip < 0) { 2445 throw new IllegalArgumentException("Skip count must be non-negative, actual: " + toSkip); 2446 } 2447 final ByteBuffer skipByteBuffer = ByteBuffer.allocate((int) Math.min(toSkip, DEFAULT_BUFFER_SIZE)); 2448 long remain = toSkip; 2449 while (remain > 0) { 2450 skipByteBuffer.position(0); 2451 skipByteBuffer.limit((int) Math.min(remain, DEFAULT_BUFFER_SIZE)); 2452 final int n = input.read(skipByteBuffer); 2453 if (n == EOF) { 2454 break; 2455 } 2456 remain -= n; 2457 } 2458 return toSkip - remain; 2459 } 2460 2461 /** 2462 * Skips characters from an input character stream. 2463 * This implementation guarantees that it will read as many characters 2464 * as possible before giving up; this may not always be the case for 2465 * skip() implementations in subclasses of {@link Reader}. 2466 * <p> 2467 * Note that the implementation uses {@link Reader#read(char[], int, int)} rather 2468 * than delegating to {@link Reader#skip(long)}. 2469 * This means that the method may be considerably less efficient than using the actual skip implementation, 2470 * this is done to guarantee that the correct number of characters are skipped. 2471 * </p> 2472 * 2473 * @param reader character stream to skip 2474 * @param toSkip number of characters to skip. 2475 * @return number of characters actually skipped. 2476 * @throws IOException if there is a problem reading the file 2477 * @throws IllegalArgumentException if toSkip is negative 2478 * @see Reader#skip(long) 2479 * @see <a href="https://issues.apache.org/jira/browse/IO-203">IO-203 - Add skipFully() method for InputStreams</a> 2480 * @since 2.0 2481 */ 2482 public static long skip(final Reader reader, final long toSkip) throws IOException { 2483 if (toSkip < 0) { 2484 throw new IllegalArgumentException("Skip count must be non-negative, actual: " + toSkip); 2485 } 2486 long remain = toSkip; 2487 while (remain > 0) { 2488 // See https://issues.apache.org/jira/browse/IO-203 for why we use read() rather than delegating to skip() 2489 final char[] charArray = getScratchCharArrayWriteOnly(); 2490 final long n = reader.read(charArray, 0, (int) Math.min(remain, charArray.length)); 2491 if (n < 0) { // EOF 2492 break; 2493 } 2494 remain -= n; 2495 } 2496 return toSkip - remain; 2497 } 2498 2499 /** 2500 * Skips the requested number of bytes or fail if there are not enough left. 2501 * <p> 2502 * This allows for the possibility that {@link InputStream#skip(long)} may 2503 * not skip as many bytes as requested (most likely because of reaching EOF). 2504 * </p> 2505 * <p> 2506 * Note that the implementation uses {@link #skip(InputStream, long)}. 2507 * This means that the method may be considerably less efficient than using the actual skip implementation, 2508 * this is done to guarantee that the correct number of characters are skipped. 2509 * </p> 2510 * 2511 * @param input stream to skip 2512 * @param toSkip the number of bytes to skip 2513 * @throws IOException if there is a problem reading the file 2514 * @throws IllegalArgumentException if toSkip is negative 2515 * @throws EOFException if the number of bytes skipped was incorrect 2516 * @see InputStream#skip(long) 2517 * @since 2.0 2518 */ 2519 public static void skipFully(final InputStream input, final long toSkip) throws IOException { 2520 final long skipped = skip(input, toSkip, IOUtils::getScratchByteArrayWriteOnly); 2521 if (skipped != toSkip) { 2522 throw new EOFException("Bytes to skip: " + toSkip + " actual: " + skipped); 2523 } 2524 } 2525 2526 /** 2527 * Skips the requested number of bytes or fail if there are not enough left. 2528 * <p> 2529 * Intended for special cases when customization of the temporary buffer is needed because, for example, a nested input stream has requirements for the 2530 * bytes read. For example, when using {@link InflaterInputStream}s from multiple threads. 2531 * </p> 2532 * <p> 2533 * This allows for the possibility that {@link InputStream#skip(long)} may not skip as many bytes as requested (most likely because of reaching EOF). 2534 * </p> 2535 * <p> 2536 * Note that the implementation uses {@link #skip(InputStream, long)}. This means that the method may be considerably less efficient than using the actual 2537 * skip implementation, this is done to guarantee that the correct number of characters are skipped. 2538 * </p> 2539 * 2540 * @param input stream to skip 2541 * @param toSkip the number of bytes to skip 2542 * @param skipBufferSupplier Supplies the buffer to use for reading. 2543 * @throws IOException if there is a problem reading the file 2544 * @throws IllegalArgumentException if toSkip is negative 2545 * @throws EOFException if the number of bytes skipped was incorrect 2546 * @see InputStream#skip(long) 2547 * @since 2.14.0 2548 */ 2549 public static void skipFully(final InputStream input, final long toSkip, final Supplier<byte[]> skipBufferSupplier) throws IOException { 2550 if (toSkip < 0) { 2551 throw new IllegalArgumentException("Bytes to skip must not be negative: " + toSkip); 2552 } 2553 final long skipped = skip(input, toSkip, skipBufferSupplier); 2554 if (skipped != toSkip) { 2555 throw new EOFException("Bytes to skip: " + toSkip + " actual: " + skipped); 2556 } 2557 } 2558 2559 /** 2560 * Skips the requested number of bytes or fail if there are not enough left. 2561 * 2562 * @param input ReadableByteChannel to skip 2563 * @param toSkip the number of bytes to skip 2564 * @throws IOException if there is a problem reading the ReadableByteChannel 2565 * @throws IllegalArgumentException if toSkip is negative 2566 * @throws EOFException if the number of bytes skipped was incorrect 2567 * @since 2.5 2568 */ 2569 public static void skipFully(final ReadableByteChannel input, final long toSkip) throws IOException { 2570 if (toSkip < 0) { 2571 throw new IllegalArgumentException("Bytes to skip must not be negative: " + toSkip); 2572 } 2573 final long skipped = skip(input, toSkip); 2574 if (skipped != toSkip) { 2575 throw new EOFException("Bytes to skip: " + toSkip + " actual: " + skipped); 2576 } 2577 } 2578 2579 /** 2580 * Skips the requested number of characters or fail if there are not enough left. 2581 * <p> 2582 * This allows for the possibility that {@link Reader#skip(long)} may 2583 * not skip as many characters as requested (most likely because of reaching EOF). 2584 * </p> 2585 * <p> 2586 * Note that the implementation uses {@link #skip(Reader, long)}. 2587 * This means that the method may be considerably less efficient than using the actual skip implementation, 2588 * this is done to guarantee that the correct number of characters are skipped. 2589 * </p> 2590 * 2591 * @param reader stream to skip 2592 * @param toSkip the number of characters to skip 2593 * @throws IOException if there is a problem reading the file 2594 * @throws IllegalArgumentException if toSkip is negative 2595 * @throws EOFException if the number of characters skipped was incorrect 2596 * @see Reader#skip(long) 2597 * @since 2.0 2598 */ 2599 public static void skipFully(final Reader reader, final long toSkip) throws IOException { 2600 final long skipped = skip(reader, toSkip); 2601 if (skipped != toSkip) { 2602 throw new EOFException("Chars to skip: " + toSkip + " actual: " + skipped); 2603 } 2604 } 2605 2606 /** 2607 * Fetches entire contents of an {@link InputStream} and represent 2608 * same data as result InputStream. 2609 * <p> 2610 * This method is useful where, 2611 * </p> 2612 * <ul> 2613 * <li>Source InputStream is slow.</li> 2614 * <li>It has network resources associated, so we cannot keep it open for 2615 * long time.</li> 2616 * <li>It has network timeout associated.</li> 2617 * </ul> 2618 * <p> 2619 * It can be used in favor of {@link #toByteArray(InputStream)}, since it 2620 * avoids unnecessary allocation and copy of byte[].<br> 2621 * This method buffers the input internally, so there is no need to use a 2622 * {@link BufferedInputStream}. 2623 * </p> 2624 * 2625 * @param input Stream to be fully buffered. 2626 * @return A fully buffered stream. 2627 * @throws IOException if an I/O error occurs. 2628 * @since 2.0 2629 */ 2630 public static InputStream toBufferedInputStream(final InputStream input) throws IOException { 2631 return ByteArrayOutputStream.toBufferedInputStream(input); 2632 } 2633 2634 /** 2635 * Fetches entire contents of an {@link InputStream} and represent 2636 * same data as result InputStream. 2637 * <p> 2638 * This method is useful where, 2639 * </p> 2640 * <ul> 2641 * <li>Source InputStream is slow.</li> 2642 * <li>It has network resources associated, so we cannot keep it open for 2643 * long time.</li> 2644 * <li>It has network timeout associated.</li> 2645 * </ul> 2646 * <p> 2647 * It can be used in favor of {@link #toByteArray(InputStream)}, since it 2648 * avoids unnecessary allocation and copy of byte[].<br> 2649 * This method buffers the input internally, so there is no need to use a 2650 * {@link BufferedInputStream}. 2651 * </p> 2652 * 2653 * @param input Stream to be fully buffered. 2654 * @param size the initial buffer size 2655 * @return A fully buffered stream. 2656 * @throws IOException if an I/O error occurs. 2657 * @since 2.5 2658 */ 2659 public static InputStream toBufferedInputStream(final InputStream input, final int size) throws IOException { 2660 return ByteArrayOutputStream.toBufferedInputStream(input, size); 2661 } 2662 2663 /** 2664 * Returns the given reader if it is a {@link BufferedReader}, otherwise creates a BufferedReader from the given 2665 * reader. 2666 * 2667 * @param reader the reader to wrap or return (not null) 2668 * @return the given reader or a new {@link BufferedReader} for the given reader 2669 * @throws NullPointerException if the input parameter is null 2670 * @see #buffer(Reader) 2671 * @since 2.2 2672 */ 2673 public static BufferedReader toBufferedReader(final Reader reader) { 2674 return reader instanceof BufferedReader ? (BufferedReader) reader : new BufferedReader(reader); 2675 } 2676 2677 /** 2678 * Returns the given reader if it is a {@link BufferedReader}, otherwise creates a BufferedReader from the given 2679 * reader. 2680 * 2681 * @param reader the reader to wrap or return (not null) 2682 * @param size the buffer size, if a new BufferedReader is created. 2683 * @return the given reader or a new {@link BufferedReader} for the given reader 2684 * @throws NullPointerException if the input parameter is null 2685 * @see #buffer(Reader) 2686 * @since 2.5 2687 */ 2688 public static BufferedReader toBufferedReader(final Reader reader, final int size) { 2689 return reader instanceof BufferedReader ? (BufferedReader) reader : new BufferedReader(reader, size); 2690 } 2691 2692 /** 2693 * Gets the contents of an {@link InputStream} as a {@code byte[]}. 2694 * <p> 2695 * This method buffers the input internally, so there is no need to use a 2696 * {@link BufferedInputStream}. 2697 * </p> 2698 * 2699 * @param inputStream the {@link InputStream} to read. 2700 * @return the requested byte array. 2701 * @throws NullPointerException if the InputStream is {@code null}. 2702 * @throws IOException if an I/O error occurs or reading more than {@link Integer#MAX_VALUE} occurs. 2703 */ 2704 public static byte[] toByteArray(final InputStream inputStream) throws IOException { 2705 // We use a ThresholdingOutputStream to avoid reading AND writing more than Integer.MAX_VALUE. 2706 try (UnsynchronizedByteArrayOutputStream ubaOutput = UnsynchronizedByteArrayOutputStream.builder().get(); 2707 ThresholdingOutputStream thresholdOutput = new ThresholdingOutputStream(Integer.MAX_VALUE, os -> { 2708 throw new IllegalArgumentException(String.format("Cannot read more than %,d into a byte array", Integer.MAX_VALUE)); 2709 }, os -> ubaOutput)) { 2710 copy(inputStream, thresholdOutput); 2711 return ubaOutput.toByteArray(); 2712 } 2713 } 2714 2715 /** 2716 * Gets the contents of an {@link InputStream} as a {@code byte[]}. Use this method instead of 2717 * {@link #toByteArray(InputStream)} when {@link InputStream} size is known. 2718 * 2719 * @param input the {@link InputStream} to read. 2720 * @param size the size of {@link InputStream} to read, where 0 < {@code size} <= length of input stream. 2721 * @return byte [] of length {@code size}. 2722 * @throws IOException if an I/O error occurs or {@link InputStream} length is smaller than parameter {@code size}. 2723 * @throws IllegalArgumentException if {@code size} is less than zero. 2724 * @since 2.1 2725 */ 2726 public static byte[] toByteArray(final InputStream input, final int size) throws IOException { 2727 if (size == 0) { 2728 return EMPTY_BYTE_ARRAY; 2729 } 2730 return toByteArray(Objects.requireNonNull(input, "input")::read, size); 2731 } 2732 2733 /** 2734 * Gets contents of an {@link InputStream} as a {@code byte[]}. 2735 * Use this method instead of {@link #toByteArray(InputStream)} 2736 * when {@link InputStream} size is known. 2737 * <b>NOTE:</b> the method checks that the length can safely be cast to an int without truncation 2738 * before using {@link IOUtils#toByteArray(InputStream, int)} to read into the byte array. 2739 * (Arrays can have no more than Integer.MAX_VALUE entries anyway) 2740 * 2741 * @param input the {@link InputStream} to read 2742 * @param size the size of {@link InputStream} to read, where 0 < {@code size} <= min(Integer.MAX_VALUE, length of input stream). 2743 * @return byte [] the requested byte array, of length {@code size} 2744 * @throws IOException if an I/O error occurs or {@link InputStream} length is less than {@code size} 2745 * @throws IllegalArgumentException if size is less than zero or size is greater than Integer.MAX_VALUE 2746 * @see IOUtils#toByteArray(InputStream, int) 2747 * @since 2.1 2748 */ 2749 public static byte[] toByteArray(final InputStream input, final long size) throws IOException { 2750 if (size > Integer.MAX_VALUE) { 2751 throw new IllegalArgumentException("Size cannot be greater than Integer max value: " + size); 2752 } 2753 return toByteArray(input, (int) size); 2754 } 2755 2756 /** 2757 * Gets the contents of an input as a {@code byte[]}. 2758 * 2759 * @param input the input to read. 2760 * @param size the size of the input to read, where 0 < {@code size} <= length of input. 2761 * @return byte [] of length {@code size}. 2762 * @throws IOException if an I/O error occurs or input length is smaller than parameter {@code size}. 2763 * @throws IllegalArgumentException if {@code size} is less than zero. 2764 */ 2765 static byte[] toByteArray(final IOTriFunction<byte[], Integer, Integer, Integer> input, final int size) throws IOException { 2766 2767 if (size < 0) { 2768 throw new IllegalArgumentException("Size must be equal or greater than zero: " + size); 2769 } 2770 2771 if (size == 0) { 2772 return EMPTY_BYTE_ARRAY; 2773 } 2774 2775 final byte[] data = byteArray(size); 2776 int offset = 0; 2777 int read; 2778 2779 while (offset < size && (read = input.apply(data, offset, size - offset)) != EOF) { 2780 offset += read; 2781 } 2782 2783 if (offset != size) { 2784 throw new IOException("Unexpected read size, current: " + offset + ", expected: " + size); 2785 } 2786 2787 return data; 2788 } 2789 2790 /** 2791 * Gets the contents of a {@link Reader} as a {@code byte[]} 2792 * using the default character encoding of the platform. 2793 * <p> 2794 * This method buffers the input internally, so there is no need to use a 2795 * {@link BufferedReader}. 2796 * </p> 2797 * 2798 * @param reader the {@link Reader} to read 2799 * @return the requested byte array 2800 * @throws NullPointerException if the input is null 2801 * @throws IOException if an I/O error occurs 2802 * @deprecated 2.5 use {@link #toByteArray(Reader, Charset)} instead 2803 */ 2804 @Deprecated 2805 public static byte[] toByteArray(final Reader reader) throws IOException { 2806 return toByteArray(reader, Charset.defaultCharset()); 2807 } 2808 2809 /** 2810 * Gets the contents of a {@link Reader} as a {@code byte[]} 2811 * using the specified character encoding. 2812 * <p> 2813 * This method buffers the input internally, so there is no need to use a 2814 * {@link BufferedReader}. 2815 * </p> 2816 * 2817 * @param reader the {@link Reader} to read 2818 * @param charset the charset to use, null means platform default 2819 * @return the requested byte array 2820 * @throws NullPointerException if the input is null 2821 * @throws IOException if an I/O error occurs 2822 * @since 2.3 2823 */ 2824 public static byte[] toByteArray(final Reader reader, final Charset charset) throws IOException { 2825 try (ByteArrayOutputStream output = new ByteArrayOutputStream()) { 2826 copy(reader, output, charset); 2827 return output.toByteArray(); 2828 } 2829 } 2830 2831 /** 2832 * Gets the contents of a {@link Reader} as a {@code byte[]} 2833 * using the specified character encoding. 2834 * <p> 2835 * Character encoding names can be found at 2836 * <a href="http://www.iana.org/assignments/character-sets">IANA</a>. 2837 * </p> 2838 * <p> 2839 * This method buffers the input internally, so there is no need to use a 2840 * {@link BufferedReader}. 2841 * </p> 2842 * 2843 * @param reader the {@link Reader} to read 2844 * @param charsetName the name of the requested charset, null means platform default 2845 * @return the requested byte array 2846 * @throws NullPointerException if the input is null 2847 * @throws IOException if an I/O error occurs 2848 * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io 2849 * .UnsupportedEncodingException} in version 2.2 if the 2850 * encoding is not supported. 2851 * @since 1.1 2852 */ 2853 public static byte[] toByteArray(final Reader reader, final String charsetName) throws IOException { 2854 return toByteArray(reader, Charsets.toCharset(charsetName)); 2855 } 2856 2857 /** 2858 * Gets the contents of a {@link String} as a {@code byte[]} 2859 * using the default character encoding of the platform. 2860 * <p> 2861 * This is the same as {@link String#getBytes()}. 2862 * </p> 2863 * 2864 * @param input the {@link String} to convert 2865 * @return the requested byte array 2866 * @throws NullPointerException if the input is null 2867 * @deprecated 2.5 Use {@link String#getBytes()} instead 2868 */ 2869 @Deprecated 2870 public static byte[] toByteArray(final String input) { 2871 // make explicit the use of the default charset 2872 return input.getBytes(Charset.defaultCharset()); 2873 } 2874 2875 /** 2876 * Gets the contents of a {@link URI} as a {@code byte[]}. 2877 * 2878 * @param uri the {@link URI} to read 2879 * @return the requested byte array 2880 * @throws NullPointerException if the uri is null 2881 * @throws IOException if an I/O exception occurs 2882 * @since 2.4 2883 */ 2884 public static byte[] toByteArray(final URI uri) throws IOException { 2885 return toByteArray(uri.toURL()); 2886 } 2887 2888 /** 2889 * Gets the contents of a {@link URL} as a {@code byte[]}. 2890 * 2891 * @param url the {@link URL} to read 2892 * @return the requested byte array 2893 * @throws NullPointerException if the input is null 2894 * @throws IOException if an I/O exception occurs 2895 * @since 2.4 2896 */ 2897 public static byte[] toByteArray(final URL url) throws IOException { 2898 try (CloseableURLConnection urlConnection = CloseableURLConnection.open(url)) { 2899 return toByteArray(urlConnection); 2900 } 2901 } 2902 2903 /** 2904 * Gets the contents of a {@link URLConnection} as a {@code byte[]}. 2905 * 2906 * @param urlConnection the {@link URLConnection} to read. 2907 * @return the requested byte array. 2908 * @throws NullPointerException if the urlConn is null. 2909 * @throws IOException if an I/O exception occurs. 2910 * @since 2.4 2911 */ 2912 public static byte[] toByteArray(final URLConnection urlConnection) throws IOException { 2913 try (InputStream inputStream = urlConnection.getInputStream()) { 2914 return toByteArray(inputStream); 2915 } 2916 } 2917 2918 /** 2919 * Gets the contents of an {@link InputStream} as a character array 2920 * using the default character encoding of the platform. 2921 * <p> 2922 * This method buffers the input internally, so there is no need to use a 2923 * {@link BufferedInputStream}. 2924 * </p> 2925 * 2926 * @param inputStream the {@link InputStream} to read 2927 * @return the requested character array 2928 * @throws NullPointerException if the input is null 2929 * @throws IOException if an I/O error occurs 2930 * @since 1.1 2931 * @deprecated 2.5 use {@link #toCharArray(InputStream, Charset)} instead 2932 */ 2933 @Deprecated 2934 public static char[] toCharArray(final InputStream inputStream) throws IOException { 2935 return toCharArray(inputStream, Charset.defaultCharset()); 2936 } 2937 2938 /** 2939 * Gets the contents of an {@link InputStream} as a character array 2940 * using the specified character encoding. 2941 * <p> 2942 * This method buffers the input internally, so there is no need to use a 2943 * {@link BufferedInputStream}. 2944 * </p> 2945 * 2946 * @param inputStream the {@link InputStream} to read 2947 * @param charset the charset to use, null means platform default 2948 * @return the requested character array 2949 * @throws NullPointerException if the input is null 2950 * @throws IOException if an I/O error occurs 2951 * @since 2.3 2952 */ 2953 public static char[] toCharArray(final InputStream inputStream, final Charset charset) 2954 throws IOException { 2955 final CharArrayWriter writer = new CharArrayWriter(); 2956 copy(inputStream, writer, charset); 2957 return writer.toCharArray(); 2958 } 2959 2960 /** 2961 * Gets the contents of an {@link InputStream} as a character array 2962 * using the specified character encoding. 2963 * <p> 2964 * Character encoding names can be found at 2965 * <a href="http://www.iana.org/assignments/character-sets">IANA</a>. 2966 * </p> 2967 * <p> 2968 * This method buffers the input internally, so there is no need to use a 2969 * {@link BufferedInputStream}. 2970 * </p> 2971 * 2972 * @param inputStream the {@link InputStream} to read 2973 * @param charsetName the name of the requested charset, null means platform default 2974 * @return the requested character array 2975 * @throws NullPointerException if the input is null 2976 * @throws IOException if an I/O error occurs 2977 * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io 2978 * .UnsupportedEncodingException} in version 2.2 if the 2979 * encoding is not supported. 2980 * @since 1.1 2981 */ 2982 public static char[] toCharArray(final InputStream inputStream, final String charsetName) throws IOException { 2983 return toCharArray(inputStream, Charsets.toCharset(charsetName)); 2984 } 2985 2986 /** 2987 * Gets the contents of a {@link Reader} as a character array. 2988 * <p> 2989 * This method buffers the input internally, so there is no need to use a 2990 * {@link BufferedReader}. 2991 * </p> 2992 * 2993 * @param reader the {@link Reader} to read 2994 * @return the requested character array 2995 * @throws NullPointerException if the input is null 2996 * @throws IOException if an I/O error occurs 2997 * @since 1.1 2998 */ 2999 public static char[] toCharArray(final Reader reader) throws IOException { 3000 final CharArrayWriter sw = new CharArrayWriter(); 3001 copy(reader, sw); 3002 return sw.toCharArray(); 3003 } 3004 3005 /** 3006 * Converts the specified CharSequence to an input stream, encoded as bytes 3007 * using the default character encoding of the platform. 3008 * 3009 * @param input the CharSequence to convert 3010 * @return an input stream 3011 * @since 2.0 3012 * @deprecated 2.5 use {@link #toInputStream(CharSequence, Charset)} instead 3013 */ 3014 @Deprecated 3015 public static InputStream toInputStream(final CharSequence input) { 3016 return toInputStream(input, Charset.defaultCharset()); 3017 } 3018 3019 /** 3020 * Converts the specified CharSequence to an input stream, encoded as bytes 3021 * using the specified character encoding. 3022 * 3023 * @param input the CharSequence to convert 3024 * @param charset the charset to use, null means platform default 3025 * @return an input stream 3026 * @since 2.3 3027 */ 3028 public static InputStream toInputStream(final CharSequence input, final Charset charset) { 3029 return toInputStream(input.toString(), charset); 3030 } 3031 3032 /** 3033 * Converts the specified CharSequence to an input stream, encoded as bytes 3034 * using the specified character encoding. 3035 * <p> 3036 * Character encoding names can be found at 3037 * <a href="http://www.iana.org/assignments/character-sets">IANA</a>. 3038 * </p> 3039 * 3040 * @param input the CharSequence to convert 3041 * @param charsetName the name of the requested charset, null means platform default 3042 * @return an input stream 3043 * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io 3044 * .UnsupportedEncodingException} in version 2.2 if the 3045 * encoding is not supported. 3046 * @since 2.0 3047 */ 3048 public static InputStream toInputStream(final CharSequence input, final String charsetName) { 3049 return toInputStream(input, Charsets.toCharset(charsetName)); 3050 } 3051 3052 /** 3053 * Converts the specified string to an input stream, encoded as bytes 3054 * using the default character encoding of the platform. 3055 * 3056 * @param input the string to convert 3057 * @return an input stream 3058 * @since 1.1 3059 * @deprecated 2.5 use {@link #toInputStream(String, Charset)} instead 3060 */ 3061 @Deprecated 3062 public static InputStream toInputStream(final String input) { 3063 return toInputStream(input, Charset.defaultCharset()); 3064 } 3065 3066 /** 3067 * Converts the specified string to an input stream, encoded as bytes 3068 * using the specified character encoding. 3069 * 3070 * @param input the string to convert 3071 * @param charset the charset to use, null means platform default 3072 * @return an input stream 3073 * @since 2.3 3074 */ 3075 public static InputStream toInputStream(final String input, final Charset charset) { 3076 return new ByteArrayInputStream(input.getBytes(Charsets.toCharset(charset))); 3077 } 3078 3079 /** 3080 * Converts the specified string to an input stream, encoded as bytes 3081 * using the specified character encoding. 3082 * <p> 3083 * Character encoding names can be found at 3084 * <a href="http://www.iana.org/assignments/character-sets">IANA</a>. 3085 * </p> 3086 * 3087 * @param input the string to convert 3088 * @param charsetName the name of the requested charset, null means platform default 3089 * @return an input stream 3090 * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io 3091 * .UnsupportedEncodingException} in version 2.2 if the 3092 * encoding is not supported. 3093 * @since 1.1 3094 */ 3095 public static InputStream toInputStream(final String input, final String charsetName) { 3096 return new ByteArrayInputStream(input.getBytes(Charsets.toCharset(charsetName))); 3097 } 3098 3099 /** 3100 * Gets the contents of a {@code byte[]} as a String 3101 * using the default character encoding of the platform. 3102 * 3103 * @param input the byte array to read 3104 * @return the requested String 3105 * @throws NullPointerException if the input is null 3106 * @deprecated 2.5 Use {@link String#String(byte[])} instead 3107 */ 3108 @Deprecated 3109 public static String toString(final byte[] input) { 3110 // make explicit the use of the default charset 3111 return new String(input, Charset.defaultCharset()); 3112 } 3113 3114 /** 3115 * Gets the contents of a {@code byte[]} as a String 3116 * using the specified character encoding. 3117 * <p> 3118 * Character encoding names can be found at 3119 * <a href="http://www.iana.org/assignments/character-sets">IANA</a>. 3120 * </p> 3121 * 3122 * @param input the byte array to read 3123 * @param charsetName the name of the requested charset, null means platform default 3124 * @return the requested String 3125 * @throws NullPointerException if the input is null 3126 */ 3127 public static String toString(final byte[] input, final String charsetName) { 3128 return new String(input, Charsets.toCharset(charsetName)); 3129 } 3130 3131 /** 3132 * Gets the contents of an {@link InputStream} as a String 3133 * using the default character encoding of the platform. 3134 * <p> 3135 * This method buffers the input internally, so there is no need to use a 3136 * {@link BufferedInputStream}. 3137 * </p> 3138 * 3139 * @param input the {@link InputStream} to read 3140 * @return the requested String 3141 * @throws NullPointerException if the input is null 3142 * @throws IOException if an I/O error occurs 3143 * @deprecated 2.5 use {@link #toString(InputStream, Charset)} instead 3144 */ 3145 @Deprecated 3146 public static String toString(final InputStream input) throws IOException { 3147 return toString(input, Charset.defaultCharset()); 3148 } 3149 3150 /** 3151 * Gets the contents of an {@link InputStream} as a String 3152 * using the specified character encoding. 3153 * <p> 3154 * This method buffers the input internally, so there is no need to use a 3155 * {@link BufferedInputStream}. 3156 * </p> 3157 * 3158 * @param input the {@link InputStream} to read 3159 * @param charset the charset to use, null means platform default 3160 * @return the requested String 3161 * @throws NullPointerException if the input is null 3162 * @throws IOException if an I/O error occurs 3163 * @since 2.3 3164 */ 3165 public static String toString(final InputStream input, final Charset charset) throws IOException { 3166 try (StringBuilderWriter sw = new StringBuilderWriter()) { 3167 copy(input, sw, charset); 3168 return sw.toString(); 3169 } 3170 } 3171 3172 /** 3173 * Gets the contents of an {@link InputStream} as a String 3174 * using the specified character encoding. 3175 * <p> 3176 * Character encoding names can be found at 3177 * <a href="http://www.iana.org/assignments/character-sets">IANA</a>. 3178 * </p> 3179 * <p> 3180 * This method buffers the input internally, so there is no need to use a 3181 * {@link BufferedInputStream}. 3182 * </p> 3183 * 3184 * @param input the {@link InputStream} to read 3185 * @param charsetName the name of the requested charset, null means platform default 3186 * @return the requested String 3187 * @throws NullPointerException if the input is null 3188 * @throws IOException if an I/O error occurs 3189 * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io 3190 * .UnsupportedEncodingException} in version 2.2 if the 3191 * encoding is not supported. 3192 */ 3193 public static String toString(final InputStream input, final String charsetName) 3194 throws IOException { 3195 return toString(input, Charsets.toCharset(charsetName)); 3196 } 3197 3198 /** 3199 * Gets the contents of an {@link InputStream} from a supplier as a String 3200 * using the specified character encoding. 3201 * <p> 3202 * This method buffers the input internally, so there is no need to use a 3203 * {@link BufferedInputStream}. 3204 * </p> 3205 * 3206 * @param input supplies the {@link InputStream} to read 3207 * @param charset the charset to use, null means platform default 3208 * @return the requested String 3209 * @throws NullPointerException if the input is null 3210 * @throws IOException if an I/O error occurs 3211 * @since 2.12.0 3212 */ 3213 public static String toString(final IOSupplier<InputStream> input, final Charset charset) throws IOException { 3214 return toString(input, charset, () -> { 3215 throw new NullPointerException("input"); 3216 }); 3217 } 3218 3219 /** 3220 * Gets the contents of an {@link InputStream} from a supplier as a String 3221 * using the specified character encoding. 3222 * <p> 3223 * This method buffers the input internally, so there is no need to use a 3224 * {@link BufferedInputStream}. 3225 * </p> 3226 * 3227 * @param input supplies the {@link InputStream} to read 3228 * @param charset the charset to use, null means platform default 3229 * @param defaultString the default return value if the supplier or its value is null. 3230 * @return the requested String 3231 * @throws NullPointerException if the input is null 3232 * @throws IOException if an I/O error occurs 3233 * @since 2.12.0 3234 */ 3235 public static String toString(final IOSupplier<InputStream> input, final Charset charset, final IOSupplier<String> defaultString) throws IOException { 3236 if (input == null) { 3237 return defaultString.get(); 3238 } 3239 try (InputStream inputStream = input.get()) { 3240 return inputStream != null ? toString(inputStream, charset) : defaultString.get(); 3241 } 3242 } 3243 3244 /** 3245 * Gets the contents of a {@link Reader} as a String. 3246 * <p> 3247 * This method buffers the input internally, so there is no need to use a 3248 * {@link BufferedReader}. 3249 * </p> 3250 * 3251 * @param reader the {@link Reader} to read 3252 * @return the requested String 3253 * @throws NullPointerException if the input is null 3254 * @throws IOException if an I/O error occurs 3255 */ 3256 public static String toString(final Reader reader) throws IOException { 3257 try (StringBuilderWriter sw = new StringBuilderWriter()) { 3258 copy(reader, sw); 3259 return sw.toString(); 3260 } 3261 } 3262 3263 /** 3264 * Gets the contents at the given URI. 3265 * 3266 * @param uri The URI source. 3267 * @return The contents of the URL as a String. 3268 * @throws IOException if an I/O exception occurs. 3269 * @since 2.1 3270 * @deprecated 2.5 use {@link #toString(URI, Charset)} instead 3271 */ 3272 @Deprecated 3273 public static String toString(final URI uri) throws IOException { 3274 return toString(uri, Charset.defaultCharset()); 3275 } 3276 3277 /** 3278 * Gets the contents at the given URI. 3279 * 3280 * @param uri The URI source. 3281 * @param encoding The encoding name for the URL contents. 3282 * @return The contents of the URL as a String. 3283 * @throws IOException if an I/O exception occurs. 3284 * @since 2.3. 3285 */ 3286 public static String toString(final URI uri, final Charset encoding) throws IOException { 3287 return toString(uri.toURL(), Charsets.toCharset(encoding)); 3288 } 3289 3290 /** 3291 * Gets the contents at the given URI. 3292 * 3293 * @param uri The URI source. 3294 * @param charsetName The encoding name for the URL contents. 3295 * @return The contents of the URL as a String. 3296 * @throws IOException if an I/O exception occurs. 3297 * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io 3298 * .UnsupportedEncodingException} in version 2.2 if the 3299 * encoding is not supported. 3300 * @since 2.1 3301 */ 3302 public static String toString(final URI uri, final String charsetName) throws IOException { 3303 return toString(uri, Charsets.toCharset(charsetName)); 3304 } 3305 3306 /** 3307 * Gets the contents at the given URL. 3308 * 3309 * @param url The URL source. 3310 * @return The contents of the URL as a String. 3311 * @throws IOException if an I/O exception occurs. 3312 * @since 2.1 3313 * @deprecated 2.5 use {@link #toString(URL, Charset)} instead 3314 */ 3315 @Deprecated 3316 public static String toString(final URL url) throws IOException { 3317 return toString(url, Charset.defaultCharset()); 3318 } 3319 3320 /** 3321 * Gets the contents at the given URL. 3322 * 3323 * @param url The URL source. 3324 * @param encoding The encoding name for the URL contents. 3325 * @return The contents of the URL as a String. 3326 * @throws IOException if an I/O exception occurs. 3327 * @since 2.3 3328 */ 3329 public static String toString(final URL url, final Charset encoding) throws IOException { 3330 return toString(url::openStream, encoding); 3331 } 3332 3333 /** 3334 * Gets the contents at the given URL. 3335 * 3336 * @param url The URL source. 3337 * @param charsetName The encoding name for the URL contents. 3338 * @return The contents of the URL as a String. 3339 * @throws IOException if an I/O exception occurs. 3340 * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io 3341 * .UnsupportedEncodingException} in version 2.2 if the 3342 * encoding is not supported. 3343 * @since 2.1 3344 */ 3345 public static String toString(final URL url, final String charsetName) throws IOException { 3346 return toString(url, Charsets.toCharset(charsetName)); 3347 } 3348 3349 /** 3350 * Writes bytes from a {@code byte[]} to an {@link OutputStream}. 3351 * 3352 * @param data the byte array to write, do not modify during output, 3353 * null ignored 3354 * @param output the {@link OutputStream} to write to 3355 * @throws NullPointerException if output is null 3356 * @throws IOException if an I/O error occurs 3357 * @since 1.1 3358 */ 3359 public static void write(final byte[] data, final OutputStream output) 3360 throws IOException { 3361 if (data != null) { 3362 output.write(data); 3363 } 3364 } 3365 3366 /** 3367 * Writes bytes from a {@code byte[]} to chars on a {@link Writer} 3368 * using the default character encoding of the platform. 3369 * <p> 3370 * This method uses {@link String#String(byte[])}. 3371 * </p> 3372 * 3373 * @param data the byte array to write, do not modify during output, 3374 * null ignored 3375 * @param writer the {@link Writer} to write to 3376 * @throws NullPointerException if output is null 3377 * @throws IOException if an I/O error occurs 3378 * @since 1.1 3379 * @deprecated 2.5 use {@link #write(byte[], Writer, Charset)} instead 3380 */ 3381 @Deprecated 3382 public static void write(final byte[] data, final Writer writer) throws IOException { 3383 write(data, writer, Charset.defaultCharset()); 3384 } 3385 3386 /** 3387 * Writes bytes from a {@code byte[]} to chars on a {@link Writer} 3388 * using the specified character encoding. 3389 * <p> 3390 * This method uses {@link String#String(byte[], String)}. 3391 * </p> 3392 * 3393 * @param data the byte array to write, do not modify during output, 3394 * null ignored 3395 * @param writer the {@link Writer} to write to 3396 * @param charset the charset to use, null means platform default 3397 * @throws NullPointerException if output is null 3398 * @throws IOException if an I/O error occurs 3399 * @since 2.3 3400 */ 3401 public static void write(final byte[] data, final Writer writer, final Charset charset) throws IOException { 3402 if (data != null) { 3403 writer.write(new String(data, Charsets.toCharset(charset))); 3404 } 3405 } 3406 3407 /** 3408 * Writes bytes from a {@code byte[]} to chars on a {@link Writer} 3409 * using the specified character encoding. 3410 * <p> 3411 * Character encoding names can be found at 3412 * <a href="http://www.iana.org/assignments/character-sets">IANA</a>. 3413 * </p> 3414 * <p> 3415 * This method uses {@link String#String(byte[], String)}. 3416 * </p> 3417 * 3418 * @param data the byte array to write, do not modify during output, 3419 * null ignored 3420 * @param writer the {@link Writer} to write to 3421 * @param charsetName the name of the requested charset, null means platform default 3422 * @throws NullPointerException if output is null 3423 * @throws IOException if an I/O error occurs 3424 * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io 3425 * .UnsupportedEncodingException} in version 2.2 if the 3426 * encoding is not supported. 3427 * @since 1.1 3428 */ 3429 public static void write(final byte[] data, final Writer writer, final String charsetName) throws IOException { 3430 write(data, writer, Charsets.toCharset(charsetName)); 3431 } 3432 3433 /** 3434 * Writes chars from a {@code char[]} to bytes on an 3435 * {@link OutputStream}. 3436 * <p> 3437 * This method uses {@link String#String(char[])} and 3438 * {@link String#getBytes()}. 3439 * </p> 3440 * 3441 * @param data the char array to write, do not modify during output, 3442 * null ignored 3443 * @param output the {@link OutputStream} to write to 3444 * @throws NullPointerException if output is null 3445 * @throws IOException if an I/O error occurs 3446 * @since 1.1 3447 * @deprecated 2.5 use {@link #write(char[], OutputStream, Charset)} instead 3448 */ 3449 @Deprecated 3450 public static void write(final char[] data, final OutputStream output) 3451 throws IOException { 3452 write(data, output, Charset.defaultCharset()); 3453 } 3454 3455 /** 3456 * Writes chars from a {@code char[]} to bytes on an 3457 * {@link OutputStream} using the specified character encoding. 3458 * <p> 3459 * This method uses {@link String#String(char[])} and 3460 * {@link String#getBytes(String)}. 3461 * </p> 3462 * 3463 * @param data the char array to write, do not modify during output, 3464 * null ignored 3465 * @param output the {@link OutputStream} to write to 3466 * @param charset the charset to use, null means platform default 3467 * @throws NullPointerException if output is null 3468 * @throws IOException if an I/O error occurs 3469 * @since 2.3 3470 */ 3471 public static void write(final char[] data, final OutputStream output, final Charset charset) throws IOException { 3472 if (data != null) { 3473 write(new String(data), output, charset); 3474 } 3475 } 3476 3477 /** 3478 * Writes chars from a {@code char[]} to bytes on an 3479 * {@link OutputStream} using the specified character encoding. 3480 * <p> 3481 * Character encoding names can be found at 3482 * <a href="http://www.iana.org/assignments/character-sets">IANA</a>. 3483 * </p> 3484 * <p> 3485 * This method uses {@link String#String(char[])} and 3486 * {@link String#getBytes(String)}. 3487 * </p> 3488 * 3489 * @param data the char array to write, do not modify during output, 3490 * null ignored 3491 * @param output the {@link OutputStream} to write to 3492 * @param charsetName the name of the requested charset, null means platform default 3493 * @throws NullPointerException if output is null 3494 * @throws IOException if an I/O error occurs 3495 * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io 3496 * .UnsupportedEncodingException} in version 2.2 if the encoding is not supported. 3497 * @since 1.1 3498 */ 3499 public static void write(final char[] data, final OutputStream output, final String charsetName) 3500 throws IOException { 3501 write(data, output, Charsets.toCharset(charsetName)); 3502 } 3503 3504 /** 3505 * Writes chars from a {@code char[]} to a {@link Writer} 3506 * 3507 * @param data the char array to write, do not modify during output, 3508 * null ignored 3509 * @param writer the {@link Writer} to write to 3510 * @throws NullPointerException if output is null 3511 * @throws IOException if an I/O error occurs 3512 * @since 1.1 3513 */ 3514 public static void write(final char[] data, final Writer writer) throws IOException { 3515 if (data != null) { 3516 writer.write(data); 3517 } 3518 } 3519 3520 /** 3521 * Writes chars from a {@link CharSequence} to bytes on an 3522 * {@link OutputStream} using the default character encoding of the 3523 * platform. 3524 * <p> 3525 * This method uses {@link String#getBytes()}. 3526 * </p> 3527 * 3528 * @param data the {@link CharSequence} to write, null ignored 3529 * @param output the {@link OutputStream} to write to 3530 * @throws NullPointerException if output is null 3531 * @throws IOException if an I/O error occurs 3532 * @since 2.0 3533 * @deprecated 2.5 use {@link #write(CharSequence, OutputStream, Charset)} instead 3534 */ 3535 @Deprecated 3536 public static void write(final CharSequence data, final OutputStream output) 3537 throws IOException { 3538 write(data, output, Charset.defaultCharset()); 3539 } 3540 3541 /** 3542 * Writes chars from a {@link CharSequence} to bytes on an 3543 * {@link OutputStream} using the specified character encoding. 3544 * <p> 3545 * This method uses {@link String#getBytes(String)}. 3546 * </p> 3547 * 3548 * @param data the {@link CharSequence} to write, null ignored 3549 * @param output the {@link OutputStream} to write to 3550 * @param charset the charset to use, null means platform default 3551 * @throws NullPointerException if output is null 3552 * @throws IOException if an I/O error occurs 3553 * @since 2.3 3554 */ 3555 public static void write(final CharSequence data, final OutputStream output, final Charset charset) 3556 throws IOException { 3557 if (data != null) { 3558 write(data.toString(), output, charset); 3559 } 3560 } 3561 3562 /** 3563 * Writes chars from a {@link CharSequence} to bytes on an 3564 * {@link OutputStream} using the specified character encoding. 3565 * <p> 3566 * Character encoding names can be found at 3567 * <a href="http://www.iana.org/assignments/character-sets">IANA</a>. 3568 * </p> 3569 * <p> 3570 * This method uses {@link String#getBytes(String)}. 3571 * </p> 3572 * 3573 * @param data the {@link CharSequence} to write, null ignored 3574 * @param output the {@link OutputStream} to write to 3575 * @param charsetName the name of the requested charset, null means platform default 3576 * @throws NullPointerException if output is null 3577 * @throws IOException if an I/O error occurs 3578 * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io 3579 * .UnsupportedEncodingException} in version 2.2 if the encoding is not supported. 3580 * @since 2.0 3581 */ 3582 public static void write(final CharSequence data, final OutputStream output, final String charsetName) 3583 throws IOException { 3584 write(data, output, Charsets.toCharset(charsetName)); 3585 } 3586 3587 3588 /** 3589 * Writes chars from a {@link CharSequence} to a {@link Writer}. 3590 * 3591 * @param data the {@link CharSequence} to write, null ignored 3592 * @param writer the {@link Writer} to write to 3593 * @throws NullPointerException if output is null 3594 * @throws IOException if an I/O error occurs 3595 * @since 2.0 3596 */ 3597 public static void write(final CharSequence data, final Writer writer) throws IOException { 3598 if (data != null) { 3599 write(data.toString(), writer); 3600 } 3601 } 3602 3603 /** 3604 * Writes chars from a {@link String} to bytes on an 3605 * {@link OutputStream} using the default character encoding of the 3606 * platform. 3607 * <p> 3608 * This method uses {@link String#getBytes()}. 3609 * </p> 3610 * 3611 * @param data the {@link String} to write, null ignored 3612 * @param output the {@link OutputStream} to write to 3613 * @throws NullPointerException if output is null 3614 * @throws IOException if an I/O error occurs 3615 * @since 1.1 3616 * @deprecated 2.5 use {@link #write(String, OutputStream, Charset)} instead 3617 */ 3618 @Deprecated 3619 public static void write(final String data, final OutputStream output) 3620 throws IOException { 3621 write(data, output, Charset.defaultCharset()); 3622 } 3623 3624 /** 3625 * Writes chars from a {@link String} to bytes on an 3626 * {@link OutputStream} using the specified character encoding. 3627 * <p> 3628 * This method uses {@link String#getBytes(String)}. 3629 * </p> 3630 * 3631 * @param data the {@link String} to write, null ignored 3632 * @param output the {@link OutputStream} to write to 3633 * @param charset the charset to use, null means platform default 3634 * @throws NullPointerException if output is null 3635 * @throws IOException if an I/O error occurs 3636 * @since 2.3 3637 */ 3638 @SuppressWarnings("resource") 3639 public static void write(final String data, final OutputStream output, final Charset charset) throws IOException { 3640 if (data != null) { 3641 // Use Charset#encode(String), since calling String#getBytes(Charset) might result in 3642 // NegativeArraySizeException or OutOfMemoryError. 3643 // The underlying OutputStream should not be closed, so the channel is not closed. 3644 Channels.newChannel(output).write(Charsets.toCharset(charset).encode(data)); 3645 } 3646 } 3647 3648 /** 3649 * Writes chars from a {@link String} to bytes on an 3650 * {@link OutputStream} using the specified character encoding. 3651 * <p> 3652 * Character encoding names can be found at 3653 * <a href="http://www.iana.org/assignments/character-sets">IANA</a>. 3654 * </p> 3655 * <p> 3656 * This method uses {@link String#getBytes(String)}. 3657 * </p> 3658 * 3659 * @param data the {@link String} to write, null ignored 3660 * @param output the {@link OutputStream} to write to 3661 * @param charsetName the name of the requested charset, null means platform default 3662 * @throws NullPointerException if output is null 3663 * @throws IOException if an I/O error occurs 3664 * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io 3665 * .UnsupportedEncodingException} in version 2.2 if the encoding is not supported. 3666 * @since 1.1 3667 */ 3668 public static void write(final String data, final OutputStream output, final String charsetName) 3669 throws IOException { 3670 write(data, output, Charsets.toCharset(charsetName)); 3671 } 3672 3673 /** 3674 * Writes chars from a {@link String} to a {@link Writer}. 3675 * 3676 * @param data the {@link String} to write, null ignored 3677 * @param writer the {@link Writer} to write to 3678 * @throws NullPointerException if output is null 3679 * @throws IOException if an I/O error occurs 3680 * @since 1.1 3681 */ 3682 public static void write(final String data, final Writer writer) throws IOException { 3683 if (data != null) { 3684 writer.write(data); 3685 } 3686 } 3687 3688 /** 3689 * Writes chars from a {@link StringBuffer} to bytes on an 3690 * {@link OutputStream} using the default character encoding of the 3691 * platform. 3692 * <p> 3693 * This method uses {@link String#getBytes()}. 3694 * </p> 3695 * 3696 * @param data the {@link StringBuffer} to write, null ignored 3697 * @param output the {@link OutputStream} to write to 3698 * @throws NullPointerException if output is null 3699 * @throws IOException if an I/O error occurs 3700 * @since 1.1 3701 * @deprecated Use {@link #write(CharSequence, OutputStream)} 3702 */ 3703 @Deprecated 3704 public static void write(final StringBuffer data, final OutputStream output) //NOSONAR 3705 throws IOException { 3706 write(data, output, (String) null); 3707 } 3708 3709 /** 3710 * Writes chars from a {@link StringBuffer} to bytes on an 3711 * {@link OutputStream} using the specified character encoding. 3712 * <p> 3713 * Character encoding names can be found at 3714 * <a href="http://www.iana.org/assignments/character-sets">IANA</a>. 3715 * </p> 3716 * <p> 3717 * This method uses {@link String#getBytes(String)}. 3718 * </p> 3719 * 3720 * @param data the {@link StringBuffer} to write, null ignored 3721 * @param output the {@link OutputStream} to write to 3722 * @param charsetName the name of the requested charset, null means platform default 3723 * @throws NullPointerException if output is null 3724 * @throws IOException if an I/O error occurs 3725 * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io 3726 * .UnsupportedEncodingException} in version 2.2 if the encoding is not supported. 3727 * @since 1.1 3728 * @deprecated Use {@link #write(CharSequence, OutputStream, String)}. 3729 */ 3730 @Deprecated 3731 public static void write(final StringBuffer data, final OutputStream output, final String charsetName) //NOSONAR 3732 throws IOException { 3733 if (data != null) { 3734 write(data.toString(), output, Charsets.toCharset(charsetName)); 3735 } 3736 } 3737 3738 /** 3739 * Writes chars from a {@link StringBuffer} to a {@link Writer}. 3740 * 3741 * @param data the {@link StringBuffer} to write, null ignored 3742 * @param writer the {@link Writer} to write to 3743 * @throws NullPointerException if output is null 3744 * @throws IOException if an I/O error occurs 3745 * @since 1.1 3746 * @deprecated Use {@link #write(CharSequence, Writer)} 3747 */ 3748 @Deprecated 3749 public static void write(final StringBuffer data, final Writer writer) //NOSONAR 3750 throws IOException { 3751 if (data != null) { 3752 writer.write(data.toString()); 3753 } 3754 } 3755 3756 /** 3757 * Writes bytes from a {@code byte[]} to an {@link OutputStream} using chunked writes. 3758 * This is intended for writing very large byte arrays which might otherwise cause excessive 3759 * memory usage if the native code has to allocate a copy. 3760 * 3761 * @param data the byte array to write, do not modify during output, 3762 * null ignored 3763 * @param output the {@link OutputStream} to write to 3764 * @throws NullPointerException if output is null 3765 * @throws IOException if an I/O error occurs 3766 * @since 2.5 3767 */ 3768 public static void writeChunked(final byte[] data, final OutputStream output) 3769 throws IOException { 3770 if (data != null) { 3771 int bytes = data.length; 3772 int offset = 0; 3773 while (bytes > 0) { 3774 final int chunk = Math.min(bytes, DEFAULT_BUFFER_SIZE); 3775 output.write(data, offset, chunk); 3776 bytes -= chunk; 3777 offset += chunk; 3778 } 3779 } 3780 } 3781 3782 /** 3783 * Writes chars from a {@code char[]} to a {@link Writer} using chunked writes. 3784 * This is intended for writing very large byte arrays which might otherwise cause excessive 3785 * memory usage if the native code has to allocate a copy. 3786 * 3787 * @param data the char array to write, do not modify during output, 3788 * null ignored 3789 * @param writer the {@link Writer} to write to 3790 * @throws NullPointerException if output is null 3791 * @throws IOException if an I/O error occurs 3792 * @since 2.5 3793 */ 3794 public static void writeChunked(final char[] data, final Writer writer) throws IOException { 3795 if (data != null) { 3796 int bytes = data.length; 3797 int offset = 0; 3798 while (bytes > 0) { 3799 final int chunk = Math.min(bytes, DEFAULT_BUFFER_SIZE); 3800 writer.write(data, offset, chunk); 3801 bytes -= chunk; 3802 offset += chunk; 3803 } 3804 } 3805 } 3806 3807 /** 3808 * Writes the {@link #toString()} value of each item in a collection to 3809 * an {@link OutputStream} line by line, using the default character 3810 * encoding of the platform and the specified line ending. 3811 * 3812 * @param lines the lines to write, null entries produce blank lines 3813 * @param lineEnding the line separator to use, null is system default 3814 * @param output the {@link OutputStream} to write to, not null, not closed 3815 * @throws NullPointerException if the output is null 3816 * @throws IOException if an I/O error occurs 3817 * @since 1.1 3818 * @deprecated 2.5 use {@link #writeLines(Collection, String, OutputStream, Charset)} instead 3819 */ 3820 @Deprecated 3821 public static void writeLines(final Collection<?> lines, final String lineEnding, 3822 final OutputStream output) throws IOException { 3823 writeLines(lines, lineEnding, output, Charset.defaultCharset()); 3824 } 3825 3826 /** 3827 * Writes the {@link #toString()} value of each item in a collection to 3828 * an {@link OutputStream} line by line, using the specified character 3829 * encoding and the specified line ending. 3830 * <p> 3831 * UTF-16 is written big-endian with no byte order mark. 3832 * For little endian, use UTF-16LE. For a BOM, write it to the stream 3833 * before calling this method. 3834 * </p> 3835 * 3836 * @param lines the lines to write, null entries produce blank lines 3837 * @param lineEnding the line separator to use, null is system default 3838 * @param output the {@link OutputStream} to write to, not null, not closed 3839 * @param charset the charset to use, null means platform default 3840 * @throws NullPointerException if output is null 3841 * @throws IOException if an I/O error occurs 3842 * @since 2.3 3843 */ 3844 public static void writeLines(final Collection<?> lines, String lineEnding, final OutputStream output, 3845 Charset charset) throws IOException { 3846 if (lines == null) { 3847 return; 3848 } 3849 if (lineEnding == null) { 3850 lineEnding = System.lineSeparator(); 3851 } 3852 if (StandardCharsets.UTF_16.equals(charset)) { 3853 // don't write a BOM 3854 charset = StandardCharsets.UTF_16BE; 3855 } 3856 final byte[] eolBytes = lineEnding.getBytes(charset); 3857 for (final Object line : lines) { 3858 if (line != null) { 3859 write(line.toString(), output, charset); 3860 } 3861 output.write(eolBytes); 3862 } 3863 } 3864 3865 /** 3866 * Writes the {@link #toString()} value of each item in a collection to 3867 * an {@link OutputStream} line by line, using the specified character 3868 * encoding and the specified line ending. 3869 * <p> 3870 * Character encoding names can be found at 3871 * <a href="http://www.iana.org/assignments/character-sets">IANA</a>. 3872 * </p> 3873 * 3874 * @param lines the lines to write, null entries produce blank lines 3875 * @param lineEnding the line separator to use, null is system default 3876 * @param output the {@link OutputStream} to write to, not null, not closed 3877 * @param charsetName the name of the requested charset, null means platform default 3878 * @throws NullPointerException if the output is null 3879 * @throws IOException if an I/O error occurs 3880 * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io 3881 * .UnsupportedEncodingException} in version 2.2 if the 3882 * encoding is not supported. 3883 * @since 1.1 3884 */ 3885 public static void writeLines(final Collection<?> lines, final String lineEnding, 3886 final OutputStream output, final String charsetName) throws IOException { 3887 writeLines(lines, lineEnding, output, Charsets.toCharset(charsetName)); 3888 } 3889 3890 /** 3891 * Writes the {@link #toString()} value of each item in a collection to 3892 * a {@link Writer} line by line, using the specified line ending. 3893 * 3894 * @param lines the lines to write, null entries produce blank lines 3895 * @param lineEnding the line separator to use, null is system default 3896 * @param writer the {@link Writer} to write to, not null, not closed 3897 * @throws NullPointerException if the input is null 3898 * @throws IOException if an I/O error occurs 3899 * @since 1.1 3900 */ 3901 public static void writeLines(final Collection<?> lines, String lineEnding, 3902 final Writer writer) throws IOException { 3903 if (lines == null) { 3904 return; 3905 } 3906 if (lineEnding == null) { 3907 lineEnding = System.lineSeparator(); 3908 } 3909 for (final Object line : lines) { 3910 if (line != null) { 3911 writer.write(line.toString()); 3912 } 3913 writer.write(lineEnding); 3914 } 3915 } 3916 3917 /** 3918 * Returns the given Appendable if it is already a {@link Writer}, otherwise creates a Writer wrapper around the 3919 * given Appendable. 3920 * 3921 * @param appendable the Appendable to wrap or return (not null) 3922 * @return the given Appendable or a Writer wrapper around the given Appendable 3923 * @throws NullPointerException if the input parameter is null 3924 * @since 2.7 3925 */ 3926 public static Writer writer(final Appendable appendable) { 3927 Objects.requireNonNull(appendable, "appendable"); 3928 if (appendable instanceof Writer) { 3929 return (Writer) appendable; 3930 } 3931 if (appendable instanceof StringBuilder) { 3932 return new StringBuilderWriter((StringBuilder) appendable); 3933 } 3934 return new AppendableWriter<>(appendable); 3935 } 3936 3937 /** 3938 * Instances should NOT be constructed in standard programming. 3939 * @deprecated Will be private in 3.0. 3940 */ 3941 @Deprecated 3942 public IOUtils() { //NOSONAR 3943 } 3944 3945}