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