View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one
3    * or more contributor license agreements.  See the NOTICE file
4    * distributed with this work for additional information
5    * regarding copyright ownership.  The ASF licenses this file
6    * to you under the Apache License, Version 2.0 (the
7    * "License"); you may not use this file except in compliance
8    * with the License.  You may obtain a copy of the License at
9    *
10   *   http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing,
13   * software distributed under the License is distributed on an
14   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   * KIND, either express or implied.  See the License for the
16   * specific language governing permissions and limitations
17   * under the License.
18   */
19  package org.apache.maven.shared.utils.io;
20  
21  import javax.annotation.Nonnull;
22  import javax.annotation.Nullable;
23  
24  import java.io.BufferedInputStream;
25  import java.io.ByteArrayInputStream;
26  import java.io.ByteArrayOutputStream;
27  import java.io.IOException;
28  import java.io.InputStream;
29  import java.io.InputStreamReader;
30  import java.io.OutputStream;
31  import java.io.OutputStreamWriter;
32  import java.io.Reader;
33  import java.io.StringReader;
34  import java.io.StringWriter;
35  import java.io.Writer;
36  import java.nio.channels.Channel;
37  
38  /**
39   * <p>General IO Stream manipulation.</p>
40   * <p>
41   * This class provides static utility methods for input/output operations, particularly buffered
42   * copying between sources (<code>InputStream</code>, <code>Reader</code>, <code>String</code> and
43   * <code>byte[]</code>) and destinations (<code>OutputStream</code>, <code>Writer</code>,
44   * <code>String</code> and <code>byte[]</code>).</p>
45   *
46   * <p>Unless otherwise noted, these <code>copy</code> methods do <em>not</em> flush or close the
47   * streams. Often, doing so would require making non-portable assumptions about the streams' origin
48   * and further use. This means that both streams' <code>close()</code> methods must be called after
49   * copying. if one omits this step, then the stream resources (sockets, file descriptors) are
50   * released when the associated Stream is garbage-collected. It is not a good idea to rely on this
51   * mechanism.</p>
52   *
53   * <p>For each <code>copy</code> method, a variant is provided that allows the caller to specify the
54   * buffer size (the default is 4k). As the buffer size can have a fairly large impact on speed, this
55   * may be worth tweaking. Often "large buffer -&gt; faster" does not hold, even for large data
56   * transfers.</p>
57   * <p>For byte-to-char methods, a <code>copy</code> variant allows the encoding to be selected
58   * (otherwise the platform default is used).</p>
59   * <p>The <code>copy</code> methods use an internal buffer when copying. It is therefore advisable
60   * <em>not</em> to deliberately wrap the stream arguments to the <code>copy</code> methods in
61   * <code>Buffered*</code> streams. For example, don't do the
62   * following:</p>
63   * <p>
64   * <code>copy( new BufferedInputStream( in ), new BufferedOutputStream( out ) );</code>
65   * </p>
66   * <p>The rationale is as follows:</p>
67   *
68   * <p>Imagine that an InputStream's read() is a very expensive operation, which would usually suggest
69   * wrapping in a BufferedInputStream. The BufferedInputStream works by issuing infrequent
70   * {@link java.io.InputStream#read(byte[] b, int off, int len)} requests on the underlying InputStream, to
71   * fill an internal buffer, from which further <code>read</code> requests can inexpensively get
72   * their data (until the buffer runs out).</p>
73   * <p>However, the <code>copy</code> methods do the same thing, keeping an internal buffer,
74   * populated by {@link InputStream#read(byte[] b, int off, int len)} requests. Having two buffers
75   * (or three if the destination stream is also buffered) is pointless, and the unnecessary buffer
76   * management hurts performance slightly (about 3%, according to some simple experiments).</p>
77   *
78   * @author <a href="mailto:peter@apache.org">Peter Donald</a>
79   * @author <a href="mailto:jefft@apache.org">Jeff Turner</a>
80   * @version CVS $Revision$ $Date$
81   *
82   */
83  public final class IOUtil
84  /*
85   * Behold, intrepid explorers; a map of this class:
86   *
87   *       Method      Input               Output          Dependency
88   *       ------      -----               ------          -------
89   * 1     copy        InputStream         OutputStream    (primitive)
90   * 2     copy        Reader              Writer          (primitive)
91   *
92   * 3     copy        InputStream         Writer          2
93   * 4     toString    InputStream         String          3
94   * 5     toByteArray InputStream         byte[]          1
95   *
96   * 6     copy        Reader              OutputStream    2
97   * 7     toString    Reader              String          2
98   * 8     toByteArray Reader              byte[]          6
99   *
100  * 9     copy        String              OutputStream    2
101  * 10    copy        String              Writer          (trivial)
102  * 11    toByteArray String              byte[]          9
103  *
104  * 12    copy        byte[]              Writer          3
105  * 13    toString    byte[]              String          12
106  * 14    copy        byte[]              OutputStream    (trivial)
107  *
108  *
109  * Note that only the first two methods shuffle bytes; the rest use these two, or (if possible) copy
110  * using native Java copy methods. As there are method variants to specify buffer size and encoding,
111  * each row may correspond to up to 4 methods.
112  *
113  */
114 {
115     private static final int DEFAULT_BUFFER_SIZE = 1024 * 4;
116 
117     /**
118      * Private constructor to prevent instantiation.
119      */
120     private IOUtil() {}
121 
122     ///////////////////////////////////////////////////////////////
123     // Core copy methods
124     ///////////////////////////////////////////////////////////////
125 
126     /**
127      * Copy bytes from an <code>InputStream</code> to an <code>OutputStream</code>.
128      *
129      * @param input the stream to read from
130      * @param output the stream to write to
131      * @throws IOException in case of an error
132      * @deprecated use {@code org.apache.commons.io.IOUtils.copy()} or in
133      *         Java 9 and later {@code InputStream.transferTo()}.
134      */
135     @Deprecated
136     public static void copy(@Nonnull final InputStream input, @Nonnull final OutputStream output) throws IOException {
137         copy(input, output, DEFAULT_BUFFER_SIZE);
138     }
139 
140     /**
141      * Copy bytes from an <code>InputStream</code> to an <code>OutputStream</code>.
142      *
143      * In Java 9 and later this is replaced by {@code InputStream.transferTo()}.
144      *
145      * @param input the stream to read from
146      * @param output the stream to write to
147      * @param bufferSize size of internal buffer
148      * @throws IOException in case of an error
149      * @deprecated use {@code org.apache.commons.io.IOUtils.copy()} or in
150      *         Java 9 and later {@code InputStream.transferTo()}.
151      */
152     @Deprecated
153     public static void copy(@Nonnull final InputStream input, @Nonnull final OutputStream output, final int bufferSize)
154             throws IOException {
155         final byte[] buffer = new byte[bufferSize];
156         int n;
157         while (-1 != (n = input.read(buffer))) {
158             output.write(buffer, 0, n);
159         }
160     }
161 
162     /**
163      * Copy chars from a <code>Reader</code> to a <code>Writer</code>.
164      *
165      * @param input the reader to read from
166      * @param output the writer to write to
167      * @throws IOException in case of failure     * @deprecated use {@code org.apache.commons.io.IOUtils.copy()}.
168      */
169     @Deprecated
170     public static void copy(@Nonnull final Reader input, @Nonnull final Writer output) throws IOException {
171         copy(input, output, DEFAULT_BUFFER_SIZE);
172     }
173 
174     /**
175      * Copy chars from a <code>Reader</code> to a <code>Writer</code>.
176      *
177      * @param input the reader to read from
178      * @param output the writer to write to
179      * @param bufferSize size of internal buffer
180      * @throws IOException in case of failure
181      * @deprecated use {@code org.apache.commons.io.IOUtils.copy()}.
182      */
183     @Deprecated
184     public static void copy(@Nonnull final Reader input, @Nonnull final Writer output, final int bufferSize)
185             throws IOException {
186         final char[] buffer = new char[bufferSize];
187         int n;
188         while (-1 != (n = input.read(buffer))) {
189             output.write(buffer, 0, n);
190         }
191         output.flush();
192     }
193 
194     ///////////////////////////////////////////////////////////////
195     // Derived copy methods
196     // InputStream -> *
197     ///////////////////////////////////////////////////////////////
198 
199     ///////////////////////////////////////////////////////////////
200     // InputStream -> Writer
201 
202     /**
203      * Copy and convert bytes from an <code>InputStream</code> to chars on a
204      * <code>Writer</code>.
205      *
206      * The platform's default encoding is used for the byte-to-char conversion.
207      *
208      * @param input the reader to read from
209      * @param output the writer to write to
210      * @throws IOException in case of failure
211      * @deprecated use {@code org.apache.commons.io.IOUtils.copy()}.
212      */
213     @Deprecated
214     public static void copy(@Nonnull final InputStream input, @Nonnull final Writer output) throws IOException {
215         copy(input, output, DEFAULT_BUFFER_SIZE);
216     }
217 
218     /**
219      * Copy and convert bytes from an <code>InputStream</code> to chars on a
220      * <code>Writer</code>.
221      * The platform's default encoding is used for the byte-to-char conversion.
222      *
223      * @param input the input stream to read from
224      * @param output the writer to write to
225      * @param bufferSize size of internal buffer
226      * @throws IOException in case of failure
227      * @deprecated use {@code org.apache.commons.io.IOUtils.copy()}.
228      */
229     @Deprecated
230     public static void copy(@Nonnull final InputStream input, @Nonnull final Writer output, final int bufferSize)
231             throws IOException {
232         final InputStreamReader in = new InputStreamReader(input);
233         copy(in, output, bufferSize);
234     }
235 
236     /**
237      * Copy and convert bytes from an <code>InputStream</code> to chars on a
238      * <code>Writer</code>, using the specified encoding.
239      *
240      * @param input the input stream to read from
241      * @param output the writer to write to
242      * @param encoding the name of a supported character encoding. See the
243      *                 <a href="https://www.iana.org/assignments/character-sets">IANA
244      *                 Charset Registry</a> for a list of valid encoding types.
245      * @throws IOException in case of failure
246      * @deprecated use {@code org.apache.commons.io.IOUtils.copy()}.
247      */
248     @Deprecated
249     public static void copy(
250             @Nonnull final InputStream input, @Nonnull final Writer output, @Nonnull final String encoding)
251             throws IOException {
252         final InputStreamReader in = new InputStreamReader(input, encoding);
253         copy(in, output);
254     }
255 
256     /**
257      * Copy and convert bytes from an <code>InputStream</code> to chars on a
258      * <code>Writer</code>, using the specified encoding.
259      *
260      * @param encoding   the name of a supported character encoding. See the
261      *                   <a href="https://www.iana.org/assignments/character-sets">IANA
262      *                   Charset Registry</a> for a list of valid encoding types.
263      * @param input the input stream to read from
264      * @param output the writer to write to
265      * @param bufferSize size of internal buffer
266      * @throws IOException in case of failure
267      * @deprecated use {@code org.apache.commons.io.IOUtils.copy()}.
268      */
269     @Deprecated
270     public static void copy(
271             @Nonnull final InputStream input,
272             @Nonnull final Writer output,
273             @Nonnull final String encoding,
274             final int bufferSize)
275             throws IOException {
276         final InputStreamReader in = new InputStreamReader(input, encoding);
277         copy(in, output, bufferSize);
278     }
279 
280     ///////////////////////////////////////////////////////////////
281     // InputStream -> String
282 
283     /**
284      * Get the contents of an <code>InputStream</code> as a String.
285      * The platform's default encoding is used for the byte-to-char conversion.
286      *
287      * @param input the InputStream to read from
288      * @return the resulting string
289      * @throws IOException in case of failure
290      * @deprecated always specify a character encoding
291      */
292     @Deprecated
293     @Nonnull
294     public static String toString(@Nonnull final InputStream input) throws IOException {
295         return toString(input, DEFAULT_BUFFER_SIZE);
296     }
297 
298     /**
299      * Get the contents of an <code>InputStream</code> as a String.
300      * The platform's default encoding is used for the byte-to-char conversion.
301      *
302      * @param input the InputStream to read from
303      * @param bufferSize size of internal buffer
304      * @return the resulting string
305      * @throws IOException in case of failure
306      * @deprecated always specify a character encoding
307      */
308     @Deprecated
309     @Nonnull
310     public static String toString(@Nonnull final InputStream input, final int bufferSize) throws IOException {
311         final StringWriter sw = new StringWriter();
312         copy(input, sw, bufferSize);
313         return sw.toString();
314     }
315 
316     /**
317      * Get the contents of an <code>InputStream</code> as a String.
318      *
319      * @param input the InputStream to read from
320      * @param encoding the name of a supported character encoding. See the
321      *                 <a href="https://www.iana.org/assignments/character-sets">IANA
322      *                 Charset Registry</a> for a list of valid encoding types.
323      * @return the converted string
324      * @throws IOException in case of failure
325      * @deprecated use {@code org.apache.commons.io.IOUtils.toString()}.
326      */
327     @Deprecated
328     @Nonnull
329     public static String toString(@Nonnull final InputStream input, @Nonnull final String encoding) throws IOException {
330         return toString(input, encoding, DEFAULT_BUFFER_SIZE);
331     }
332 
333     /**
334      * Get the contents of an <code>InputStream</code> as a String.
335      *
336      * @param input the InputStream to read from
337      * @param encoding   the name of a supported character encoding. See the
338      *                   <a href="https://www.iana.org/assignments/character-sets">IANA
339      *                   Charset Registry</a> for a list of valid encoding types.
340      * @param bufferSize size of internal buffer
341      * @return The converted string.
342      * @throws IOException in case of failure
343      * @deprecated use {@code org.apache.commons.io.IOUtils.toString()}.
344      */
345     @Deprecated
346     @Nonnull
347     public static String toString(
348             @Nonnull final InputStream input, @Nonnull final String encoding, final int bufferSize) throws IOException {
349         final StringWriter sw = new StringWriter();
350         copy(input, sw, encoding, bufferSize);
351         return sw.toString();
352     }
353 
354     ///////////////////////////////////////////////////////////////
355     // InputStream -> byte[]
356 
357     /**
358      * Get the contents of an <code>InputStream</code> as a <code>byte[]</code>.
359      *
360      * @param input the InputStream to read from
361      * @return the resulting byte array.
362      * @throws IOException in case of failure
363      * @deprecated use {@code org.apache.commons.io.IOUtils.readFully()}.
364      */
365     @Deprecated
366     @Nonnull
367     public static byte[] toByteArray(@Nonnull final InputStream input) throws IOException {
368         return toByteArray(input, DEFAULT_BUFFER_SIZE);
369     }
370 
371     /**
372      * Get the contents of an <code>InputStream</code> as a <code>byte[]</code>.
373      *
374      * @param input the InputStream to read from
375      * @param bufferSize size of internal buffer
376      * @return the resulting byte array.
377      * @throws IOException in case of failure
378      * @deprecated use {@code org.apache.commons.io.IOUtils.readFully()}.
379      */
380     @Deprecated
381     @Nonnull
382     public static byte[] toByteArray(@Nonnull final InputStream input, final int bufferSize) throws IOException {
383         final ByteArrayOutputStream output = new ByteArrayOutputStream();
384         copy(input, output, bufferSize);
385         return output.toByteArray();
386     }
387 
388     ///////////////////////////////////////////////////////////////
389     // Derived copy methods
390     // Reader -> *
391     ///////////////////////////////////////////////////////////////
392 
393     ///////////////////////////////////////////////////////////////
394     // Reader -> OutputStream
395 
396     /**
397      * Serialize chars from a <code>Reader</code> to bytes on an <code>OutputStream</code>, and
398      * flush the <code>OutputStream</code>.
399      *
400      * @param input the InputStream to read from
401      * @param output the output stream to write to
402      * @throws IOException in case of failure
403      * @deprecated always specify a character encoding
404      */
405     @Deprecated
406     public static void copy(@Nonnull final Reader input, @Nonnull final OutputStream output) throws IOException {
407         copy(input, output, DEFAULT_BUFFER_SIZE);
408     }
409 
410     /**
411      * Serialize chars from a <code>Reader</code> to bytes on an <code>OutputStream</code>, and
412      * flush the <code>OutputStream</code>.
413      *
414      * @param input the InputStream to read from
415      * @param output the output to write to
416      * @param bufferSize size of internal buffer
417      * @throws IOException in case of failure
418      * @deprecated always specify a character encoding
419      */
420     @Deprecated
421     public static void copy(@Nonnull final Reader input, @Nonnull final OutputStream output, final int bufferSize)
422             throws IOException {
423         final OutputStreamWriter out = new OutputStreamWriter(output);
424         copy(input, out, bufferSize);
425         // NOTE: Unless anyone is planning on rewriting OutputStreamWriter, we have to flush
426         // here.
427         out.flush();
428     }
429 
430     ///////////////////////////////////////////////////////////////
431     // Reader -> String
432 
433     /**
434      * Get the contents of a <code>Reader</code> as a String.
435      * @param input the InputStream to read from
436      * @return The converted string.
437      * @throws IOException in case of failure
438      * @deprecated use {@code org.apache.commons.io.IOUtils.toString()}.
439      */
440     @Deprecated
441     @Nonnull
442     public static String toString(@Nonnull final Reader input) throws IOException {
443         return toString(input, DEFAULT_BUFFER_SIZE);
444     }
445 
446     /**
447      * Get the contents of a <code>Reader</code> as a String.
448      *
449      * @param input the reader to read from
450      * @param bufferSize size of internal buffer
451      * @return the resulting byte array.
452      * @throws IOException in case of failure
453      * @deprecated use {@code org.apache.commons.io.IOUtils.toString()}.
454      */
455     @Deprecated
456     @Nonnull
457     public static String toString(@Nonnull final Reader input, final int bufferSize) throws IOException {
458         final StringWriter sw = new StringWriter();
459         copy(input, sw, bufferSize);
460         return sw.toString();
461     }
462 
463     ///////////////////////////////////////////////////////////////
464     // Reader -> byte[]
465 
466     /**
467      * Get the contents of a <code>Reader</code> as a <code>byte[]</code>.
468      *
469      * @param input the InputStream to read from
470      * @return the resulting byte array.
471      * @throws IOException in case of failure
472      * @deprecated always specify a character encoding
473      */
474     @Deprecated
475     @Nonnull
476     public static byte[] toByteArray(@Nonnull final Reader input) throws IOException {
477         return toByteArray(input, DEFAULT_BUFFER_SIZE);
478     }
479 
480     /**
481      * Get the contents of a <code>Reader</code> as a <code>byte[]</code>.
482      *
483      * @param input the InputStream to read from
484      * @param bufferSize size of internal buffer
485      * @return the resulting byte array.
486      * @throws IOException in case of failure
487      * @deprecated always specify a character encoding
488      */
489     @Deprecated
490     @Nonnull
491     public static byte[] toByteArray(@Nonnull final Reader input, final int bufferSize) throws IOException {
492         ByteArrayOutputStream output = new ByteArrayOutputStream();
493         copy(input, output, bufferSize);
494         return output.toByteArray();
495     }
496 
497     ///////////////////////////////////////////////////////////////
498     // Derived copy methods
499     // String -> *
500     ///////////////////////////////////////////////////////////////
501 
502     ///////////////////////////////////////////////////////////////
503     // String -> OutputStream
504 
505     /**
506      * Serialize chars from a <code>String</code> to bytes on an <code>OutputStream</code>, and
507      * flush the <code>OutputStream</code>.
508      * @param input the InputStream to read from
509      * @param output the output to write to
510      * @throws IOException in case of failure
511      * @deprecated always specify a character encoding
512      */
513     @Deprecated
514     public static void copy(@Nonnull final String input, @Nonnull final OutputStream output) throws IOException {
515         copy(input, output, DEFAULT_BUFFER_SIZE);
516     }
517 
518     /**
519      * Serialize chars from a <code>String</code> to bytes on an <code>OutputStream</code>, and
520      * flush the <code>OutputStream</code>.
521      *
522      * @param input the InputStream to read from
523      * @param output the output to write to
524      * @param bufferSize size of internal buffer
525      * @throws IOException in case of failure
526      * @deprecated always specify a character encoding
527      */
528     @Deprecated
529     public static void copy(@Nonnull final String input, @Nonnull final OutputStream output, final int bufferSize)
530             throws IOException {
531         final StringReader in = new StringReader(input);
532         final OutputStreamWriter out = new OutputStreamWriter(output);
533         copy(in, out, bufferSize);
534         // NOTE: Unless anyone is planning on rewriting OutputStreamWriter, we have to flush
535         // here.
536         out.flush();
537     }
538 
539     ///////////////////////////////////////////////////////////////
540     // String -> Writer
541 
542     /**
543      * Copy chars from a <code>String</code> to a <code>Writer</code>.
544      *
545      * @param input the string to write
546      * @param output resulting output {@link Writer}
547      * @throws IOException in case of failure
548      * @deprecated use {@code org.apache.commons.io.IOUtils.write()}.
549      */
550     @Deprecated
551     public static void copy(@Nonnull final String input, @Nonnull final Writer output) throws IOException {
552         output.write(input);
553     }
554 
555     ///////////////////////////////////////////////////////////////
556     // String -> byte[]
557 
558     /**
559      * Get the contents of a <code>String</code> as a <code>byte[]</code>.
560      *
561      * @param input the String to read from
562      * @return the resulting byte array
563      * @throws IOException in case of failure
564      * @deprecated always specify a character encoding
565      */
566     @Deprecated
567     @Nonnull
568     public static byte[] toByteArray(@Nonnull final String input) throws IOException {
569         return toByteArray(input, DEFAULT_BUFFER_SIZE);
570     }
571 
572     /**
573      * Get the contents of a <code>String</code> as a <code>byte[]</code>.
574      *
575      * @param input the InputStream to read from
576      * @param bufferSize size of internal buffer
577      * @return the resulting byte array
578      * @throws IOException in case of failure
579      * @deprecated always specify a character encoding
580      */
581     @Deprecated
582     @Nonnull
583     public static byte[] toByteArray(@Nonnull final String input, final int bufferSize) throws IOException {
584         ByteArrayOutputStream output = new ByteArrayOutputStream();
585         copy(input, output, bufferSize);
586         return output.toByteArray();
587     }
588 
589     ///////////////////////////////////////////////////////////////
590     // Derived copy methods
591     // byte[] -> *
592     ///////////////////////////////////////////////////////////////
593 
594     ///////////////////////////////////////////////////////////////
595     // byte[] -> Writer
596 
597     /**
598      * Copy and convert bytes from a <code>byte[]</code> to chars on a
599      * <code>Writer</code>.
600      * The platform's default encoding is used for the byte-to-char conversion.
601      *
602      * @param input the InputStream to read from
603      * @param output the output to write to
604      * @throws IOException in case of failure
605      * @deprecated always specify a character encoding
606      */
607     @Deprecated
608     public static void copy(@Nonnull final byte[] input, @Nonnull final Writer output) throws IOException {
609         copy(input, output, DEFAULT_BUFFER_SIZE);
610     }
611 
612     /**
613      * Copy and convert bytes from a <code>byte[]</code> to chars on a
614      * <code>Writer</code>.
615      * The platform's default encoding is used for the byte-to-char conversion.
616      *
617      * @param input the InputStream to read from
618      * @param output the output to write to
619      * @param bufferSize size of internal buffer
620      * @throws IOException in case of failure
621      * @deprecated always specify a character encoding
622      */
623     @Deprecated
624     public static void copy(@Nonnull final byte[] input, @Nonnull final Writer output, final int bufferSize)
625             throws IOException {
626         final ByteArrayInputStream in = new ByteArrayInputStream(input);
627         copy(in, output, bufferSize);
628     }
629 
630     /**
631      * Copy and convert bytes from a <code>byte[]</code> to chars on a
632      * <code>Writer</code>, using the specified encoding.
633      *
634      * @param encoding the name of a supported character encoding. See the
635      *                 <a href="https://www.iana.org/assignments/character-sets">IANA
636      *                 Charset Registry</a> for a list of valid encoding types.
637      * @param input the data to write
638      * @param output the writer to write to
639      * @throws IOException in case of failure
640      * @deprecated use {@code org.apache.commons.io.IOUtils.write()}.
641      */
642     @Deprecated
643     public static void copy(@Nonnull final byte[] input, @Nonnull final Writer output, final String encoding)
644             throws IOException {
645         final ByteArrayInputStream in = new ByteArrayInputStream(input);
646         copy(in, output, encoding);
647     }
648 
649     /**
650      * Copy and convert bytes from a <code>byte[]</code> to chars on a
651      * <code>Writer</code>, using the specified encoding.
652      *
653      * @param encoding   the name of a supported character encoding. See the
654      *                   <a href="https://www.iana.org/assignments/character-sets">IANA
655      *                   Charset Registry</a> for a list of valid encoding types.
656      * @param input the input bytes
657      * @param output The output buffer {@link Writer}
658      * @param bufferSize size of internal buffer
659      * @throws IOException in case of failure
660      * @deprecated use {@code org.apache.commons.io.IOUtils.write()}.
661      */
662     @Deprecated
663     public static void copy(
664             @Nonnull final byte[] input,
665             @Nonnull final Writer output,
666             @Nonnull final String encoding,
667             final int bufferSize)
668             throws IOException {
669         final ByteArrayInputStream in = new ByteArrayInputStream(input);
670         copy(in, output, encoding, bufferSize);
671     }
672 
673     ///////////////////////////////////////////////////////////////
674     // byte[] -> String
675 
676     /**
677      * Get the contents of a <code>byte[]</code> as a String.
678      * The platform's default encoding is used for the byte-to-char conversion.
679      * @param input the input bytes
680      * @return the resulting string
681      * @throws IOException in case of failure
682      * @deprecated always specify a character encoding
683      */
684     @Deprecated
685     @Nonnull
686     public static String toString(@Nonnull final byte[] input) throws IOException {
687         return toString(input, DEFAULT_BUFFER_SIZE);
688     }
689 
690     /**
691      * Get the contents of a <code>byte[]</code> as a String.
692      * The platform's default encoding is used for the byte-to-char conversion.
693      *
694      * @param bufferSize size of internal buffer
695      * @param input the input bytes
696      * @return the created string
697      * @throws IOException in case of failure
698      * @deprecated always specify a character encoding
699      */
700     @Deprecated
701     @Nonnull
702     public static String toString(@Nonnull final byte[] input, final int bufferSize) throws IOException {
703         final StringWriter sw = new StringWriter();
704         copy(input, sw, bufferSize);
705         return sw.toString();
706     }
707 
708     /**
709      * Get the contents of a <code>byte[]</code> as a String.
710      *
711      * @param encoding the name of a supported character encoding. See the
712      *                 <a href="https://www.iana.org/assignments/character-sets">IANA
713      *                 Charset Registry</a> for a list of valid encoding types.
714      * @param input the input bytes
715      * @return the resulting string
716      * @throws IOException in case of failure
717      * @deprecated use {@code new String(input, encoding)}
718      */
719     @Deprecated
720     @Nonnull
721     public static String toString(@Nonnull final byte[] input, @Nonnull final String encoding) throws IOException {
722         return toString(input, encoding, DEFAULT_BUFFER_SIZE);
723     }
724 
725     /**
726      * Get the contents of a <code>byte[]</code> as a String.
727      *
728      * @param encoding   the name of a supported character encoding. See the
729      *                   <a href="https://www.iana.org/assignments/character-sets">IANA
730      *                   Charset Registry</a> for a list of valid encoding types.
731      * @param bufferSize size of internal buffer
732      * @param input input bytes
733      * @return the resulting string
734      * @throws IOException in case of failure
735      * @deprecated use {@code new String(input, encoding)}
736      */
737     @Deprecated
738     @Nonnull
739     public static String toString(@Nonnull final byte[] input, @Nonnull final String encoding, final int bufferSize)
740             throws IOException {
741         final StringWriter sw = new StringWriter();
742         copy(input, sw, encoding, bufferSize);
743         return sw.toString();
744     }
745 
746     ///////////////////////////////////////////////////////////////
747     // byte[] -> OutputStream
748 
749     /**
750      * Copy bytes from a <code>byte[]</code> to an <code>OutputStream</code>.
751      *
752      * @param input Input byte array.
753      * @param output output stream {@link OutputStream}
754      * @throws IOException in case of failure
755      * @deprecated inline this method
756      */
757     @Deprecated
758     public static void copy(@Nonnull final byte[] input, @Nonnull final OutputStream output) throws IOException {
759         output.write(input);
760     }
761 
762     /**
763      * Compare the contents of two streams to determine if they are equal or not.
764      *
765      * @param input1 the first stream
766      * @param input2 the second stream
767      * @return true if the content of the streams are equal or they both don't exist, false otherwise
768      * @throws IOException in case of failure
769      * @deprecated use {@code org.apache.commons.io.IOUtils.contentEquals()}
770      */
771     @Deprecated
772     public static boolean contentEquals(@Nonnull final InputStream input1, @Nonnull final InputStream input2)
773             throws IOException {
774         final InputStream bufferedInput1 = new BufferedInputStream(input1);
775         final InputStream bufferedInput2 = new BufferedInputStream(input2);
776 
777         int ch = bufferedInput1.read();
778         while (-1 != ch) {
779             final int ch2 = bufferedInput2.read();
780             if (ch != ch2) {
781                 return false;
782             }
783             ch = bufferedInput1.read();
784         }
785 
786         final int ch2 = bufferedInput2.read();
787         return -1 == ch2;
788     }
789 
790     // ----------------------------------------------------------------------
791     // closeXXX()
792     // ----------------------------------------------------------------------
793 
794     /**
795      * <p>Closes a {@code Channel} suppressing any {@code IOException}.</p>
796      * <p>
797      * <b>Note:</b> The use case justifying this method is a shortcoming of the Java language up to but not including
798      * Java 7. For any code targeting Java 7 or later use of this method is highly discouraged and the
799      * {@code try-with-resources} statement should be used instead. Care must be taken to not use this method in a way
800      * {@code IOException}s get suppressed incorrectly.
801      * <strong>You must close all resources in use inside the {@code try} block to not suppress exceptions in the
802      * {@code finally} block incorrectly by using this method.</strong>
803      * </p>
804      * <p>
805      * <b>Example:</b>
806      * </p>
807      * <pre>
808      * // Introduce variables for the resources and initialize them to null. This cannot throw an exception.
809      * Closeable resource1 = null;
810      * Closeable resource2 = null;
811      * try
812      * {
813      *     // Obtain a resource object and assign it to variable resource1. This may throw an exception.
814      *     // If successful, resource1 != null.
815      *     resource1 = ...
816      *
817      *     // Obtain a resource object and assign it to variable resource2. This may throw an exception.
818      *     // If successful, resource2 != null. Not reached if an exception has been thrown above.
819      *     resource2 = ...
820      *
821      *     // Perform operations on the resources. This may throw an exception. Not reached if an exception has been
822      *     // thrown above. Note: Treat the variables resource1 and resource2 the same way as if they would have been
823      *     // declared with the final modifier - that is - do NOT write anyting like resource1 = something else or
824      *     // resource2 = something else here.
825      *     resource1 ...
826      *     resource2 ...
827      *
828      *     // Finally, close the resources and set the variables to null indicating successful completion.
829      *     // This may throw an exception. Not reached if an exception has been thrown above.
830      *     resource1.close();
831      *     resource1 = null;
832      *     // Not reached if an exception has been thrown above.
833      *     resource2.close();
834      *     resource2 = null;
835      *
836      *     // All resources are closed at this point and all operations (up to here) completed successfully without
837      *     // throwing an exception we would need to handle (by letting it propagate or by catching and handling it).
838      * }
839      * finally
840      * {
841      *     // Cleanup any resource not closed in the try block due to an exception having been thrown and suppress any
842      *     // exception this may produce to not stop the exception from the try block to be propagated. If the try
843      *     // block completed successfully, all variables will have been set to null there and this will not do
844      *     // anything. This is just to cleanup properly in case of an exception.
845      *
846      *     IOUtil.close( resource1 );
847      *     IOUtil.close( resource2 );
848      *
849      *     // Without that utility method you would need to write the following:
850      *     //
851      *     // try
852      *     // {
853      *     //     if ( resource1 != null )
854      *     //     {
855      *     //         resource1.close();
856      *     //     }
857      *     // }
858      *     // catch( IOException e )
859      *     // {
860      *     //     Suppressed. If resource1 != null, an exception has already been thrown in the try block we need to
861      *     //     propagate instead of this one.
862      *     // }
863      *     // finally
864      *     // {
865      *     //     try
866      *     //     {
867      *     //         if ( resource2 != null )
868      *     //         {
869      *     //             resource2.close();
870      *     //         }
871      *     //     }
872      *     //     catch ( IOException e )
873      *     //     {
874      *     //         Suppressed. If resource2 != null, an exception has already been thrown in the try block we need to
875      *     //         propagate instead of this one.
876      *     //     }
877      *     // }
878      * }
879      * </pre>
880      *
881      * @param channel The channel to close or {@code null}.
882      * @deprecated use try-with-resources
883      */
884     @Deprecated
885     public static void close(@Nullable Channel channel) {
886         try {
887             if (channel != null) {
888                 channel.close();
889             }
890         } catch (IOException ex) {
891             // Suppressed
892         }
893     }
894 
895     /**
896      * <p>Closes an {@code InputStream} suppressing any {@code IOException}.</p>
897      * <p>
898      * <b>Note:</b> The use case justifying this method is a shortcoming of the Java language up to but not including
899      * Java 7. For any code targeting Java 7 or later use of this method is highly discouraged and the
900      * {@code try-with-resources} statement should be used instead. Care must be taken to not use this method in a way
901      * {@code IOException}s get suppressed incorrectly.
902      * <strong>You must close all resources in use inside the {@code try} block to not suppress exceptions in the
903      * {@code finally} block incorrectly by using this method.</strong>
904      * </p>
905      * <p>
906      * <b>Example:</b>
907      * </p>
908      * <pre>
909      * // Introduce variables for the resources and initialize them to null. This cannot throw an exception.
910      * Closeable resource1 = null;
911      * Closeable resource2 = null;
912      * try
913      * {
914      *     // Obtain a resource object and assign it to variable resource1. This may throw an exception.
915      *     // If successful, resource1 != null.
916      *     resource1 = ...
917      *
918      *     // Obtain a resource object and assign it to variable resource2. This may throw an exception.
919      *     // If successful, resource2 != null. Not reached if an exception has been thrown above.
920      *     resource2 = ...
921      *
922      *     // Perform operations on the resources. This may throw an exception. Not reached if an exception has been
923      *     // thrown above. Note: Treat the variables resource1 and resource2 the same way as if they would have been
924      *     // declared with the final modifier - that is - do NOT write anyting like resource1 = something else or
925      *     // resource2 = something else here.
926      *     resource1 ...
927      *     resource2 ...
928      *
929      *     // Finally, close the resources and set the variables to null indicating successful completion.
930      *     // This may throw an exception. Not reached if an exception has been thrown above.
931      *     resource1.close();
932      *     resource1 = null;
933      *     // This may throw an exception. Not reached if an exception has been thrown above.
934      *     resource2.close();
935      *     resource2 = null;
936      *
937      *     // All resources are closed at this point and all operations (up to here) completed successfully without
938      *     // throwing an exception we would need to handle (by letting it propagate or by catching and handling it).
939      * }
940      * finally
941      * {
942      *     // Cleanup any resource not closed in the try block due to an exception having been thrown and suppress any
943      *     // exception this may produce to not stop the exception from the try block to be propagated. If the try
944      *     // block completed successfully, all variables will have been set to null there and this will not do
945      *     // anything. This is just to cleanup properly in case of an exception.
946      *
947      *     IOUtil.close( resource1 );
948      *     IOUtil.close( resource2 );
949      *
950      *     // Without that utility method you would need to write the following:
951      *     //
952      *     // try
953      *     // {
954      *     //     if ( resource1 != null )
955      *     //     {
956      *     //         resource1.close();
957      *     //     }
958      *     // }
959      *     // catch( IOException e )
960      *     // {
961      *     //     Suppressed. If resource1 != null, an exception has already been thrown in the try block we need to
962      *     //     propagate instead of this one.
963      *     // }
964      *     // finally
965      *     // {
966      *     //     try
967      *     //     {
968      *     //         if ( resource2 != null )
969      *     //         {
970      *     //             resource2.close();
971      *     //         }
972      *     //     }
973      *     //     catch ( IOException e )
974      *     //     {
975      *     //         Suppressed. If resource2 != null, an exception has already been thrown in the try block we need to
976      *     //         propagate instead of this one.
977      *     //     }
978      *     // }
979      * }
980      * </pre>
981      *
982      * @param inputStream The stream to close or {@code null}.
983      * @deprecated use try-with-resources
984      */
985     @Deprecated
986     public static void close(@Nullable InputStream inputStream) {
987         try {
988             if (inputStream != null) {
989                 inputStream.close();
990             }
991         } catch (IOException ex) {
992             // Suppressed
993         }
994     }
995 
996     /**
997      * <p>Closes an {@code OutputStream} suppressing any {@code IOException}.</p>
998      * <p>
999      * <b>Note:</b> The use case justifying this method is a shortcoming of the Java language up to but not including
1000      * Java 7. For any code targeting Java 7 or later use of this method is highly discouraged and the
1001      * {@code try-with-resources} statement should be used instead. Care must be taken to not use this method in a way
1002      * {@code IOException}s get suppressed incorrectly.
1003      * <strong>You must close all resources in use inside the {@code try} block to not suppress exceptions in the
1004      * {@code finally} block incorrectly by using this method.</strong>
1005      * </p>
1006      * <p>
1007      * <b>Example:</b>
1008      * </p>
1009      * <pre>
1010      * // Introduce variables for the resources and initialize them to null. This cannot throw an exception.
1011      * Closeable resource1 = null;
1012      * Closeable resource2 = null;
1013      * try
1014      * {
1015      *     // Obtain a resource object and assign it to variable resource1. This may throw an exception.
1016      *     // If successful, resource1 != null.
1017      *     resource1 = ...
1018      *
1019      *     // Obtain a resource object and assign it to variable resource2. This may throw an exception.
1020      *     // If successful, resource2 != null. Not reached if an exception has been thrown above.
1021      *     resource2 = ...
1022      *
1023      *     // Perform operations on the resources. This may throw an exception. Not reached if an exception has been
1024      *     // thrown above. Note: Treat the variables resource1 and resource2 the same way as if they would have been
1025      *     // declared with the final modifier - that is - do NOT write anyting like resource1 = something else or
1026      *     // resource2 = something else here.
1027      *     resource1 ...
1028      *     resource2 ...
1029      *
1030      *     // Finally, close the resources and set the variables to null indicating successful completion.
1031      *     // This may throw an exception. Not reached if an exception has been thrown above.
1032      *     resource1.close();
1033      *     resource1 = null;
1034      *     // This may throw an exception. Not reached if an exception has been thrown above.
1035      *     resource2.close();
1036      *     resource2 = null;
1037      *
1038      *     // All resources are closed at this point and all operations (up to here) completed successfully without
1039      *     // throwing an exception we would need to handle (by letting it propagate or by catching and handling it).
1040      * }
1041      * finally
1042      * {
1043      *     // Cleanup any resource not closed in the try block due to an exception having been thrown and suppress any
1044      *     // exception this may produce to not stop the exception from the try block to be propagated. If the try
1045      *     // block completed successfully, all variables will have been set to null there and this will not do
1046      *     // anything. This is just to cleanup properly in case of an exception.
1047      *
1048      *     IOUtil.close( resource1 );
1049      *     IOUtil.close( resource2 );
1050      *
1051      *     // Without that utility method you would need to write the following:
1052      *     //
1053      *     // try
1054      *     // {
1055      *     //     if ( resource1 != null )
1056      *     //     {
1057      *     //         resource1.close();
1058      *     //     }
1059      *     // }
1060      *     // catch( IOException e )
1061      *     // {
1062      *     //     Suppressed. If resource1 != null, an exception has already been thrown in the try block we need to
1063      *     //     propagate instead of this one.
1064      *     // }
1065      *     // finally
1066      *     // {
1067      *     //     try
1068      *     //     {
1069      *     //         if ( resource2 != null )
1070      *     //         {
1071      *     //             resource2.close();
1072      *     //         }
1073      *     //     }
1074      *     //     catch ( IOException e )
1075      *     //     {
1076      *     //         Suppressed. If resource2 != null, an exception has already been thrown in the try block we need to
1077      *     //         propagate instead of this one.
1078      *     //     }
1079      *     // }
1080      * }
1081      * </pre>
1082      *
1083      * @param outputStream The stream to close or {@code null}.
1084      * @deprecated use try-with-resources
1085      */
1086     @Deprecated
1087     public static void close(@Nullable OutputStream outputStream) {
1088         try {
1089             if (outputStream != null) {
1090                 outputStream.close();
1091             }
1092         } catch (IOException ex) {
1093             // Suppressed
1094         }
1095     }
1096 
1097     /**
1098      * <p>Closes a {@code Reader} suppressing any {@code IOException}.</p>
1099      * <p>
1100      * <b>Note:</b> The use case justifying this method is a shortcoming of the Java language up to but not including
1101      * Java 7. For any code targeting Java 7 or later use of this method is highly discouraged and the
1102      * {@code try-with-resources} statement should be used instead. Care must be taken to not use this method in a way
1103      * {@code IOException}s get suppressed incorrectly.
1104      * <strong>You must close all resources in use inside the {@code try} block to not suppress exceptions in the
1105      * {@code finally} block incorrectly by using this method.</strong>
1106      * </p>
1107      * <p>
1108      * <b>Example:</b>
1109      * </p>
1110      * <pre>
1111      * // Introduce variables for the resources and initialize them to null. This cannot throw an exception.
1112      * Closeable resource1 = null;
1113      * Closeable resource2 = null;
1114      * try
1115      * {
1116      *     // Obtain a resource object and assign it to variable resource1. This may throw an exception.
1117      *     // If successful, resource1 != null.
1118      *     resource1 = ...
1119      *
1120      *     // Obtain a resource object and assign it to variable resource2. This may throw an exception.
1121      *     // If successful, resource2 != null. Not reached if an exception has been thrown above.
1122      *     resource2 = ...
1123      *
1124      *     // Perform operations on the resources. This may throw an exception. Not reached if an exception has been
1125      *     // thrown above. Note: Treat the variables resource1 and resource2 the same way as if they would have been
1126      *     // declared with the final modifier - that is - do NOT write anyting like resource1 = something else or
1127      *     // resource2 = something else here.
1128      *     resource1 ...
1129      *     resource2 ...
1130      *
1131      *     // Finally, close the resources and set the variables to null indicating successful completion.
1132      *     // This may throw an exception. Not reached if an exception has been thrown above.
1133      *     resource1.close();
1134      *     resource1 = null;
1135      *     // This may throw an exception. Not reached if an exception has been thrown above.
1136      *     resource2.close();
1137      *     resource2 = null;
1138      *
1139      *     // All resources are closed at this point and all operations (up to here) completed successfully without
1140      *     // throwing an exception we would need to handle (by letting it propagate or by catching and handling it).
1141      * }
1142      * finally
1143      * {
1144      *     // Cleanup any resource not closed in the try block due to an exception having been thrown and suppress any
1145      *     // exception this may produce to not stop the exception from the try block to be propagated. If the try
1146      *     // block completed successfully, all variables will have been set to null there and this will not do
1147      *     // anything. This is just to cleanup properly in case of an exception.
1148      *
1149      *     IOUtil.close( resource1 );
1150      *     IOUtil.close( resource2 );
1151      *
1152      *     // Without that utility method you would need to write the following:
1153      *     //
1154      *     // try
1155      *     // {
1156      *     //     if ( resource1 != null )
1157      *     //     {
1158      *     //         resource1.close();
1159      *     //     }
1160      *     // }
1161      *     // catch( IOException e )
1162      *     // {
1163      *     //     Suppressed. If resource1 != null, an exception has already been thrown in the try block we need to
1164      *     //     propagate instead of this one.
1165      *     // }
1166      *     // finally
1167      *     // {
1168      *     //     try
1169      *     //     {
1170      *     //         if ( resource2 != null )
1171      *     //         {
1172      *     //             resource2.close();
1173      *     //         }
1174      *     //     }
1175      *     //     catch ( IOException e )
1176      *     //     {
1177      *     //         Suppressed. If resource2 != null, an exception has already been thrown in the try block we need to
1178      *     //         propagate instead of this one.
1179      *     //     }
1180      *     // }
1181      * }
1182      * </pre>
1183      *
1184      * @param reader The reader to close or {@code null}.
1185      * @deprecated use try-with-resources
1186      */
1187     @Deprecated
1188     public static void close(@Nullable Reader reader) {
1189         try {
1190             if (reader != null) {
1191                 reader.close();
1192             }
1193         } catch (IOException ex) {
1194             // Suppressed
1195         }
1196     }
1197 
1198     /**
1199      * <p>Closes a {@code Writer} suppressing any {@code IOException}.</p>
1200      * <p>
1201      * <b>Note:</b> The use case justifying this method is a shortcoming of the Java language up to but not including
1202      * Java 7. For any code targeting Java 7 or later use of this method is highly discouraged and the
1203      * {@code try-with-resources} statement should be used instead. Care must be taken to not use this method in a way
1204      * {@code IOException}s get suppressed incorrectly.
1205      * <strong>You must close all resources in use inside the {@code try} block to not suppress exceptions in the
1206      * {@code finally} block incorrectly by using this method.</strong>
1207      * </p>
1208      * <p>
1209      * <b>Example:</b>
1210      * </p>
1211      * <pre>
1212      * // Introduce variables for the resources and initialize them to null. This cannot throw an exception.
1213      * Closeable resource1 = null;
1214      * Closeable resource2 = null;
1215      * try
1216      * {
1217      *     // Obtain a resource object and assign it to variable resource1. This may throw an exception.
1218      *     // If successful, resource1 != null.
1219      *     resource1 = ...
1220      *
1221      *     // Obtain a resource object and assign it to variable resource2. This may throw an exception.
1222      *     // If successful, resource2 != null. Not reached if an exception has been thrown above.
1223      *     resource2 = ...
1224      *
1225      *     // Perform operations on the resources. This may throw an exception. Not reached if an exception has been
1226      *     // thrown above. Note: Treat the variables resource1 and resource2 the same way as if they would have been
1227      *     // declared with the final modifier - that is - do NOT write anyting like resource1 = something else or
1228      *     // resource2 = something else here.
1229      *     resource1 ...
1230      *     resource2 ...
1231      *
1232      *     // Finally, close the resources and set the variables to null indicating successful completion.
1233      *     // This may throw an exception. Not reached if an exception has been thrown above.
1234      *     resource1.close();
1235      *     resource1 = null;
1236      *     // This may throw an exception. Not reached if an exception has been thrown above.
1237      *     resource2.close();
1238      *     resource2 = null;
1239      *
1240      *     // All resources are closed at this point and all operations (up to here) completed successfully without
1241      *     // throwing an exception we would need to handle (by letting it propagate or by catching and handling it).
1242      * }
1243      * finally
1244      * {
1245      *     // Cleanup any resource not closed in the try block due to an exception having been thrown and suppress any
1246      *     // exception this may produce to not stop the exception from the try block to be propagated. If the try
1247      *     // block completed successfully, all variables will have been set to null there and this will not do
1248      *     // anything. This is just to cleanup properly in case of an exception.
1249      *
1250      *     IOUtil.close( resource1 );
1251      *     IOUtil.close( resource2 );
1252      *
1253      *     // Without that utility method you would need to write the following:
1254      *     //
1255      *     // try
1256      *     // {
1257      *     //     if ( resource1 != null )
1258      *     //     {
1259      *     //         resource1.close();
1260      *     //     }
1261      *     // }
1262      *     // catch( IOException e )
1263      *     // {
1264      *     //     Suppressed. If resource1 != null, an exception has already been thrown in the try block we need to
1265      *     //     propagate instead of this one.
1266      *     // }
1267      *     // finally
1268      *     // {
1269      *     //     try
1270      *     //     {
1271      *     //         if ( resource2 != null )
1272      *     //         {
1273      *     //             resource2.close();
1274      *     //         }
1275      *     //     }
1276      *     //     catch ( IOException e )
1277      *     //     {
1278      *     //         Suppressed. If resource2 != null, an exception has already been thrown in the try block we need to
1279      *     //         propagate instead of this one.
1280      *     //     }
1281      *     // }
1282      * }
1283      * </pre>
1284      *
1285      * @param writer The writer to close or {@code null}.
1286      * @deprecated use try-with-resources
1287      */
1288     @Deprecated
1289     public static void close(@Nullable Writer writer) {
1290         try {
1291             if (writer != null) {
1292                 writer.close();
1293             }
1294         } catch (IOException ex) {
1295             // Suppressed
1296         }
1297     }
1298 }