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