Coverage Report - org.apache.commons.io.IOUtils
 
Classes in this File Line Coverage Branch Coverage Complexity
IOUtils
89%
409/457
85%
213/250
0
 
 1  
 /*
 2  
  * Licensed to the Apache Software Foundation (ASF) under one or more
 3  
  * contributor license agreements.  See the NOTICE file distributed with
 4  
  * this work for additional information regarding copyright ownership.
 5  
  * The ASF licenses this file to You under the Apache License, Version 2.0
 6  
  * (the "License"); you may not use this file except in compliance with
 7  
  * the License.  You may obtain a copy of the License at
 8  
  *
 9  
  *      http://www.apache.org/licenses/LICENSE-2.0
 10  
  *
 11  
  * Unless required by applicable law or agreed to in writing, software
 12  
  * distributed under the License is distributed on an "AS IS" BASIS,
 13  
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 14  
  * See the License for the specific language governing permissions and
 15  
  * limitations under the License.
 16  
  */
 17  
 package org.apache.commons.io;
 18  
 
 19  
 import java.io.BufferedInputStream;
 20  
 import java.io.BufferedOutputStream;
 21  
 import java.io.BufferedReader;
 22  
 import java.io.BufferedWriter;
 23  
 import java.io.ByteArrayInputStream;
 24  
 import java.io.CharArrayWriter;
 25  
 import java.io.Closeable;
 26  
 import java.io.EOFException;
 27  
 import java.io.File;
 28  
 import java.io.IOException;
 29  
 import java.io.InputStream;
 30  
 import java.io.InputStreamReader;
 31  
 import java.io.OutputStream;
 32  
 import java.io.OutputStreamWriter;
 33  
 import java.io.PrintWriter;
 34  
 import java.io.Reader;
 35  
 import java.io.Writer;
 36  
 import java.net.HttpURLConnection;
 37  
 import java.net.ServerSocket;
 38  
 import java.net.Socket;
 39  
 import java.net.URI;
 40  
 import java.net.URL;
 41  
 import java.net.URLConnection;
 42  
 import java.nio.ByteBuffer;
 43  
 import java.nio.channels.ReadableByteChannel;
 44  
 import java.nio.channels.Selector;
 45  
 import java.nio.charset.Charset;
 46  
 import java.util.ArrayList;
 47  
 import java.util.Collection;
 48  
 import java.util.List;
 49  
 
 50  
 import org.apache.commons.io.output.ByteArrayOutputStream;
 51  
 import org.apache.commons.io.output.StringBuilderWriter;
 52  
 
 53  
 /**
 54  
  * General IO stream manipulation utilities.
 55  
  * <p>
 56  
  * This class provides static utility methods for input/output operations.
 57  
  * <ul>
 58  
  * <li><b>[Deprecated]</b> closeQuietly - these methods close a stream ignoring nulls and exceptions
 59  
  * <li>toXxx/read - these methods read data from a stream
 60  
  * <li>write - these methods write data to a stream
 61  
  * <li>copy - these methods copy all the data from one stream to another
 62  
  * <li>contentEquals - these methods compare the content of two streams
 63  
  * </ul>
 64  
  * <p>
 65  
  * The byte-to-char methods and char-to-byte methods involve a conversion step.
 66  
  * Two methods are provided in each case, one that uses the platform default
 67  
  * encoding and the other which allows you to specify an encoding. You are
 68  
  * encouraged to always specify an encoding because relying on the platform
 69  
  * default can lead to unexpected results, for example when moving from
 70  
  * development to production.
 71  
  * <p>
 72  
  * All the methods in this class that read a stream are buffered internally.
 73  
  * This means that there is no cause to use a <code>BufferedInputStream</code>
 74  
  * or <code>BufferedReader</code>. The default buffer size of 4K has been shown
 75  
  * to be efficient in tests.
 76  
  * <p>
 77  
  * The various copy methods all delegate the actual copying to one of the following methods:
 78  
  * <ul>
 79  
  * <li>{@link #copyLarge(InputStream, OutputStream, byte[])}</li>
 80  
  * <li>{@link #copyLarge(InputStream, OutputStream, long, long, byte[])}</li>
 81  
  * <li>{@link #copyLarge(Reader, Writer, char[])}</li>
 82  
  * <li>{@link #copyLarge(Reader, Writer, long, long, char[])}</li>
 83  
  * </ul>
 84  
  * For example, {@link #copy(InputStream, OutputStream)} calls {@link #copyLarge(InputStream, OutputStream)}
 85  
  * which calls {@link #copy(InputStream, OutputStream, int)} which creates the buffer and calls
 86  
  * {@link #copyLarge(InputStream, OutputStream, byte[])}.
 87  
  * <p>
 88  
  * Applications can re-use buffers by using the underlying methods directly.
 89  
  * This may improve performance for applications that need to do a lot of copying.
 90  
  * <p>
 91  
  * Wherever possible, the methods in this class do <em>not</em> flush or close
 92  
  * the stream. This is to avoid making non-portable assumptions about the
 93  
  * streams' origin and further use. Thus the caller is still responsible for
 94  
  * closing streams after use.
 95  
  * <p>
 96  
  * Origin of code: Excalibur.
 97  
  *
 98  
  */
 99  
 public 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  15
     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  30
         try (final StringBuilderWriter buf = new StringBuilderWriter(4);
 138  15
                 final PrintWriter out = new PrintWriter(buf)) {
 139  15
             out.println();
 140  15
             LINE_SEPARATOR = buf.toString();
 141  15
         }
 142  15
     }
 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  0
         super();
 176  0
     }
 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  7
         if (conn instanceof HttpURLConnection) {
 188  0
             ((HttpURLConnection) conn).disconnect();
 189  
         }
 190  7
     }
 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  47
         closeQuietly((Closeable) input);
 222  47
     }
 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  37
         closeQuietly((Closeable) output);
 253  37
     }
 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  88
         closeQuietly((Closeable) input);
 285  88
     }
 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  188
         closeQuietly((Closeable) output);
 318  188
     }
 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(&quot;foo.txt&quot;);
 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  380
             if (closeable != null) {
 363  235
                 closeable.close();
 364  
             }
 365  3
         } catch (final IOException ioe) {
 366  
             // ignore
 367  377
         }
 368  380
     }
 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(&quot;foo.txt&quot;);
 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  5
         if (closeables == null) {
 420  0
             return;
 421  
         }
 422  16
         for (final Closeable closeable : closeables) {
 423  11
             closeQuietly(closeable);
 424  
         }
 425  5
     }
 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  3
         if (sock != null) {
 457  
             try {
 458  2
                 sock.close();
 459  1
             } catch (final IOException ioe) {
 460  
                 // ignored
 461  1
             }
 462  
         }
 463  3
     }
 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  5
         if (selector != null) {
 495  
             try {
 496  4
                 selector.close();
 497  1
             } catch (final IOException ioe) {
 498  
                 // ignored
 499  3
             }
 500  
         }
 501  5
     }
 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  3
         if (sock != null) {
 533  
             try {
 534  2
                 sock.close();
 535  1
             } catch (final IOException ioe) {
 536  
                 // ignored
 537  1
             }
 538  
         }
 539  3
     }
 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  1
         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, int size) throws IOException {
 589  1
         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  39
         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, int size) {
 618  0
         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  4
         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, int size) {
 645  2
         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  4
         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, int size) {
 672  2
         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  4
         if (outputStream == null) { // not checked by BufferedOutputStream
 687  1
             throw new NullPointerException();
 688  
         }
 689  3
         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, int size) {
 704  
         // reject null early on rather than waiting for IO operation to fail
 705  2
         if (outputStream == null) { // not checked by BufferedOutputStream
 706  0
             throw new NullPointerException();
 707  
         }
 708  2
         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  4
         if (inputStream == null) { // not checked by BufferedInputStream
 724  1
             throw new NullPointerException();
 725  
         }
 726  3
         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, int size) {
 741  
         // reject null early on rather than waiting for IO operation to fail
 742  2
         if (inputStream == null) { // not checked by BufferedInputStream
 743  0
             throw new NullPointerException();
 744  
         }
 745  2
         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  29
         try (final ByteArrayOutputStream output = new ByteArrayOutputStream()) {
 765  29
             copy(input, output);
 766  58
             return output.toByteArray();
 767  29
         }
 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  4
         if (size > Integer.MAX_VALUE) {
 790  1
             throw new IllegalArgumentException("Size cannot be greater than Integer max value: " + size);
 791  
         }
 792  
 
 793  3
         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  5
         if (size < 0) {
 812  1
             throw new IllegalArgumentException("Size must be equal or greater than zero: " + size);
 813  
         }
 814  
 
 815  4
         if (size == 0) {
 816  1
             return new byte[0];
 817  
         }
 818  
 
 819  3
         final byte[] data = new byte[size];
 820  3
         int offset = 0;
 821  
         int read;
 822  
 
 823  6
         while (offset < size && (read = input.read(data, offset, size - offset)) != EOF) {
 824  3
             offset += read;
 825  
         }
 826  
 
 827  3
         if (offset != size) {
 828  1
             throw new IOException("Unexpected read size. current: " + offset + ", expected: " + size);
 829  
         }
 830  
 
 831  2
         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  1
         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  2
         try (final ByteArrayOutputStream output = new ByteArrayOutputStream()) {
 868  2
             copy(input, output, encoding);
 869  4
             return output.toByteArray();
 870  2
         }
 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  1
         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  1
         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  1
         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  6
         final URLConnection conn = url.openConnection();
 939  
         try {
 940  12
             return IOUtils.toByteArray(conn);
 941  
         } finally {
 942  6
             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  7
         try (InputStream inputStream = urlConn.getInputStream()) {
 957  14
             return IOUtils.toByteArray(inputStream);
 958  7
         }
 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  1
         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  2
         final CharArrayWriter output = new CharArrayWriter();
 1000  2
         copy(is, output, encoding);
 1001  2
         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  1
         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  1
         final CharArrayWriter sw = new CharArrayWriter();
 1042  1
         copy(input, sw);
 1043  1
         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  1
         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  40
         try (final StringBuilderWriter sw = new StringBuilderWriter()) {
 1084  40
             copy(input, sw, encoding);
 1085  80
             return sw.toString();
 1086  40
         }
 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  0
         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  6
         try (final StringBuilderWriter sw = new StringBuilderWriter()) {
 1126  6
             copy(input, sw);
 1127  12
             return sw.toString();
 1128  6
         }
 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  1
         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  3
         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  2
         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  1
         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  12
         try (InputStream inputStream = url.openStream()) {
 1199  24
             return toString(inputStream, encoding);
 1200  12
         }
 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  2
         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  1
         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  0
         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  5
         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, ClassLoader classLoader) throws IOException {
 1293  10
         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  4
         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  8
         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  4
         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  26
         final URL resource = classLoader == null ? IOUtils.class.getResource(name) : classLoader.getResource(name);
 1370  
 
 1371  20
         if (resource == null) {
 1372  6
             throw new IOException("Resource not found: " + name);
 1373  
         }
 1374  
 
 1375  14
         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  1
         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  4
         final InputStreamReader reader = new InputStreamReader(input, Charsets.toCharset(encoding));
 1416  4
         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  1
         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  5
         final BufferedReader reader = toBufferedReader(input);
 1458  5
         final List<String> list = new ArrayList<>();
 1459  5
         String line = reader.readLine();
 1460  28
         while (line != null) {
 1461  23
             list.add(line);
 1462  23
             line = reader.readLine();
 1463  
         }
 1464  5
         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  0
         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  10
         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  11
         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  1
         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  3
         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  2
         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  1
         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  4
         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  2
         final byte[] bytes = input.getBytes(Charsets.toCharset(encoding));
 1668  2
         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  6
         if (data != null) {
 1687  5
             output.write(data);
 1688  
         }
 1689  5
     }
 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  0
         if (data != null) {
 1706  0
             int bytes = data.length;
 1707  0
             int offset = 0;
 1708  0
             while (bytes > 0) {
 1709  0
                 int chunk = Math.min(bytes, DEFAULT_BUFFER_SIZE);
 1710  0
                 output.write(data, offset, chunk);
 1711  0
                 bytes -= chunk;
 1712  0
                 offset += chunk;
 1713  0
             }
 1714  
         }
 1715  0
     }
 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  3
         write(data, output, Charset.defaultCharset());
 1734  2
     }
 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  7
         if (data != null) {
 1752  5
             output.write(new String(data, Charsets.toCharset(encoding)));
 1753  
         }
 1754  5
     }
 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  4
         write(data, output, Charsets.toCharset(encoding));
 1778  3
     }
 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  3
         if (data != null) {
 1795  2
             output.write(data);
 1796  
         }
 1797  2
     }
 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  0
         if (data != null) {
 1813  0
             int bytes = data.length;
 1814  0
             int offset = 0;
 1815  0
             while (bytes > 0) {
 1816  0
                 int chunk = Math.min(bytes, DEFAULT_BUFFER_SIZE);
 1817  0
                 output.write(data, offset, chunk);
 1818  0
                 bytes -= chunk;
 1819  0
                 offset += chunk;
 1820  0
             }
 1821  
         }
 1822  0
     }
 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  5
         write(data, output, Charset.defaultCharset());
 1843  3
     }
 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  7
         if (data != null) {
 1862  5
             output.write(new String(data).getBytes(Charsets.toCharset(encoding)));
 1863  
         }
 1864  5
     }
 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  2
         write(data, output, Charsets.toCharset(encoding));
 1889  2
     }
 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  3
         if (data != null) {
 1905  2
             write(data.toString(), output);
 1906  
         }
 1907  2
     }
 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  5
         write(data, output, Charset.defaultCharset());
 1927  3
     }
 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  7
         if (data != null) {
 1945  5
             write(data.toString(), output, encoding);
 1946  
         }
 1947  5
     }
 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  2
         write(data, output, Charsets.toCharset(encoding));
 1970  2
     }
 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  5
         if (data != null) {
 1986  4
             output.write(data);
 1987  
         }
 1988  3
     }
 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  5
         write(data, output, Charset.defaultCharset());
 2008  3
     }
 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  79
         if (data != null) {
 2025  77
             output.write(data.getBytes(Charsets.toCharset(encoding)));
 2026  
         }
 2027  75
     }
 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  2
         write(data, output, Charsets.toCharset(encoding));
 2050  2
     }
 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  0
         if (data != null) {
 2069  0
             output.write(data.toString());
 2070  
         }
 2071  0
     }
 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  0
         write(data, output, (String) null);
 2091  0
     }
 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  0
         if (data != null) {
 2116  0
             output.write(data.toString().getBytes(Charsets.toCharset(encoding)));
 2117  
         }
 2118  0
     }
 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  4
         writeLines(lines, lineEnding, output, Charset.defaultCharset());
 2140  3
     }
 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  34
         if (lines == null) {
 2158  3
             return;
 2159  
         }
 2160  31
         if (lineEnding == null) {
 2161  25
             lineEnding = LINE_SEPARATOR;
 2162  
         }
 2163  31
         final Charset cs = Charsets.toCharset(encoding);
 2164  31
         for (final Object line : lines) {
 2165  103
             if (line != null) {
 2166  97
                 output.write(line.toString().getBytes(cs));
 2167  
             }
 2168  101
             output.write(lineEnding.getBytes(cs));
 2169  101
         }
 2170  29
     }
 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  30
         writeLines(lines, lineEnding, output, Charsets.toCharset(encoding));
 2194  29
     }
 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  4
         if (lines == null) {
 2210  1
             return;
 2211  
         }
 2212  3
         if (lineEnding == null) {
 2213  1
             lineEnding = LINE_SEPARATOR;
 2214  
         }
 2215  3
         for (final Object line : lines) {
 2216  9
             if (line != null) {
 2217  8
                 writer.write(line.toString());
 2218  
             }
 2219  8
             writer.write(lineEnding);
 2220  8
         }
 2221  2
     }
 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 &gt; 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  56
         final long count = copyLarge(input, output);
 2247  53
         if (count > Integer.MAX_VALUE) {
 2248  1
             return -1;
 2249  
         }
 2250  52
         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  77
         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  62
         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  77
         long count = 0;
 2313  
         int n;
 2314  3154081
         while (EOF != (n = input.read(buffer))) {
 2315  3154005
             output.write(buffer, 0, n);
 2316  3154004
             count += n;
 2317  
         }
 2318  74
         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  6
         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  6
         if (inputOffset > 0) {
 2377  2
             skipFully(input, inputOffset);
 2378  
         }
 2379  5
         if (length == 0) {
 2380  0
             return 0;
 2381  
         }
 2382  5
         final int bufferLength = buffer.length;
 2383  5
         int bytesToRead = bufferLength;
 2384  5
         if (length > 0 && length < bufferLength) {
 2385  4
             bytesToRead = (int) length;
 2386  
         }
 2387  
         int read;
 2388  5
         long totalRead = 0;
 2389  10
         while (bytesToRead > 0 && EOF != (read = input.read(buffer, 0, bytesToRead))) {
 2390  5
             output.write(buffer, 0, read);
 2391  5
             totalRead += read;
 2392  5
             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  4
                 bytesToRead = (int) Math.min(length - totalRead, bufferLength);
 2395  
             }
 2396  
         }
 2397  5
         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  3
         copy(input, output, Charset.defaultCharset());
 2420  1
     }
 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  49
         final InputStreamReader in = new InputStreamReader(input, Charsets.toCharset(inputEncoding));
 2441  47
         copy(in, output);
 2442  45
     }
 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  4
         copy(input, output, Charsets.toCharset(inputEncoding));
 2469  2
     }
 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 &gt; 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  65
         final long count = copyLarge(input, output);
 2494  59
         if (count > Integer.MAX_VALUE) {
 2495  1
             return -1;
 2496  
         }
 2497  58
         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  66
         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  66
         long count = 0;
 2536  
         int n;
 2537  1048721
         while (EOF != (n = input.read(buffer))) {
 2538  1048658
             output.write(buffer, 0, n);
 2539  1048655
             count += n;
 2540  
         }
 2541  60
         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  5
         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  5
         if (inputOffset > 0) {
 2591  2
             skipFully(input, inputOffset);
 2592  
         }
 2593  4
         if (length == 0) {
 2594  0
             return 0;
 2595  
         }
 2596  4
         int bytesToRead = buffer.length;
 2597  4
         if (length > 0 && length < buffer.length) {
 2598  3
             bytesToRead = (int) length;
 2599  
         }
 2600  
         int read;
 2601  4
         long totalRead = 0;
 2602  8
         while (bytesToRead > 0 && EOF != (read = input.read(buffer, 0, bytesToRead))) {
 2603  4
             output.write(buffer, 0, read);
 2604  4
             totalRead += read;
 2605  4
             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  3
                 bytesToRead = (int) Math.min(length - totalRead, buffer.length);
 2608  
             }
 2609  
         }
 2610  4
         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  3
         copy(input, output, Charset.defaultCharset());
 2637  1
     }
 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  9
         final OutputStreamWriter out = new OutputStreamWriter(output, Charsets.toCharset(outputEncoding));
 2665  7
         copy(input, out);
 2666  
         // XXX Unless anyone is planning on rewriting OutputStreamWriter,
 2667  
         // we have to flush here.
 2668  5
         out.flush();
 2669  5
     }
 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  4
         copy(input, output, Charsets.toCharset(outputEncoding));
 2700  2
     }
 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  12
         if (input1 == input2) {
 2722  2
             return true;
 2723  
         }
 2724  10
         if (!(input1 instanceof BufferedInputStream)) {
 2725  9
             input1 = new BufferedInputStream(input1);
 2726  
         }
 2727  10
         if (!(input2 instanceof BufferedInputStream)) {
 2728  9
             input2 = new BufferedInputStream(input2);
 2729  
         }
 2730  
 
 2731  10
         int ch = input1.read();
 2732  4511
         while (EOF != ch) {
 2733  4503
             final int ch2 = input2.read();
 2734  4503
             if (ch != ch2) {
 2735  2
                 return false;
 2736  
             }
 2737  4501
             ch = input1.read();
 2738  4501
         }
 2739  
 
 2740  8
         final int ch2 = input2.read();
 2741  8
         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  7
         if (input1 == input2) {
 2762  2
             return true;
 2763  
         }
 2764  
 
 2765  5
         input1 = toBufferedReader(input1);
 2766  5
         input2 = toBufferedReader(input2);
 2767  
 
 2768  5
         int ch = input1.read();
 2769  14
         while (EOF != ch) {
 2770  10
             final int ch2 = input2.read();
 2771  10
             if (ch != ch2) {
 2772  1
                 return false;
 2773  
             }
 2774  9
             ch = input1.read();
 2775  9
         }
 2776  
 
 2777  4
         final int ch2 = input2.read();
 2778  4
         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  14
         if (input1 == input2) {
 2798  2
             return true;
 2799  
         }
 2800  12
         final BufferedReader br1 = toBufferedReader(input1);
 2801  12
         final BufferedReader br2 = toBufferedReader(input2);
 2802  
 
 2803  12
         String line1 = br1.readLine();
 2804  12
         String line2 = br2.readLine();
 2805  28
         while (line1 != null && line2 != null && line1.equals(line2)) {
 2806  16
             line1 = br1.readLine();
 2807  16
             line2 = br2.readLine();
 2808  
         }
 2809  12
         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  8
         if (toSkip < 0) {
 2835  0
             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  8
         if (SKIP_BYTE_BUFFER == null) {
 2843  1
             SKIP_BYTE_BUFFER = new byte[SKIP_BUFFER_SIZE];
 2844  
         }
 2845  8
         long remain = toSkip;
 2846  15
         while (remain > 0) {
 2847  
             // See https://issues.apache.org/jira/browse/IO-203 for why we use read() rather than delegating to skip()
 2848  11
             final long n = input.read(SKIP_BYTE_BUFFER, 0, (int) Math.min(remain, SKIP_BUFFER_SIZE));
 2849  11
             if (n < 0) { // EOF
 2850  4
                 break;
 2851  
             }
 2852  7
             remain -= n;
 2853  7
         }
 2854  8
         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  6
         if (toSkip < 0) {
 2871  0
             throw new IllegalArgumentException("Skip count must be non-negative, actual: " + toSkip);
 2872  
         }
 2873  6
         final ByteBuffer skipByteBuffer = ByteBuffer.allocate((int) Math.min(toSkip, SKIP_BUFFER_SIZE));
 2874  6
         long remain = toSkip;
 2875  12
         while (remain > 0) {
 2876  9
             skipByteBuffer.position(0);
 2877  9
             skipByteBuffer.limit((int) Math.min(remain, SKIP_BUFFER_SIZE));
 2878  9
             final int n = input.read(skipByteBuffer);
 2879  9
             if (n == EOF) {
 2880  3
                 break;
 2881  
             }
 2882  6
             remain -= n;
 2883  6
         }
 2884  6
         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  9
         if (toSkip < 0) {
 2910  1
             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  8
         if (SKIP_CHAR_BUFFER == null) {
 2918  1
             SKIP_CHAR_BUFFER = new char[SKIP_BUFFER_SIZE];
 2919  
         }
 2920  8
         long remain = toSkip;
 2921  15
         while (remain > 0) {
 2922  
             // See https://issues.apache.org/jira/browse/IO-203 for why we use read() rather than delegating to skip()
 2923  11
             final long n = input.read(SKIP_CHAR_BUFFER, 0, (int) Math.min(remain, SKIP_BUFFER_SIZE));
 2924  11
             if (n < 0) { // EOF
 2925  4
                 break;
 2926  
             }
 2927  7
             remain -= n;
 2928  7
         }
 2929  8
         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  6
         if (toSkip < 0) {
 2953  1
             throw new IllegalArgumentException("Bytes to skip must not be negative: " + toSkip);
 2954  
         }
 2955  5
         final long skipped = skip(input, toSkip);
 2956  5
         if (skipped != toSkip) {
 2957  2
             throw new EOFException("Bytes to skip: " + toSkip + " actual: " + skipped);
 2958  
         }
 2959  3
     }
 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  4
         if (toSkip < 0) {
 2973  1
             throw new IllegalArgumentException("Bytes to skip must not be negative: " + toSkip);
 2974  
         }
 2975  3
         final long skipped = skip(input, toSkip);
 2976  3
         if (skipped != toSkip) {
 2977  1
             throw new EOFException("Bytes to skip: " + toSkip + " actual: " + skipped);
 2978  
         }
 2979  2
     }
 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  6
         final long skipped = skip(input, toSkip);
 3002  5
         if (skipped != toSkip) {
 3003  2
             throw new EOFException("Chars to skip: " + toSkip + " actual: " + skipped);
 3004  
         }
 3005  3
     }
 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 &gt;= 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  5
         if (length < 0) {
 3025  1
             throw new IllegalArgumentException("Length must not be negative: " + length);
 3026  
         }
 3027  4
         int remaining = length;
 3028  7
         while (remaining > 0) {
 3029  4
             final int location = length - remaining;
 3030  4
             final int count = input.read(buffer, offset + location, remaining);
 3031  4
             if (EOF == count) { // EOF
 3032  1
                 break;
 3033  
             }
 3034  3
             remaining -= count;
 3035  3
         }
 3036  4
         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  0
         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 &gt;= 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  6
         if (length < 0) {
 3072  1
             throw new IllegalArgumentException("Length must not be negative: " + length);
 3073  
         }
 3074  5
         int remaining = length;
 3075  9
         while (remaining > 0) {
 3076  5
             final int location = length - remaining;
 3077  5
             final int count = input.read(buffer, offset + location, remaining);
 3078  5
             if (EOF == count) { // EOF
 3079  1
                 break;
 3080  
             }
 3081  4
             remaining -= count;
 3082  4
         }
 3083  5
         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  0
         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  7
         final int length = buffer.remaining();
 3117  9
         while (buffer.remaining() > 0) {
 3118  4
             final int count = input.read(buffer);
 3119  4
             if (EOF == count) { // EOF
 3120  2
                 break;
 3121  
             }
 3122  2
         }
 3123  7
         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 &gt;= 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  5
         final int actual = read(input, buffer, offset, length);
 3144  4
         if (actual != length) {
 3145  1
             throw new EOFException("Length to read: " + length + " actual: " + actual);
 3146  
         }
 3147  3
     }
 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  0
         readFully(input, buffer, 0, buffer.length);
 3164  0
     }
 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 &gt;= 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  6
         final int actual = read(input, buffer, offset, length);
 3184  5
         if (actual != length) {
 3185  1
             throw new EOFException("Length to read: " + length + " actual: " + actual);
 3186  
         }
 3187  4
     }
 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  0
         readFully(input, buffer, 0, buffer.length);
 3204  0
     }
 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 &gt;= 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  1
         final byte[] buffer = new byte[length];
 3222  1
         readFully(input, buffer, 0, buffer.length);
 3223  1
         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  5
         final int expected = buffer.remaining();
 3240  5
         final int actual = read(input, buffer);
 3241  5
         if (actual != expected) {
 3242  2
             throw new EOFException("Length to read: " + expected + " actual: " + actual);
 3243  
         }
 3244  3
     }
 3245  
 
 3246  
 }