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