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 -> 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 }