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