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