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.FileOutputStream; 029import java.io.IOException; 030import java.io.InputStream; 031import java.io.InputStreamReader; 032import java.io.OutputStream; 033import java.io.OutputStreamWriter; 034import java.io.Reader; 035import java.io.Writer; 036import java.net.HttpURLConnection; 037import java.net.ServerSocket; 038import java.net.Socket; 039import java.net.URI; 040import java.net.URL; 041import java.net.URLConnection; 042import java.nio.ByteBuffer; 043import java.nio.CharBuffer; 044import java.nio.channels.ReadableByteChannel; 045import java.nio.channels.Selector; 046import java.nio.charset.Charset; 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 (FileOutputStream outputStream = new FileOutputStream(Objects.requireNonNull(file, "file"))) { 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 * @throws IOException Never thrown. 1598 * @since 2.3 1599 */ 1600 public static LineIterator lineIterator(final InputStream input, final Charset charset) throws IOException { 1601 return new LineIterator(new InputStreamReader(input, Charsets.toCharset(charset))); 1602 } 1603 1604 /** 1605 * Returns an Iterator for the lines in an {@code InputStream}, using 1606 * the character encoding specified (or default encoding if null). 1607 * <p> 1608 * {@code LineIterator} holds a reference to the open 1609 * {@code InputStream} specified here. When you have finished with 1610 * the iterator you should close the stream to free internal resources. 1611 * This can be done by closing the stream directly, or by calling 1612 * {@link LineIterator#close()} or {@link LineIterator#closeQuietly(LineIterator)}. 1613 * <p> 1614 * The recommended usage pattern is: 1615 * <pre> 1616 * try { 1617 * LineIterator it = IOUtils.lineIterator(stream, "UTF-8"); 1618 * while (it.hasNext()) { 1619 * String line = it.nextLine(); 1620 * /// do something with line 1621 * } 1622 * } finally { 1623 * IOUtils.closeQuietly(stream); 1624 * } 1625 * </pre> 1626 * 1627 * @param input the {@code InputStream} to read from, not null 1628 * @param charsetName the encoding to use, null means platform default 1629 * @return an Iterator of the lines in the reader, never null 1630 * @throws IllegalArgumentException if the input is null 1631 * @throws IOException if an I/O error occurs, such as if the encoding is invalid 1632 * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io 1633 * .UnsupportedEncodingException} in version 2.2 if the 1634 * encoding is not supported. 1635 * @since 1.2 1636 */ 1637 public static LineIterator lineIterator(final InputStream input, final String charsetName) throws IOException { 1638 return lineIterator(input, Charsets.toCharset(charsetName)); 1639 } 1640 1641 /** 1642 * Returns an Iterator for the lines in a {@code Reader}. 1643 * <p> 1644 * {@code LineIterator} holds a reference to the open 1645 * {@code Reader} specified here. When you have finished with the 1646 * iterator you should close the reader to free internal resources. 1647 * This can be done by closing the reader directly, or by calling 1648 * {@link LineIterator#close()} or {@link LineIterator#closeQuietly(LineIterator)}. 1649 * <p> 1650 * The recommended usage pattern is: 1651 * <pre> 1652 * try { 1653 * LineIterator it = IOUtils.lineIterator(reader); 1654 * while (it.hasNext()) { 1655 * String line = it.nextLine(); 1656 * /// do something with line 1657 * } 1658 * } finally { 1659 * IOUtils.closeQuietly(reader); 1660 * } 1661 * </pre> 1662 * 1663 * @param reader the {@code Reader} to read from, not null 1664 * @return an Iterator of the lines in the reader, never null 1665 * @throws IllegalArgumentException if the reader is null 1666 * @since 1.2 1667 */ 1668 public static LineIterator lineIterator(final Reader reader) { 1669 return new LineIterator(reader); 1670 } 1671 1672 /** 1673 * Reads bytes from an input stream. 1674 * This implementation guarantees that it will read as many bytes 1675 * as possible before giving up; this may not always be the case for 1676 * subclasses of {@link InputStream}. 1677 * 1678 * @param input where to read input from 1679 * @param buffer destination 1680 * @return actual length read; may be less than requested if EOF was reached 1681 * @throws IOException if a read error occurs 1682 * @since 2.2 1683 */ 1684 public static int read(final InputStream input, final byte[] buffer) throws IOException { 1685 return read(input, buffer, 0, buffer.length); 1686 } 1687 1688 /** 1689 * Reads bytes from an input stream. 1690 * This implementation guarantees that it will read as many bytes 1691 * as possible before giving up; this may not always be the case for 1692 * subclasses of {@link InputStream}. 1693 * 1694 * @param input where to read input from 1695 * @param buffer destination 1696 * @param offset initial offset into buffer 1697 * @param length length to read, must be >= 0 1698 * @return actual length read; may be less than requested if EOF was reached 1699 * @throws IOException if a read error occurs 1700 * @since 2.2 1701 */ 1702 public static int read(final InputStream input, final byte[] buffer, final int offset, final int length) 1703 throws IOException { 1704 if (length < 0) { 1705 throw new IllegalArgumentException("Length must not be negative: " + length); 1706 } 1707 int remaining = length; 1708 while (remaining > 0) { 1709 final int location = length - remaining; 1710 final int count = input.read(buffer, offset + location, remaining); 1711 if (EOF == count) { // EOF 1712 break; 1713 } 1714 remaining -= count; 1715 } 1716 return length - remaining; 1717 } 1718 1719 /** 1720 * Reads bytes from a ReadableByteChannel. 1721 * <p> 1722 * This implementation guarantees that it will read as many bytes 1723 * as possible before giving up; this may not always be the case for 1724 * subclasses of {@link ReadableByteChannel}. 1725 * 1726 * @param input the byte channel to read 1727 * @param buffer byte buffer destination 1728 * @return the actual length read; may be less than requested if EOF was reached 1729 * @throws IOException if a read error occurs 1730 * @since 2.5 1731 */ 1732 public static int read(final ReadableByteChannel input, final ByteBuffer buffer) throws IOException { 1733 final int length = buffer.remaining(); 1734 while (buffer.remaining() > 0) { 1735 final int count = input.read(buffer); 1736 if (EOF == count) { // EOF 1737 break; 1738 } 1739 } 1740 return length - buffer.remaining(); 1741 } 1742 1743 /** 1744 * Reads characters from an input character stream. 1745 * This implementation guarantees that it will read as many characters 1746 * as possible before giving up; this may not always be the case for 1747 * subclasses of {@link Reader}. 1748 * 1749 * @param reader where to read input from 1750 * @param buffer destination 1751 * @return actual length read; may be less than requested if EOF was reached 1752 * @throws IOException if a read error occurs 1753 * @since 2.2 1754 */ 1755 public static int read(final Reader reader, final char[] buffer) throws IOException { 1756 return read(reader, buffer, 0, buffer.length); 1757 } 1758 1759 /** 1760 * Reads characters from an input character stream. 1761 * This implementation guarantees that it will read as many characters 1762 * as possible before giving up; this may not always be the case for 1763 * subclasses of {@link Reader}. 1764 * 1765 * @param reader where to read input from 1766 * @param buffer destination 1767 * @param offset initial offset into buffer 1768 * @param length length to read, must be >= 0 1769 * @return actual length read; may be less than requested if EOF was reached 1770 * @throws IOException if a read error occurs 1771 * @since 2.2 1772 */ 1773 public static int read(final Reader reader, final char[] buffer, final int offset, final int length) 1774 throws IOException { 1775 if (length < 0) { 1776 throw new IllegalArgumentException("Length must not be negative: " + length); 1777 } 1778 int remaining = length; 1779 while (remaining > 0) { 1780 final int location = length - remaining; 1781 final int count = reader.read(buffer, offset + location, remaining); 1782 if (EOF == count) { // EOF 1783 break; 1784 } 1785 remaining -= count; 1786 } 1787 return length - remaining; 1788 } 1789 1790 /** 1791 * Reads the requested number of bytes or fail if there are not enough left. 1792 * <p> 1793 * This allows for the possibility that {@link InputStream#read(byte[], int, int)} may 1794 * not read as many bytes as requested (most likely because of reaching EOF). 1795 * 1796 * @param input where to read input from 1797 * @param buffer destination 1798 * 1799 * @throws IOException if there is a problem reading the file 1800 * @throws IllegalArgumentException if length is negative 1801 * @throws EOFException if the number of bytes read was incorrect 1802 * @since 2.2 1803 */ 1804 public static void readFully(final InputStream input, final byte[] buffer) throws IOException { 1805 readFully(input, buffer, 0, buffer.length); 1806 } 1807 1808 /** 1809 * Reads the requested number of bytes or fail if there are not enough left. 1810 * <p> 1811 * This allows for the possibility that {@link InputStream#read(byte[], int, int)} may 1812 * not read as many bytes as requested (most likely because of reaching EOF). 1813 * 1814 * @param input where to read input from 1815 * @param buffer destination 1816 * @param offset initial offset into buffer 1817 * @param length length to read, must be >= 0 1818 * 1819 * @throws IOException if there is a problem reading the file 1820 * @throws IllegalArgumentException if length is negative 1821 * @throws EOFException if the number of bytes read was incorrect 1822 * @since 2.2 1823 */ 1824 public static void readFully(final InputStream input, final byte[] buffer, final int offset, final int length) 1825 throws IOException { 1826 final int actual = read(input, buffer, offset, length); 1827 if (actual != length) { 1828 throw new EOFException("Length to read: " + length + " actual: " + actual); 1829 } 1830 } 1831 1832 /** 1833 * Reads the requested number of bytes or fail if there are not enough left. 1834 * <p> 1835 * This allows for the possibility that {@link InputStream#read(byte[], int, int)} may 1836 * not read as many bytes as requested (most likely because of reaching EOF). 1837 * 1838 * @param input where to read input from 1839 * @param length length to read, must be >= 0 1840 * @return the bytes read from input 1841 * @throws IOException if there is a problem reading the file 1842 * @throws IllegalArgumentException if length is negative 1843 * @throws EOFException if the number of bytes read was incorrect 1844 * @since 2.5 1845 */ 1846 public static byte[] readFully(final InputStream input, final int length) throws IOException { 1847 final byte[] buffer = IOUtils.byteArray(length); 1848 readFully(input, buffer, 0, buffer.length); 1849 return buffer; 1850 } 1851 1852 /** 1853 * Reads the requested number of bytes or fail if there are not enough left. 1854 * <p> 1855 * This allows for the possibility that {@link ReadableByteChannel#read(ByteBuffer)} may 1856 * not read as many bytes as requested (most likely because of reaching EOF). 1857 * 1858 * @param input the byte channel to read 1859 * @param buffer byte buffer destination 1860 * @throws IOException if there is a problem reading the file 1861 * @throws EOFException if the number of bytes read was incorrect 1862 * @since 2.5 1863 */ 1864 public static void readFully(final ReadableByteChannel input, final ByteBuffer buffer) throws IOException { 1865 final int expected = buffer.remaining(); 1866 final int actual = read(input, buffer); 1867 if (actual != expected) { 1868 throw new EOFException("Length to read: " + expected + " actual: " + actual); 1869 } 1870 } 1871 1872 /** 1873 * Reads the requested number of characters or fail if there are not enough left. 1874 * <p> 1875 * This allows for the possibility that {@link Reader#read(char[], int, int)} may 1876 * not read as many characters as requested (most likely because of reaching EOF). 1877 * 1878 * @param reader where to read input from 1879 * @param buffer destination 1880 * @throws IOException if there is a problem reading the file 1881 * @throws IllegalArgumentException if length is negative 1882 * @throws EOFException if the number of characters read was incorrect 1883 * @since 2.2 1884 */ 1885 public static void readFully(final Reader reader, final char[] buffer) throws IOException { 1886 readFully(reader, buffer, 0, buffer.length); 1887 } 1888 1889 /** 1890 * Reads the requested number of characters or fail if there are not enough left. 1891 * <p> 1892 * This allows for the possibility that {@link Reader#read(char[], int, int)} may 1893 * not read as many characters as requested (most likely because of reaching EOF). 1894 * 1895 * @param reader where to read input from 1896 * @param buffer destination 1897 * @param offset initial offset into buffer 1898 * @param length length to read, must be >= 0 1899 * @throws IOException if there is a problem reading the file 1900 * @throws IllegalArgumentException if length is negative 1901 * @throws EOFException if the number of characters read was incorrect 1902 * @since 2.2 1903 */ 1904 public static void readFully(final Reader reader, final char[] buffer, final int offset, final int length) 1905 throws IOException { 1906 final int actual = read(reader, buffer, offset, length); 1907 if (actual != length) { 1908 throw new EOFException("Length to read: " + length + " actual: " + actual); 1909 } 1910 } 1911 1912 /** 1913 * Gets the contents of an {@code InputStream} as a list of Strings, 1914 * one entry per line, using the default character encoding of the platform. 1915 * <p> 1916 * This method buffers the input internally, so there is no need to use a 1917 * {@code BufferedInputStream}. 1918 * 1919 * @param input the {@code InputStream} to read from, not null 1920 * @return the list of Strings, never null 1921 * @throws NullPointerException if the input is null 1922 * @throws IOException if an I/O error occurs 1923 * @since 1.1 1924 * @deprecated 2.5 use {@link #readLines(InputStream, Charset)} instead 1925 */ 1926 @Deprecated 1927 public static List<String> readLines(final InputStream input) throws IOException { 1928 return readLines(input, Charset.defaultCharset()); 1929 } 1930 1931 /** 1932 * Gets the contents of an {@code InputStream} as a list of Strings, 1933 * one entry per line, using the specified character encoding. 1934 * <p> 1935 * This method buffers the input internally, so there is no need to use a 1936 * {@code BufferedInputStream}. 1937 * 1938 * @param input the {@code InputStream} to read from, not null 1939 * @param charset the charset to use, null means platform default 1940 * @return the list of Strings, never null 1941 * @throws NullPointerException if the input is null 1942 * @throws IOException if an I/O error occurs 1943 * @since 2.3 1944 */ 1945 public static List<String> readLines(final InputStream input, final Charset charset) throws IOException { 1946 final InputStreamReader reader = new InputStreamReader(input, Charsets.toCharset(charset)); 1947 return readLines(reader); 1948 } 1949 1950 /** 1951 * Gets the contents of an {@code InputStream} as a list of Strings, 1952 * one entry per line, using the specified character encoding. 1953 * <p> 1954 * Character encoding names can be found at 1955 * <a href="http://www.iana.org/assignments/character-sets">IANA</a>. 1956 * <p> 1957 * This method buffers the input internally, so there is no need to use a 1958 * {@code BufferedInputStream}. 1959 * 1960 * @param input the {@code InputStream} to read from, not null 1961 * @param charsetName the name of the requested charset, null means platform default 1962 * @return the list of Strings, never null 1963 * @throws NullPointerException if the input is null 1964 * @throws IOException if an I/O error occurs 1965 * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io 1966 * .UnsupportedEncodingException} in version 2.2 if the 1967 * encoding is not supported. 1968 * @since 1.1 1969 */ 1970 public static List<String> readLines(final InputStream input, final String charsetName) throws IOException { 1971 return readLines(input, Charsets.toCharset(charsetName)); 1972 } 1973 1974 /** 1975 * Gets the contents of a {@code Reader} as a list of Strings, 1976 * one entry per line. 1977 * <p> 1978 * This method buffers the input internally, so there is no need to use a 1979 * {@code BufferedReader}. 1980 * 1981 * @param reader the {@code Reader} to read from, not null 1982 * @return the list of Strings, never null 1983 * @throws NullPointerException if the input is null 1984 * @throws IOException if an I/O error occurs 1985 * @since 1.1 1986 */ 1987 @SuppressWarnings("resource") // reader wraps input and is the responsibility of the caller. 1988 public static List<String> readLines(final Reader reader) throws IOException { 1989 final BufferedReader bufReader = toBufferedReader(reader); 1990 final List<String> list = new ArrayList<>(); 1991 String line; 1992 while ((line = bufReader.readLine()) != null) { 1993 list.add(line); 1994 } 1995 return list; 1996 } 1997 1998 /** 1999 * Gets the contents of a classpath resource as a byte array. 2000 * 2001 * <p> 2002 * It is expected the given {@code name} to be absolute. The 2003 * behavior is not well-defined otherwise. 2004 * </p> 2005 * 2006 * @param name name of the desired resource 2007 * @return the requested byte array 2008 * @throws IOException if an I/O error occurs. 2009 * 2010 * @since 2.6 2011 */ 2012 public static byte[] resourceToByteArray(final String name) throws IOException { 2013 return resourceToByteArray(name, null); 2014 } 2015 2016 /** 2017 * Gets the contents of a classpath resource as a byte array. 2018 * 2019 * <p> 2020 * It is expected the given {@code name} to be absolute. The 2021 * behavior is not well-defined otherwise. 2022 * </p> 2023 * 2024 * @param name name of the desired resource 2025 * @param classLoader the class loader that the resolution of the resource is delegated to 2026 * @return the requested byte array 2027 * @throws IOException if an I/O error occurs. 2028 * 2029 * @since 2.6 2030 */ 2031 public static byte[] resourceToByteArray(final String name, final ClassLoader classLoader) throws IOException { 2032 return toByteArray(resourceToURL(name, classLoader)); 2033 } 2034 2035 /** 2036 * Gets the contents of a classpath resource as a String using the 2037 * specified character encoding. 2038 * 2039 * <p> 2040 * It is expected the given {@code name} to be absolute. The 2041 * behavior is not well-defined otherwise. 2042 * </p> 2043 * 2044 * @param name name of the desired resource 2045 * @param charset the charset to use, null means platform default 2046 * @return the requested String 2047 * @throws IOException if an I/O error occurs. 2048 * 2049 * @since 2.6 2050 */ 2051 public static String resourceToString(final String name, final Charset charset) throws IOException { 2052 return resourceToString(name, charset, null); 2053 } 2054 2055 /** 2056 * Gets the contents of a classpath resource as a String using the 2057 * specified character encoding. 2058 * 2059 * <p> 2060 * It is expected the given {@code name} to be absolute. The 2061 * behavior is not well-defined otherwise. 2062 * </p> 2063 * 2064 * @param name name of the desired resource 2065 * @param charset the charset to use, null means platform default 2066 * @param classLoader the class loader that the resolution of the resource is delegated to 2067 * @return the requested String 2068 * @throws IOException if an I/O error occurs. 2069 * 2070 * @since 2.6 2071 */ 2072 public static String resourceToString(final String name, final Charset charset, final ClassLoader classLoader) throws IOException { 2073 return toString(resourceToURL(name, classLoader), charset); 2074 } 2075 2076 /** 2077 * Gets a URL pointing to the given classpath resource. 2078 * 2079 * <p> 2080 * It is expected the given {@code name} to be absolute. The 2081 * behavior is not well-defined otherwise. 2082 * </p> 2083 * 2084 * @param name name of the desired resource 2085 * @return the requested URL 2086 * @throws IOException if an I/O error occurs. 2087 * 2088 * @since 2.6 2089 */ 2090 public static URL resourceToURL(final String name) throws IOException { 2091 return resourceToURL(name, null); 2092 } 2093 2094 /** 2095 * Gets a URL pointing to the given classpath resource. 2096 * 2097 * <p> 2098 * It is expected the given {@code name} to be absolute. The 2099 * behavior is not well-defined otherwise. 2100 * </p> 2101 * 2102 * @param name name of the desired resource 2103 * @param classLoader the class loader that the resolution of the resource is delegated to 2104 * @return the requested URL 2105 * @throws IOException if an I/O error occurs. 2106 * 2107 * @since 2.6 2108 */ 2109 public static URL resourceToURL(final String name, final ClassLoader classLoader) throws IOException { 2110 // What about the thread context class loader? 2111 // What about the system class loader? 2112 final URL resource = classLoader == null ? IOUtils.class.getResource(name) : classLoader.getResource(name); 2113 2114 if (resource == null) { 2115 throw new IOException("Resource not found: " + name); 2116 } 2117 2118 return resource; 2119 } 2120 2121 /** 2122 * Skips bytes from an input byte stream. 2123 * This implementation guarantees that it will read as many bytes 2124 * as possible before giving up; this may not always be the case for 2125 * skip() implementations in subclasses of {@link InputStream}. 2126 * <p> 2127 * Note that the implementation uses {@link InputStream#read(byte[], int, int)} rather 2128 * than delegating to {@link InputStream#skip(long)}. 2129 * This means that the method may be considerably less efficient than using the actual skip implementation, 2130 * this is done to guarantee that the correct number of bytes are skipped. 2131 * </p> 2132 * 2133 * @param input byte stream to skip 2134 * @param toSkip number of bytes to skip. 2135 * @return number of bytes actually skipped. 2136 * @throws IOException if there is a problem reading the file 2137 * @throws IllegalArgumentException if toSkip is negative 2138 * @see InputStream#skip(long) 2139 * @see <a href="https://issues.apache.org/jira/browse/IO-203">IO-203 - Add skipFully() method for InputStreams</a> 2140 * @since 2.0 2141 */ 2142 public static long skip(final InputStream input, final long toSkip) throws IOException { 2143 if (toSkip < 0) { 2144 throw new IllegalArgumentException("Skip count must be non-negative, actual: " + toSkip); 2145 } 2146 /* 2147 * N.B. no need to synchronize access to SKIP_BYTE_BUFFER: - we don't care if the buffer is created multiple 2148 * times (the data is ignored) - we always use the same size buffer, so if it it is recreated it will still be 2149 * OK (if the buffer size were variable, we would need to synch. to ensure some other thread did not create a 2150 * smaller one) 2151 */ 2152 long remain = toSkip; 2153 while (remain > 0) { 2154 // See https://issues.apache.org/jira/browse/IO-203 for why we use read() rather than delegating to skip() 2155 final byte[] byteArray = getByteArray(); 2156 final long n = input.read(byteArray, 0, (int) Math.min(remain, byteArray.length)); 2157 if (n < 0) { // EOF 2158 break; 2159 } 2160 remain -= n; 2161 } 2162 return toSkip - remain; 2163 } 2164 2165 /** 2166 * Skips bytes from a ReadableByteChannel. 2167 * This implementation guarantees that it will read as many bytes 2168 * as possible before giving up. 2169 * 2170 * @param input ReadableByteChannel to skip 2171 * @param toSkip number of bytes to skip. 2172 * @return number of bytes actually skipped. 2173 * @throws IOException if there is a problem reading the ReadableByteChannel 2174 * @throws IllegalArgumentException if toSkip is negative 2175 * @since 2.5 2176 */ 2177 public static long skip(final ReadableByteChannel input, final long toSkip) throws IOException { 2178 if (toSkip < 0) { 2179 throw new IllegalArgumentException("Skip count must be non-negative, actual: " + toSkip); 2180 } 2181 final ByteBuffer skipByteBuffer = ByteBuffer.allocate((int) Math.min(toSkip, DEFAULT_BUFFER_SIZE)); 2182 long remain = toSkip; 2183 while (remain > 0) { 2184 skipByteBuffer.position(0); 2185 skipByteBuffer.limit((int) Math.min(remain, DEFAULT_BUFFER_SIZE)); 2186 final int n = input.read(skipByteBuffer); 2187 if (n == EOF) { 2188 break; 2189 } 2190 remain -= n; 2191 } 2192 return toSkip - remain; 2193 } 2194 2195 /** 2196 * Skips characters from an input character stream. 2197 * This implementation guarantees that it will read as many characters 2198 * as possible before giving up; this may not always be the case for 2199 * skip() implementations in subclasses of {@link Reader}. 2200 * <p> 2201 * Note that the implementation uses {@link Reader#read(char[], int, int)} rather 2202 * than delegating to {@link Reader#skip(long)}. 2203 * This means that the method may be considerably less efficient than using the actual skip implementation, 2204 * this is done to guarantee that the correct number of characters are skipped. 2205 * </p> 2206 * 2207 * @param reader character stream to skip 2208 * @param toSkip number of characters to skip. 2209 * @return number of characters actually skipped. 2210 * @throws IOException if there is a problem reading the file 2211 * @throws IllegalArgumentException if toSkip is negative 2212 * @see Reader#skip(long) 2213 * @see <a href="https://issues.apache.org/jira/browse/IO-203">IO-203 - Add skipFully() method for InputStreams</a> 2214 * @since 2.0 2215 */ 2216 public static long skip(final Reader reader, final long toSkip) throws IOException { 2217 if (toSkip < 0) { 2218 throw new IllegalArgumentException("Skip count must be non-negative, actual: " + toSkip); 2219 } 2220 long remain = toSkip; 2221 while (remain > 0) { 2222 // See https://issues.apache.org/jira/browse/IO-203 for why we use read() rather than delegating to skip() 2223 final char[] charArray = getCharArray(); 2224 final long n = reader.read(charArray, 0, (int) Math.min(remain, charArray.length)); 2225 if (n < 0) { // EOF 2226 break; 2227 } 2228 remain -= n; 2229 } 2230 return toSkip - remain; 2231 } 2232 2233 /** 2234 * Skips the requested number of bytes or fail if there are not enough left. 2235 * <p> 2236 * This allows for the possibility that {@link InputStream#skip(long)} may 2237 * not skip as many bytes as requested (most likely because of reaching EOF). 2238 * <p> 2239 * Note that the implementation uses {@link #skip(InputStream, long)}. 2240 * This means that the method may be considerably less efficient than using the actual skip implementation, 2241 * this is done to guarantee that the correct number of characters are skipped. 2242 * </p> 2243 * 2244 * @param input stream to skip 2245 * @param toSkip the number of bytes to skip 2246 * @throws IOException if there is a problem reading the file 2247 * @throws IllegalArgumentException if toSkip is negative 2248 * @throws EOFException if the number of bytes skipped was incorrect 2249 * @see InputStream#skip(long) 2250 * @since 2.0 2251 */ 2252 public static void skipFully(final InputStream input, final long toSkip) throws IOException { 2253 if (toSkip < 0) { 2254 throw new IllegalArgumentException("Bytes to skip must not be negative: " + toSkip); 2255 } 2256 final long skipped = skip(input, toSkip); 2257 if (skipped != toSkip) { 2258 throw new EOFException("Bytes to skip: " + toSkip + " actual: " + skipped); 2259 } 2260 } 2261 2262 /** 2263 * Skips the requested number of bytes or fail if there are not enough left. 2264 * 2265 * @param input ReadableByteChannel to skip 2266 * @param toSkip the number of bytes to skip 2267 * @throws IOException if there is a problem reading the ReadableByteChannel 2268 * @throws IllegalArgumentException if toSkip is negative 2269 * @throws EOFException if the number of bytes skipped was incorrect 2270 * @since 2.5 2271 */ 2272 public static void skipFully(final ReadableByteChannel input, final long toSkip) throws IOException { 2273 if (toSkip < 0) { 2274 throw new IllegalArgumentException("Bytes to skip must not be negative: " + toSkip); 2275 } 2276 final long skipped = skip(input, toSkip); 2277 if (skipped != toSkip) { 2278 throw new EOFException("Bytes to skip: " + toSkip + " actual: " + skipped); 2279 } 2280 } 2281 2282 /** 2283 * Skips the requested number of characters or fail if there are not enough left. 2284 * <p> 2285 * This allows for the possibility that {@link Reader#skip(long)} may 2286 * not skip as many characters as requested (most likely because of reaching EOF). 2287 * <p> 2288 * Note that the implementation uses {@link #skip(Reader, long)}. 2289 * This means that the method may be considerably less efficient than using the actual skip implementation, 2290 * this is done to guarantee that the correct number of characters are skipped. 2291 * </p> 2292 * 2293 * @param reader stream to skip 2294 * @param toSkip the number of characters to skip 2295 * @throws IOException if there is a problem reading the file 2296 * @throws IllegalArgumentException if toSkip is negative 2297 * @throws EOFException if the number of characters skipped was incorrect 2298 * @see Reader#skip(long) 2299 * @since 2.0 2300 */ 2301 public static void skipFully(final Reader reader, final long toSkip) throws IOException { 2302 final long skipped = skip(reader, toSkip); 2303 if (skipped != toSkip) { 2304 throw new EOFException("Chars to skip: " + toSkip + " actual: " + skipped); 2305 } 2306 } 2307 2308 /** 2309 * Fetches entire contents of an {@code InputStream} and represent 2310 * same data as result InputStream. 2311 * <p> 2312 * This method is useful where, 2313 * <ul> 2314 * <li>Source InputStream is slow.</li> 2315 * <li>It has network resources associated, so we cannot keep it open for 2316 * long time.</li> 2317 * <li>It has network timeout associated.</li> 2318 * </ul> 2319 * It can be used in favor of {@link #toByteArray(InputStream)}, since it 2320 * avoids unnecessary allocation and copy of byte[].<br> 2321 * This method buffers the input internally, so there is no need to use a 2322 * {@code BufferedInputStream}. 2323 * 2324 * @param input Stream to be fully buffered. 2325 * @return A fully buffered stream. 2326 * @throws IOException if an I/O error occurs. 2327 * @since 2.0 2328 */ 2329 public static InputStream toBufferedInputStream(final InputStream input) throws IOException { 2330 return ByteArrayOutputStream.toBufferedInputStream(input); 2331 } 2332 2333 /** 2334 * Fetches entire contents of an {@code InputStream} and represent 2335 * same data as result InputStream. 2336 * <p> 2337 * This method is useful where, 2338 * <ul> 2339 * <li>Source InputStream is slow.</li> 2340 * <li>It has network resources associated, so we cannot keep it open for 2341 * long time.</li> 2342 * <li>It has network timeout associated.</li> 2343 * </ul> 2344 * It can be used in favor of {@link #toByteArray(InputStream)}, since it 2345 * avoids unnecessary allocation and copy of byte[].<br> 2346 * This method buffers the input internally, so there is no need to use a 2347 * {@code BufferedInputStream}. 2348 * 2349 * @param input Stream to be fully buffered. 2350 * @param size the initial buffer size 2351 * @return A fully buffered stream. 2352 * @throws IOException if an I/O error occurs. 2353 * @since 2.5 2354 */ 2355 public static InputStream toBufferedInputStream(final InputStream input, final int size) throws IOException { 2356 return ByteArrayOutputStream.toBufferedInputStream(input, size); 2357 } 2358 2359 /** 2360 * Returns the given reader if it is a {@link BufferedReader}, otherwise creates a BufferedReader from the given 2361 * reader. 2362 * 2363 * @param reader the reader to wrap or return (not null) 2364 * @return the given reader or a new {@link BufferedReader} for the given reader 2365 * @throws NullPointerException if the input parameter is null 2366 * @see #buffer(Reader) 2367 * @since 2.2 2368 */ 2369 public static BufferedReader toBufferedReader(final Reader reader) { 2370 return reader instanceof BufferedReader ? (BufferedReader) reader : new BufferedReader(reader); 2371 } 2372 2373 /** 2374 * Returns the given reader if it is a {@link BufferedReader}, otherwise creates a BufferedReader from the given 2375 * reader. 2376 * 2377 * @param reader the reader to wrap or return (not null) 2378 * @param size the buffer size, if a new BufferedReader is created. 2379 * @return the given reader or a new {@link BufferedReader} for the given reader 2380 * @throws NullPointerException if the input parameter is null 2381 * @see #buffer(Reader) 2382 * @since 2.5 2383 */ 2384 public static BufferedReader toBufferedReader(final Reader reader, final int size) { 2385 return reader instanceof BufferedReader ? (BufferedReader) reader : new BufferedReader(reader, size); 2386 } 2387 2388 /** 2389 * Gets the contents of an {@code InputStream} as a {@code byte[]}. 2390 * <p> 2391 * This method buffers the input internally, so there is no need to use a 2392 * {@code BufferedInputStream}. 2393 * </p> 2394 * 2395 * @param inputStream the {@code InputStream} to read. 2396 * @return the requested byte array. 2397 * @throws NullPointerException if the InputStream is {@code null}. 2398 * @throws IOException if an I/O error occurs or reading more than {@link Integer#MAX_VALUE} occurs. 2399 */ 2400 public static byte[] toByteArray(final InputStream inputStream) throws IOException { 2401 // We use a ThresholdingOutputStream to avoid reading AND writing more than Integer.MAX_VALUE. 2402 try (final UnsynchronizedByteArrayOutputStream ubaOutput = new UnsynchronizedByteArrayOutputStream(); 2403 final ThresholdingOutputStream thresholdOuput = new ThresholdingOutputStream(Integer.MAX_VALUE, os -> { 2404 throw new IllegalArgumentException( 2405 String.format("Cannot read more than %,d into a byte array", Integer.MAX_VALUE)); 2406 }, os -> ubaOutput)) { 2407 copy(inputStream, thresholdOuput); 2408 return ubaOutput.toByteArray(); 2409 } 2410 } 2411 2412 /** 2413 * Gets the contents of an {@code InputStream} as a {@code byte[]}. Use this method instead of 2414 * {@code toByteArray(InputStream)} when {@code InputStream} size is known 2415 * 2416 * @param input the {@code InputStream} to read. 2417 * @param size the size of {@code InputStream}. 2418 * @return the requested byte array. 2419 * @throws IOException if an I/O error occurs or {@code InputStream} size differ from parameter size. 2420 * @throws IllegalArgumentException if size is less than zero. 2421 * @since 2.1 2422 */ 2423 public static byte[] toByteArray(final InputStream input, final int size) throws IOException { 2424 2425 if (size < 0) { 2426 throw new IllegalArgumentException("Size must be equal or greater than zero: " + size); 2427 } 2428 2429 if (size == 0) { 2430 return EMPTY_BYTE_ARRAY; 2431 } 2432 2433 final byte[] data = IOUtils.byteArray(size); 2434 int offset = 0; 2435 int read; 2436 2437 while (offset < size && (read = input.read(data, offset, size - offset)) != EOF) { 2438 offset += read; 2439 } 2440 2441 if (offset != size) { 2442 throw new IOException("Unexpected read size, current: " + offset + ", expected: " + size); 2443 } 2444 2445 return data; 2446 } 2447 2448 /** 2449 * Gets contents of an {@code InputStream} as a {@code byte[]}. 2450 * Use this method instead of {@code toByteArray(InputStream)} 2451 * when {@code InputStream} size is known. 2452 * <b>NOTE:</b> the method checks that the length can safely be cast to an int without truncation 2453 * before using {@link IOUtils#toByteArray(java.io.InputStream, int)} to read into the byte array. 2454 * (Arrays can have no more than Integer.MAX_VALUE entries anyway) 2455 * 2456 * @param input the {@code InputStream} to read from 2457 * @param size the size of {@code InputStream} 2458 * @return the requested byte array 2459 * @throws IOException if an I/O error occurs or {@code InputStream} size differ from parameter 2460 * size 2461 * @throws IllegalArgumentException if size is less than zero or size is greater than Integer.MAX_VALUE 2462 * @see IOUtils#toByteArray(java.io.InputStream, int) 2463 * @since 2.1 2464 */ 2465 public static byte[] toByteArray(final InputStream input, final long size) throws IOException { 2466 2467 if (size > Integer.MAX_VALUE) { 2468 throw new IllegalArgumentException("Size cannot be greater than Integer max value: " + size); 2469 } 2470 2471 return toByteArray(input, (int) size); 2472 } 2473 2474 /** 2475 * Gets the contents of a {@code Reader} as a {@code byte[]} 2476 * using the default character encoding of the platform. 2477 * <p> 2478 * This method buffers the input internally, so there is no need to use a 2479 * {@code BufferedReader}. 2480 * 2481 * @param reader the {@code Reader} to read from 2482 * @return the requested byte array 2483 * @throws NullPointerException if the input is null 2484 * @throws IOException if an I/O error occurs 2485 * @deprecated 2.5 use {@link #toByteArray(Reader, Charset)} instead 2486 */ 2487 @Deprecated 2488 public static byte[] toByteArray(final Reader reader) throws IOException { 2489 return toByteArray(reader, Charset.defaultCharset()); 2490 } 2491 2492 /** 2493 * Gets the contents of a {@code Reader} as a {@code byte[]} 2494 * using the specified character encoding. 2495 * <p> 2496 * This method buffers the input internally, so there is no need to use a 2497 * {@code BufferedReader}. 2498 * 2499 * @param reader the {@code Reader} to read from 2500 * @param charset the charset to use, null means platform default 2501 * @return the requested byte array 2502 * @throws NullPointerException if the input is null 2503 * @throws IOException if an I/O error occurs 2504 * @since 2.3 2505 */ 2506 public static byte[] toByteArray(final Reader reader, final Charset charset) throws IOException { 2507 try (final ByteArrayOutputStream output = new ByteArrayOutputStream()) { 2508 copy(reader, output, charset); 2509 return output.toByteArray(); 2510 } 2511 } 2512 2513 /** 2514 * Gets the contents of a {@code Reader} as a {@code byte[]} 2515 * using the specified character encoding. 2516 * <p> 2517 * Character encoding names can be found at 2518 * <a href="http://www.iana.org/assignments/character-sets">IANA</a>. 2519 * <p> 2520 * This method buffers the input internally, so there is no need to use a 2521 * {@code BufferedReader}. 2522 * 2523 * @param reader the {@code Reader} to read from 2524 * @param charsetName the name of the requested charset, null means platform default 2525 * @return the requested byte array 2526 * @throws NullPointerException if the input is null 2527 * @throws IOException if an I/O error occurs 2528 * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io 2529 * .UnsupportedEncodingException} in version 2.2 if the 2530 * encoding is not supported. 2531 * @since 1.1 2532 */ 2533 public static byte[] toByteArray(final Reader reader, final String charsetName) throws IOException { 2534 return toByteArray(reader, Charsets.toCharset(charsetName)); 2535 } 2536 2537 /** 2538 * Gets the contents of a {@code String} as a {@code byte[]} 2539 * using the default character encoding of the platform. 2540 * <p> 2541 * This is the same as {@link String#getBytes()}. 2542 * 2543 * @param input the {@code String} to convert 2544 * @return the requested byte array 2545 * @throws NullPointerException if the input is null 2546 * @throws IOException Never thrown. 2547 * @deprecated 2.5 Use {@link String#getBytes()} instead 2548 */ 2549 @Deprecated 2550 public static byte[] toByteArray(final String input) throws IOException { 2551 // make explicit the use of the default charset 2552 return input.getBytes(Charset.defaultCharset()); 2553 } 2554 2555 /** 2556 * Gets the contents of a {@code URI} as a {@code byte[]}. 2557 * 2558 * @param uri the {@code URI} to read 2559 * @return the requested byte array 2560 * @throws NullPointerException if the uri is null 2561 * @throws IOException if an I/O exception occurs 2562 * @since 2.4 2563 */ 2564 public static byte[] toByteArray(final URI uri) throws IOException { 2565 return IOUtils.toByteArray(uri.toURL()); 2566 } 2567 2568 /** 2569 * Gets the contents of a {@code URL} as a {@code byte[]}. 2570 * 2571 * @param url the {@code URL} to read 2572 * @return the requested byte array 2573 * @throws NullPointerException if the input is null 2574 * @throws IOException if an I/O exception occurs 2575 * @since 2.4 2576 */ 2577 public static byte[] toByteArray(final URL url) throws IOException { 2578 final URLConnection conn = url.openConnection(); 2579 try { 2580 return IOUtils.toByteArray(conn); 2581 } finally { 2582 close(conn); 2583 } 2584 } 2585 2586 /** 2587 * Gets the contents of a {@code URLConnection} as a {@code byte[]}. 2588 * 2589 * @param urlConn the {@code URLConnection} to read. 2590 * @return the requested byte array. 2591 * @throws NullPointerException if the urlConn is null. 2592 * @throws IOException if an I/O exception occurs. 2593 * @since 2.4 2594 */ 2595 public static byte[] toByteArray(final URLConnection urlConn) throws IOException { 2596 try (InputStream inputStream = urlConn.getInputStream()) { 2597 return IOUtils.toByteArray(inputStream); 2598 } 2599 } 2600 2601 /** 2602 * Gets the contents of an {@code InputStream} as a character array 2603 * using the default character encoding of the platform. 2604 * <p> 2605 * This method buffers the input internally, so there is no need to use a 2606 * {@code BufferedInputStream}. 2607 * 2608 * @param inputStream the {@code InputStream} to read from 2609 * @return the requested character array 2610 * @throws NullPointerException if the input is null 2611 * @throws IOException if an I/O error occurs 2612 * @since 1.1 2613 * @deprecated 2.5 use {@link #toCharArray(InputStream, Charset)} instead 2614 */ 2615 @Deprecated 2616 public static char[] toCharArray(final InputStream inputStream) throws IOException { 2617 return toCharArray(inputStream, Charset.defaultCharset()); 2618 } 2619 2620 /** 2621 * Gets the contents of an {@code InputStream} as a character array 2622 * using the specified character encoding. 2623 * <p> 2624 * This method buffers the input internally, so there is no need to use a 2625 * {@code BufferedInputStream}. 2626 * 2627 * @param inputStream the {@code InputStream} to read from 2628 * @param charset the charset to use, null means platform default 2629 * @return the requested character array 2630 * @throws NullPointerException if the input is null 2631 * @throws IOException if an I/O error occurs 2632 * @since 2.3 2633 */ 2634 public static char[] toCharArray(final InputStream inputStream, final Charset charset) 2635 throws IOException { 2636 final CharArrayWriter writer = new CharArrayWriter(); 2637 copy(inputStream, writer, charset); 2638 return writer.toCharArray(); 2639 } 2640 2641 /** 2642 * Gets the contents of an {@code InputStream} as a character array 2643 * using the specified character encoding. 2644 * <p> 2645 * Character encoding names can be found at 2646 * <a href="http://www.iana.org/assignments/character-sets">IANA</a>. 2647 * <p> 2648 * This method buffers the input internally, so there is no need to use a 2649 * {@code BufferedInputStream}. 2650 * 2651 * @param inputStream the {@code InputStream} to read from 2652 * @param charsetName the name of the requested charset, null means platform default 2653 * @return the requested character array 2654 * @throws NullPointerException if the input is null 2655 * @throws IOException if an I/O error occurs 2656 * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io 2657 * .UnsupportedEncodingException} in version 2.2 if the 2658 * encoding is not supported. 2659 * @since 1.1 2660 */ 2661 public static char[] toCharArray(final InputStream inputStream, final String charsetName) throws IOException { 2662 return toCharArray(inputStream, Charsets.toCharset(charsetName)); 2663 } 2664 2665 /** 2666 * Gets the contents of a {@code Reader} as a character array. 2667 * <p> 2668 * This method buffers the input internally, so there is no need to use a 2669 * {@code BufferedReader}. 2670 * 2671 * @param reader the {@code Reader} to read from 2672 * @return the requested character array 2673 * @throws NullPointerException if the input is null 2674 * @throws IOException if an I/O error occurs 2675 * @since 1.1 2676 */ 2677 public static char[] toCharArray(final Reader reader) throws IOException { 2678 final CharArrayWriter sw = new CharArrayWriter(); 2679 copy(reader, sw); 2680 return sw.toCharArray(); 2681 } 2682 2683 /** 2684 * Converts the specified CharSequence to an input stream, encoded as bytes 2685 * using the default character encoding of the platform. 2686 * 2687 * @param input the CharSequence to convert 2688 * @return an input stream 2689 * @since 2.0 2690 * @deprecated 2.5 use {@link #toInputStream(CharSequence, Charset)} instead 2691 */ 2692 @Deprecated 2693 public static InputStream toInputStream(final CharSequence input) { 2694 return toInputStream(input, Charset.defaultCharset()); 2695 } 2696 2697 /** 2698 * Converts the specified CharSequence to an input stream, encoded as bytes 2699 * using the specified character encoding. 2700 * 2701 * @param input the CharSequence to convert 2702 * @param charset the charset to use, null means platform default 2703 * @return an input stream 2704 * @since 2.3 2705 */ 2706 public static InputStream toInputStream(final CharSequence input, final Charset charset) { 2707 return toInputStream(input.toString(), charset); 2708 } 2709 2710 /** 2711 * Converts the specified CharSequence to an input stream, encoded as bytes 2712 * using the specified character encoding. 2713 * <p> 2714 * Character encoding names can be found at 2715 * <a href="http://www.iana.org/assignments/character-sets">IANA</a>. 2716 * 2717 * @param input the CharSequence to convert 2718 * @param charsetName the name of the requested charset, null means platform default 2719 * @return an input stream 2720 * @throws IOException Never thrown. 2721 * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io 2722 * .UnsupportedEncodingException} in version 2.2 if the 2723 * encoding is not supported. 2724 * @since 2.0 2725 */ 2726 public static InputStream toInputStream(final CharSequence input, final String charsetName) throws IOException { 2727 return toInputStream(input, Charsets.toCharset(charsetName)); 2728 } 2729 2730 /** 2731 * Converts the specified string to an input stream, encoded as bytes 2732 * using the default character encoding of the platform. 2733 * 2734 * @param input the string to convert 2735 * @return an input stream 2736 * @since 1.1 2737 * @deprecated 2.5 use {@link #toInputStream(String, Charset)} instead 2738 */ 2739 @Deprecated 2740 public static InputStream toInputStream(final String input) { 2741 return toInputStream(input, Charset.defaultCharset()); 2742 } 2743 2744 /** 2745 * Converts the specified string to an input stream, encoded as bytes 2746 * using the specified character encoding. 2747 * 2748 * @param input the string to convert 2749 * @param charset the charset to use, null means platform default 2750 * @return an input stream 2751 * @since 2.3 2752 */ 2753 public static InputStream toInputStream(final String input, final Charset charset) { 2754 return new ByteArrayInputStream(input.getBytes(Charsets.toCharset(charset))); 2755 } 2756 2757 /** 2758 * Converts the specified string to an input stream, encoded as bytes 2759 * using the specified character encoding. 2760 * <p> 2761 * Character encoding names can be found at 2762 * <a href="http://www.iana.org/assignments/character-sets">IANA</a>. 2763 * 2764 * @param input the string to convert 2765 * @param charsetName the name of the requested charset, null means platform default 2766 * @return an input stream 2767 * @throws IOException Never thrown. 2768 * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io 2769 * .UnsupportedEncodingException} in version 2.2 if the 2770 * encoding is not supported. 2771 * @since 1.1 2772 */ 2773 public static InputStream toInputStream(final String input, final String charsetName) throws IOException { 2774 final byte[] bytes = input.getBytes(Charsets.toCharset(charsetName)); 2775 return new ByteArrayInputStream(bytes); 2776 } 2777 2778 /** 2779 * Gets the contents of a {@code byte[]} as a String 2780 * using the default character encoding of the platform. 2781 * 2782 * @param input the byte array to read from 2783 * @return the requested String 2784 * @throws NullPointerException if the input is null 2785 * @throws IOException Never thrown. 2786 * @deprecated 2.5 Use {@link String#String(byte[])} instead 2787 */ 2788 @Deprecated 2789 public static String toString(final byte[] input) throws IOException { 2790 // make explicit the use of the default charset 2791 return new String(input, Charset.defaultCharset()); 2792 } 2793 2794 /** 2795 * Gets the contents of a {@code byte[]} as a String 2796 * using the specified character encoding. 2797 * <p> 2798 * Character encoding names can be found at 2799 * <a href="http://www.iana.org/assignments/character-sets">IANA</a>. 2800 * 2801 * @param input the byte array to read from 2802 * @param charsetName the name of the requested charset, null means platform default 2803 * @return the requested String 2804 * @throws NullPointerException if the input is null 2805 * @throws IOException Never thrown. 2806 */ 2807 public static String toString(final byte[] input, final String charsetName) throws IOException { 2808 return new String(input, Charsets.toCharset(charsetName)); 2809 } 2810 2811 /** 2812 * Gets the contents of an {@code InputStream} as a String 2813 * using the default character encoding of the platform. 2814 * <p> 2815 * This method buffers the input internally, so there is no need to use a 2816 * {@code BufferedInputStream}. 2817 * 2818 * @param input the {@code InputStream} to read from 2819 * @return the requested String 2820 * @throws NullPointerException if the input is null 2821 * @throws IOException if an I/O error occurs 2822 * @deprecated 2.5 use {@link #toString(InputStream, Charset)} instead 2823 */ 2824 @Deprecated 2825 public static String toString(final InputStream input) throws IOException { 2826 return toString(input, Charset.defaultCharset()); 2827 } 2828 2829 /** 2830 * Gets the contents of an {@code InputStream} as a String 2831 * using the specified character encoding. 2832 * <p> 2833 * This method buffers the input internally, so there is no need to use a 2834 * {@code BufferedInputStream}. 2835 * </p> 2836 * 2837 * @param input the {@code InputStream} to read from 2838 * @param charset the charset to use, null means platform default 2839 * @return the requested String 2840 * @throws NullPointerException if the input is null 2841 * @throws IOException if an I/O error occurs 2842 * @since 2.3 2843 */ 2844 public static String toString(final InputStream input, final Charset charset) throws IOException { 2845 try (final StringBuilderWriter sw = new StringBuilderWriter()) { 2846 copy(input, sw, charset); 2847 return sw.toString(); 2848 } 2849 } 2850 2851 /** 2852 * Gets the contents of an {@code InputStream} as a String 2853 * using the specified character encoding. 2854 * <p> 2855 * Character encoding names can be found at 2856 * <a href="http://www.iana.org/assignments/character-sets">IANA</a>. 2857 * <p> 2858 * This method buffers the input internally, so there is no need to use a 2859 * {@code BufferedInputStream}. 2860 * 2861 * @param input the {@code InputStream} to read from 2862 * @param charsetName the name of the requested charset, null means platform default 2863 * @return the requested String 2864 * @throws NullPointerException if the input is null 2865 * @throws IOException if an I/O error occurs 2866 * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io 2867 * .UnsupportedEncodingException} in version 2.2 if the 2868 * encoding is not supported. 2869 */ 2870 public static String toString(final InputStream input, final String charsetName) 2871 throws IOException { 2872 return toString(input, Charsets.toCharset(charsetName)); 2873 } 2874 2875 /** 2876 * Gets the contents of a {@code Reader} as a String. 2877 * <p> 2878 * This method buffers the input internally, so there is no need to use a 2879 * {@code BufferedReader}. 2880 * 2881 * @param reader the {@code Reader} to read from 2882 * @return the requested String 2883 * @throws NullPointerException if the input is null 2884 * @throws IOException if an I/O error occurs 2885 */ 2886 public static String toString(final Reader reader) throws IOException { 2887 try (final StringBuilderWriter sw = new StringBuilderWriter()) { 2888 copy(reader, sw); 2889 return sw.toString(); 2890 } 2891 } 2892 2893 /** 2894 * Gets the contents at the given URI. 2895 * 2896 * @param uri The URI source. 2897 * @return The contents of the URL as a String. 2898 * @throws IOException if an I/O exception occurs. 2899 * @since 2.1 2900 * @deprecated 2.5 use {@link #toString(URI, Charset)} instead 2901 */ 2902 @Deprecated 2903 public static String toString(final URI uri) throws IOException { 2904 return toString(uri, Charset.defaultCharset()); 2905 } 2906 2907 /** 2908 * Gets the contents at the given URI. 2909 * 2910 * @param uri The URI source. 2911 * @param encoding The encoding name for the URL contents. 2912 * @return The contents of the URL as a String. 2913 * @throws IOException if an I/O exception occurs. 2914 * @since 2.3. 2915 */ 2916 public static String toString(final URI uri, final Charset encoding) throws IOException { 2917 return toString(uri.toURL(), Charsets.toCharset(encoding)); 2918 } 2919 2920 /** 2921 * Gets the contents at the given URI. 2922 * 2923 * @param uri The URI source. 2924 * @param charsetName The encoding name for the URL contents. 2925 * @return The contents of the URL as a String. 2926 * @throws IOException if an I/O exception occurs. 2927 * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io 2928 * .UnsupportedEncodingException} in version 2.2 if the 2929 * encoding is not supported. 2930 * @since 2.1 2931 */ 2932 public static String toString(final URI uri, final String charsetName) throws IOException { 2933 return toString(uri, Charsets.toCharset(charsetName)); 2934 } 2935 2936 /** 2937 * Gets the contents at the given URL. 2938 * 2939 * @param url The URL source. 2940 * @return The contents of the URL as a String. 2941 * @throws IOException if an I/O exception occurs. 2942 * @since 2.1 2943 * @deprecated 2.5 use {@link #toString(URL, Charset)} instead 2944 */ 2945 @Deprecated 2946 public static String toString(final URL url) throws IOException { 2947 return toString(url, Charset.defaultCharset()); 2948 } 2949 2950 /** 2951 * Gets the contents at the given URL. 2952 * 2953 * @param url The URL source. 2954 * @param encoding The encoding name for the URL contents. 2955 * @return The contents of the URL as a String. 2956 * @throws IOException if an I/O exception occurs. 2957 * @since 2.3 2958 */ 2959 public static String toString(final URL url, final Charset encoding) throws IOException { 2960 try (InputStream inputStream = url.openStream()) { 2961 return toString(inputStream, encoding); 2962 } 2963 } 2964 2965 /** 2966 * Gets the contents at the given URL. 2967 * 2968 * @param url The URL source. 2969 * @param charsetName The encoding name for the URL contents. 2970 * @return The contents of the URL as a String. 2971 * @throws IOException if an I/O exception occurs. 2972 * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io 2973 * .UnsupportedEncodingException} in version 2.2 if the 2974 * encoding is not supported. 2975 * @since 2.1 2976 */ 2977 public static String toString(final URL url, final String charsetName) throws IOException { 2978 return toString(url, Charsets.toCharset(charsetName)); 2979 } 2980 2981 /** 2982 * Writes bytes from a {@code byte[]} to an {@code OutputStream}. 2983 * 2984 * @param data the byte array to write, do not modify during output, 2985 * null ignored 2986 * @param output the {@code OutputStream} to write to 2987 * @throws NullPointerException if output is null 2988 * @throws IOException if an I/O error occurs 2989 * @since 1.1 2990 */ 2991 public static void write(final byte[] data, final OutputStream output) 2992 throws IOException { 2993 if (data != null) { 2994 output.write(data); 2995 } 2996 } 2997 2998 /** 2999 * Writes bytes from a {@code byte[]} to chars on a {@code Writer} 3000 * using the default character encoding of the platform. 3001 * <p> 3002 * This method uses {@link String#String(byte[])}. 3003 * 3004 * @param data the byte array to write, do not modify during output, 3005 * null ignored 3006 * @param writer the {@code Writer} to write to 3007 * @throws NullPointerException if output is null 3008 * @throws IOException if an I/O error occurs 3009 * @since 1.1 3010 * @deprecated 2.5 use {@link #write(byte[], Writer, Charset)} instead 3011 */ 3012 @Deprecated 3013 public static void write(final byte[] data, final Writer writer) throws IOException { 3014 write(data, writer, Charset.defaultCharset()); 3015 } 3016 3017 /** 3018 * Writes bytes from a {@code byte[]} to chars on a {@code Writer} 3019 * using the specified character encoding. 3020 * <p> 3021 * This method uses {@link String#String(byte[], String)}. 3022 * 3023 * @param data the byte array to write, do not modify during output, 3024 * null ignored 3025 * @param writer the {@code Writer} to write to 3026 * @param charset the charset to use, null means platform default 3027 * @throws NullPointerException if output is null 3028 * @throws IOException if an I/O error occurs 3029 * @since 2.3 3030 */ 3031 public static void write(final byte[] data, final Writer writer, final Charset charset) throws IOException { 3032 if (data != null) { 3033 writer.write(new String(data, Charsets.toCharset(charset))); 3034 } 3035 } 3036 3037 /** 3038 * Writes bytes from a {@code byte[]} to chars on a {@code Writer} 3039 * using the specified character encoding. 3040 * <p> 3041 * Character encoding names can be found at 3042 * <a href="http://www.iana.org/assignments/character-sets">IANA</a>. 3043 * <p> 3044 * This method uses {@link String#String(byte[], String)}. 3045 * 3046 * @param data the byte array to write, do not modify during output, 3047 * null ignored 3048 * @param writer the {@code Writer} to write to 3049 * @param charsetName the name of the requested charset, null means platform default 3050 * @throws NullPointerException if output is null 3051 * @throws IOException if an I/O error occurs 3052 * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io 3053 * .UnsupportedEncodingException} in version 2.2 if the 3054 * encoding is not supported. 3055 * @since 1.1 3056 */ 3057 public static void write(final byte[] data, final Writer writer, final String charsetName) throws IOException { 3058 write(data, writer, Charsets.toCharset(charsetName)); 3059 } 3060 3061 /** 3062 * Writes chars from a {@code char[]} to bytes on an 3063 * {@code OutputStream}. 3064 * <p> 3065 * This method uses {@link String#String(char[])} and 3066 * {@link String#getBytes()}. 3067 * 3068 * @param data the char array to write, do not modify during output, 3069 * null ignored 3070 * @param output the {@code OutputStream} to write to 3071 * @throws NullPointerException if output is null 3072 * @throws IOException if an I/O error occurs 3073 * @since 1.1 3074 * @deprecated 2.5 use {@link #write(char[], OutputStream, Charset)} instead 3075 */ 3076 @Deprecated 3077 public static void write(final char[] data, final OutputStream output) 3078 throws IOException { 3079 write(data, output, Charset.defaultCharset()); 3080 } 3081 3082 /** 3083 * Writes chars from a {@code char[]} to bytes on an 3084 * {@code OutputStream} using the specified character encoding. 3085 * <p> 3086 * This method uses {@link String#String(char[])} and 3087 * {@link String#getBytes(String)}. 3088 * 3089 * @param data the char array to write, do not modify during output, 3090 * null ignored 3091 * @param output the {@code OutputStream} to write to 3092 * @param charset the charset to use, null means platform default 3093 * @throws NullPointerException if output is null 3094 * @throws IOException if an I/O error occurs 3095 * @since 2.3 3096 */ 3097 public static void write(final char[] data, final OutputStream output, final Charset charset) throws IOException { 3098 if (data != null) { 3099 output.write(new String(data).getBytes(Charsets.toCharset(charset))); 3100 } 3101 } 3102 3103 /** 3104 * Writes chars from a {@code char[]} to bytes on an 3105 * {@code OutputStream} using the specified character encoding. 3106 * <p> 3107 * Character encoding names can be found at 3108 * <a href="http://www.iana.org/assignments/character-sets">IANA</a>. 3109 * <p> 3110 * This method uses {@link String#String(char[])} and 3111 * {@link String#getBytes(String)}. 3112 * 3113 * @param data the char array to write, do not modify during output, 3114 * null ignored 3115 * @param output the {@code OutputStream} to write to 3116 * @param charsetName the name of the requested charset, null means platform default 3117 * @throws NullPointerException if output is null 3118 * @throws IOException if an I/O error occurs 3119 * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io 3120 * .UnsupportedEncodingException} in version 2.2 if the encoding is not supported. 3121 * @since 1.1 3122 */ 3123 public static void write(final char[] data, final OutputStream output, final String charsetName) 3124 throws IOException { 3125 write(data, output, Charsets.toCharset(charsetName)); 3126 } 3127 3128 /** 3129 * Writes chars from a {@code char[]} to a {@code Writer} 3130 * 3131 * @param data the char array to write, do not modify during output, 3132 * null ignored 3133 * @param writer the {@code Writer} to write to 3134 * @throws NullPointerException if output is null 3135 * @throws IOException if an I/O error occurs 3136 * @since 1.1 3137 */ 3138 public static void write(final char[] data, final Writer writer) throws IOException { 3139 if (data != null) { 3140 writer.write(data); 3141 } 3142 } 3143 3144 /** 3145 * Writes chars from a {@code CharSequence} to bytes on an 3146 * {@code OutputStream} using the default character encoding of the 3147 * platform. 3148 * <p> 3149 * This method uses {@link String#getBytes()}. 3150 * 3151 * @param data the {@code CharSequence} to write, null ignored 3152 * @param output the {@code OutputStream} to write to 3153 * @throws NullPointerException if output is null 3154 * @throws IOException if an I/O error occurs 3155 * @since 2.0 3156 * @deprecated 2.5 use {@link #write(CharSequence, OutputStream, Charset)} instead 3157 */ 3158 @Deprecated 3159 public static void write(final CharSequence data, final OutputStream output) 3160 throws IOException { 3161 write(data, output, Charset.defaultCharset()); 3162 } 3163 3164 /** 3165 * Writes chars from a {@code CharSequence} to bytes on an 3166 * {@code OutputStream} using the specified character encoding. 3167 * <p> 3168 * This method uses {@link String#getBytes(String)}. 3169 * 3170 * @param data the {@code CharSequence} to write, null ignored 3171 * @param output the {@code OutputStream} to write to 3172 * @param charset the charset to use, null means platform default 3173 * @throws NullPointerException if output is null 3174 * @throws IOException if an I/O error occurs 3175 * @since 2.3 3176 */ 3177 public static void write(final CharSequence data, final OutputStream output, final Charset charset) 3178 throws IOException { 3179 if (data != null) { 3180 write(data.toString(), output, charset); 3181 } 3182 } 3183 3184 /** 3185 * Writes chars from a {@code CharSequence} to bytes on an 3186 * {@code OutputStream} using the specified character encoding. 3187 * <p> 3188 * Character encoding names can be found at 3189 * <a href="http://www.iana.org/assignments/character-sets">IANA</a>. 3190 * <p> 3191 * This method uses {@link String#getBytes(String)}. 3192 * 3193 * @param data the {@code CharSequence} to write, null ignored 3194 * @param output the {@code OutputStream} to write to 3195 * @param charsetName the name of the requested charset, null means platform default 3196 * @throws NullPointerException if output is null 3197 * @throws IOException if an I/O error occurs 3198 * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io 3199 * .UnsupportedEncodingException} in version 2.2 if the encoding is not supported. 3200 * @since 2.0 3201 */ 3202 public static void write(final CharSequence data, final OutputStream output, final String charsetName) 3203 throws IOException { 3204 write(data, output, Charsets.toCharset(charsetName)); 3205 } 3206 3207 /** 3208 * Writes chars from a {@code CharSequence} to a {@code Writer}. 3209 * 3210 * @param data the {@code CharSequence} to write, null ignored 3211 * @param writer the {@code Writer} to write to 3212 * @throws NullPointerException if output is null 3213 * @throws IOException if an I/O error occurs 3214 * @since 2.0 3215 */ 3216 public static void write(final CharSequence data, final Writer writer) throws IOException { 3217 if (data != null) { 3218 write(data.toString(), writer); 3219 } 3220 } 3221 3222 3223 /** 3224 * Writes chars from a {@code String} to bytes on an 3225 * {@code OutputStream} using the default character encoding of the 3226 * platform. 3227 * <p> 3228 * This method uses {@link String#getBytes()}. 3229 * 3230 * @param data the {@code String} to write, null ignored 3231 * @param output the {@code OutputStream} to write to 3232 * @throws NullPointerException if output is null 3233 * @throws IOException if an I/O error occurs 3234 * @since 1.1 3235 * @deprecated 2.5 use {@link #write(String, OutputStream, Charset)} instead 3236 */ 3237 @Deprecated 3238 public static void write(final String data, final OutputStream output) 3239 throws IOException { 3240 write(data, output, Charset.defaultCharset()); 3241 } 3242 3243 /** 3244 * Writes chars from a {@code String} to bytes on an 3245 * {@code OutputStream} using the specified character encoding. 3246 * <p> 3247 * This method uses {@link String#getBytes(String)}. 3248 * 3249 * @param data the {@code String} to write, null ignored 3250 * @param output the {@code OutputStream} to write to 3251 * @param charset the charset to use, null means platform default 3252 * @throws NullPointerException if output is null 3253 * @throws IOException if an I/O error occurs 3254 * @since 2.3 3255 */ 3256 public static void write(final String data, final OutputStream output, final Charset charset) throws IOException { 3257 if (data != null) { 3258 output.write(data.getBytes(Charsets.toCharset(charset))); 3259 } 3260 } 3261 3262 /** 3263 * Writes chars from a {@code String} to bytes on an 3264 * {@code OutputStream} using the specified character encoding. 3265 * <p> 3266 * Character encoding names can be found at 3267 * <a href="http://www.iana.org/assignments/character-sets">IANA</a>. 3268 * <p> 3269 * This method uses {@link String#getBytes(String)}. 3270 * 3271 * @param data the {@code String} to write, null ignored 3272 * @param output the {@code OutputStream} to write to 3273 * @param charsetName the name of the requested charset, null means platform default 3274 * @throws NullPointerException if output is null 3275 * @throws IOException if an I/O error occurs 3276 * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io 3277 * .UnsupportedEncodingException} in version 2.2 if the encoding is not supported. 3278 * @since 1.1 3279 */ 3280 public static void write(final String data, final OutputStream output, final String charsetName) 3281 throws IOException { 3282 write(data, output, Charsets.toCharset(charsetName)); 3283 } 3284 3285 /** 3286 * Writes chars from a {@code String} to a {@code Writer}. 3287 * 3288 * @param data the {@code String} to write, null ignored 3289 * @param writer the {@code Writer} to write to 3290 * @throws NullPointerException if output is null 3291 * @throws IOException if an I/O error occurs 3292 * @since 1.1 3293 */ 3294 public static void write(final String data, final Writer writer) throws IOException { 3295 if (data != null) { 3296 writer.write(data); 3297 } 3298 } 3299 3300 /** 3301 * Writes chars from a {@code StringBuffer} to bytes on an 3302 * {@code OutputStream} using the default character encoding of the 3303 * platform. 3304 * <p> 3305 * This method uses {@link String#getBytes()}. 3306 * 3307 * @param data the {@code StringBuffer} to write, null ignored 3308 * @param output the {@code OutputStream} to write to 3309 * @throws NullPointerException if output is null 3310 * @throws IOException if an I/O error occurs 3311 * @since 1.1 3312 * @deprecated replaced by write(CharSequence, OutputStream) 3313 */ 3314 @Deprecated 3315 public static void write(final StringBuffer data, final OutputStream output) //NOSONAR 3316 throws IOException { 3317 write(data, output, (String) null); 3318 } 3319 3320 /** 3321 * Writes chars from a {@code StringBuffer} to bytes on an 3322 * {@code OutputStream} using the specified character encoding. 3323 * <p> 3324 * Character encoding names can be found at 3325 * <a href="http://www.iana.org/assignments/character-sets">IANA</a>. 3326 * <p> 3327 * This method uses {@link String#getBytes(String)}. 3328 * 3329 * @param data the {@code StringBuffer} to write, null ignored 3330 * @param output the {@code OutputStream} to write to 3331 * @param charsetName the name of the requested charset, null means platform default 3332 * @throws NullPointerException if output is null 3333 * @throws IOException if an I/O error occurs 3334 * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io 3335 * .UnsupportedEncodingException} in version 2.2 if the encoding is not supported. 3336 * @since 1.1 3337 * @deprecated replaced by write(CharSequence, OutputStream, String) 3338 */ 3339 @Deprecated 3340 public static void write(final StringBuffer data, final OutputStream output, final String charsetName) //NOSONAR 3341 throws IOException { 3342 if (data != null) { 3343 output.write(data.toString().getBytes(Charsets.toCharset(charsetName))); 3344 } 3345 } 3346 3347 /** 3348 * Writes chars from a {@code StringBuffer} to a {@code Writer}. 3349 * 3350 * @param data the {@code StringBuffer} to write, null ignored 3351 * @param writer the {@code Writer} to write to 3352 * @throws NullPointerException if output is null 3353 * @throws IOException if an I/O error occurs 3354 * @since 1.1 3355 * @deprecated replaced by write(CharSequence, Writer) 3356 */ 3357 @Deprecated 3358 public static void write(final StringBuffer data, final Writer writer) //NOSONAR 3359 throws IOException { 3360 if (data != null) { 3361 writer.write(data.toString()); 3362 } 3363 } 3364 3365 /** 3366 * Writes bytes from a {@code byte[]} to an {@code OutputStream} using chunked writes. 3367 * This is intended for writing very large byte arrays which might otherwise cause excessive 3368 * memory usage if the native code has to allocate a copy. 3369 * 3370 * @param data the byte array to write, do not modify during output, 3371 * null ignored 3372 * @param output the {@code OutputStream} to write to 3373 * @throws NullPointerException if output is null 3374 * @throws IOException if an I/O error occurs 3375 * @since 2.5 3376 */ 3377 public static void writeChunked(final byte[] data, final OutputStream output) 3378 throws IOException { 3379 if (data != null) { 3380 int bytes = data.length; 3381 int offset = 0; 3382 while (bytes > 0) { 3383 final int chunk = Math.min(bytes, DEFAULT_BUFFER_SIZE); 3384 output.write(data, offset, chunk); 3385 bytes -= chunk; 3386 offset += chunk; 3387 } 3388 } 3389 } 3390 3391 /** 3392 * Writes chars from a {@code char[]} to a {@code Writer} using chunked writes. 3393 * This is intended for writing very large byte arrays which might otherwise cause excessive 3394 * memory usage if the native code has to allocate a copy. 3395 * 3396 * @param data the char array to write, do not modify during output, 3397 * null ignored 3398 * @param writer the {@code Writer} to write to 3399 * @throws NullPointerException if output is null 3400 * @throws IOException if an I/O error occurs 3401 * @since 2.5 3402 */ 3403 public static void writeChunked(final char[] data, final Writer writer) throws IOException { 3404 if (data != null) { 3405 int bytes = data.length; 3406 int offset = 0; 3407 while (bytes > 0) { 3408 final int chunk = Math.min(bytes, DEFAULT_BUFFER_SIZE); 3409 writer.write(data, offset, chunk); 3410 bytes -= chunk; 3411 offset += chunk; 3412 } 3413 } 3414 } 3415 3416 /** 3417 * Writes the {@code toString()} value of each item in a collection to 3418 * an {@code OutputStream} line by line, using the default character 3419 * encoding of the platform and the specified line ending. 3420 * 3421 * @param lines the lines to write, null entries produce blank lines 3422 * @param lineEnding the line separator to use, null is system default 3423 * @param output the {@code OutputStream} to write to, not null, not closed 3424 * @throws NullPointerException if the output is null 3425 * @throws IOException if an I/O error occurs 3426 * @since 1.1 3427 * @deprecated 2.5 use {@link #writeLines(Collection, String, OutputStream, Charset)} instead 3428 */ 3429 @Deprecated 3430 public static void writeLines(final Collection<?> lines, final String lineEnding, 3431 final OutputStream output) throws IOException { 3432 writeLines(lines, lineEnding, output, Charset.defaultCharset()); 3433 } 3434 3435 /** 3436 * Writes the {@code toString()} value of each item in a collection to 3437 * an {@code OutputStream} line by line, using the specified character 3438 * encoding and the specified line ending. 3439 * 3440 * @param lines the lines to write, null entries produce blank lines 3441 * @param lineEnding the line separator to use, null is system default 3442 * @param output the {@code OutputStream} to write to, not null, not closed 3443 * @param charset the charset to use, null means platform default 3444 * @throws NullPointerException if the output is null 3445 * @throws IOException if an I/O error occurs 3446 * @since 2.3 3447 */ 3448 public static void writeLines(final Collection<?> lines, String lineEnding, final OutputStream output, 3449 final Charset charset) throws IOException { 3450 if (lines == null) { 3451 return; 3452 } 3453 if (lineEnding == null) { 3454 lineEnding = System.lineSeparator(); 3455 } 3456 final Charset cs = Charsets.toCharset(charset); 3457 for (final Object line : lines) { 3458 if (line != null) { 3459 output.write(line.toString().getBytes(cs)); 3460 } 3461 output.write(lineEnding.getBytes(cs)); 3462 } 3463 } 3464 3465 /** 3466 * Writes the {@code toString()} value of each item in a collection to 3467 * an {@code OutputStream} line by line, using the specified character 3468 * encoding and the specified line ending. 3469 * <p> 3470 * Character encoding names can be found at 3471 * <a href="http://www.iana.org/assignments/character-sets">IANA</a>. 3472 * 3473 * @param lines the lines to write, null entries produce blank lines 3474 * @param lineEnding the line separator to use, null is system default 3475 * @param output the {@code OutputStream} to write to, not null, not closed 3476 * @param charsetName the name of the requested charset, null means platform default 3477 * @throws NullPointerException if the output is null 3478 * @throws IOException if an I/O error occurs 3479 * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io 3480 * .UnsupportedEncodingException} in version 2.2 if the 3481 * encoding is not supported. 3482 * @since 1.1 3483 */ 3484 public static void writeLines(final Collection<?> lines, final String lineEnding, 3485 final OutputStream output, final String charsetName) throws IOException { 3486 writeLines(lines, lineEnding, output, Charsets.toCharset(charsetName)); 3487 } 3488 3489 /** 3490 * Writes the {@code toString()} value of each item in a collection to 3491 * a {@code Writer} line by line, using the specified line ending. 3492 * 3493 * @param lines the lines to write, null entries produce blank lines 3494 * @param lineEnding the line separator to use, null is system default 3495 * @param writer the {@code Writer} to write to, not null, not closed 3496 * @throws NullPointerException if the input is null 3497 * @throws IOException if an I/O error occurs 3498 * @since 1.1 3499 */ 3500 public static void writeLines(final Collection<?> lines, String lineEnding, 3501 final Writer writer) throws IOException { 3502 if (lines == null) { 3503 return; 3504 } 3505 if (lineEnding == null) { 3506 lineEnding = System.lineSeparator(); 3507 } 3508 for (final Object line : lines) { 3509 if (line != null) { 3510 writer.write(line.toString()); 3511 } 3512 writer.write(lineEnding); 3513 } 3514 } 3515 3516 /** 3517 * Returns the given Appendable if it is already a {@link Writer}, otherwise creates a Writer wrapper around the 3518 * given Appendable. 3519 * 3520 * @param appendable the Appendable to wrap or return (not null) 3521 * @return the given Appendable or a Writer wrapper around the given Appendable 3522 * @throws NullPointerException if the input parameter is null 3523 * @since 2.7 3524 */ 3525 public static Writer writer(final Appendable appendable) { 3526 Objects.requireNonNull(appendable, "appendable"); 3527 if (appendable instanceof Writer) { 3528 return (Writer) appendable; 3529 } 3530 if (appendable instanceof StringBuilder) { 3531 return new StringBuilderWriter((StringBuilder) appendable); 3532 } 3533 return new AppendableWriter<>(appendable); 3534 } 3535 3536 /** 3537 * Instances should NOT be constructed in standard programming. 3538 */ 3539 public IOUtils() { //NOSONAR 3540 3541 } 3542 3543}