org.codehaus.plexus.util

## Class IOUtil

- java.lang.Object
- - org.codehaus.plexus.util.IOUtil

    public final class IOUtil
    extends Object

General IO Stream manipulation.

This class provides static utility methods for input/output operations, particularly buffered copying between sources (`InputStream`, `Reader`, `String` and `byte[]`) and destinations (`OutputStream`, `Writer`, `String` and `byte[]`).

Unless otherwise noted, these `copy` methods do not flush or close the streams. Often, doing so would require making non-portable assumptions about the streams' origin and further use. This means that both streams' `close()` methods must be called after copying. if one omits this step, then the stream resources (sockets, file descriptors) are released when the associated Stream is garbage-collected. It is not a good idea to rely on this mechanism. For a good overview of the distinction between "memory management" and "resource management", see this UnixReview article

For each `copy` method, a variant is provided that allows the caller to specify the buffer size (the default is 4k). As the buffer size can have a fairly large impact on speed, this may be worth tweaking. Often "large buffer -> faster" does not hold, even for large data transfers.

For byte-to-char methods, a `copy` variant allows the encoding to be selected (otherwise the platform default is used).

The `copy` methods use an internal buffer when copying. It is therefore advisable not to deliberately wrap the stream arguments to the `copy` methods in `Buffered*` streams. For example, don't do the following:

`copy( new BufferedInputStream( in ), new BufferedOutputStream( out ) );`

The rationale is as follows:

Imagine that an InputStream's read() is a very expensive operation, which would usually suggest wrapping in a BufferedInputStream. The BufferedInputStream works by issuing infrequent `InputStream.read(byte[] b, int off, int len)` requests on the underlying InputStream, to fill an internal buffer, from which further `read` requests can inexpensively get their data (until the buffer runs out).

However, the `copy` methods do the same thing, keeping an internal buffer, populated by `InputStream.read(byte[] b, int off, int len)` requests. Having two buffers (or three if the destination stream is also buffered) is pointless, and the unnecessary buffer management hurts performance slightly (about 3%, according to some simple experiments).

Since:
  4.0
Version:
  $Id$
Author:
  Peter Donald, Jeff Turner

### Method Summary

All Methods Static Methods Concrete Methods Deprecated Methods
`static void` `bufferedCopy(InputStream input, OutputStream output)` Deprecated. Buffering streams is actively harmful! See the class description as to why. Use `copy(InputStream, OutputStream)` instead.
`static void` `close(Channel channel)` Closes a channel.
`static void` `close(InputStream inputStream)` Closes the input stream.
`static void` `close(OutputStream outputStream)` Closes the output stream.
`static void` `close(Reader reader)` Closes the reader.
`static void` `close(Writer writer)` Closes the writer.
`static boolean` `contentEquals(InputStream input1, InputStream input2)` Compare the contents of two Streams to determine if they are equal or not.
`static void` `copy(byte[] input, OutputStream output)` Copy bytes from a `byte[]` to an `OutputStream`.
`static void` `copy(byte[] input, OutputStream output, int bufferSize)` Copy bytes from a `byte[]` to an `OutputStream`.
`static void` `copy(byte[] input, Writer output)` Copy and convert bytes from a `byte[]` to chars on a `Writer`.
`static void` `copy(byte[] input, Writer output, int bufferSize)` Copy and convert bytes from a `byte[]` to chars on a `Writer`.
`static void` `copy(byte[] input, Writer output, String encoding)` Copy and convert bytes from a `byte[]` to chars on a `Writer`, using the specified encoding.
`static void` `copy(byte[] input, Writer output, String encoding, int bufferSize)` Copy and convert bytes from a `byte[]` to chars on a `Writer`, using the specified encoding.
`static void` `copy(InputStream input, OutputStream output)` Copy bytes from an `InputStream` to an `OutputStream`.
`static void` `copy(InputStream input, OutputStream output, int bufferSize)` Copy bytes from an `InputStream` to an `OutputStream`.
`static void` `copy(InputStream input, Writer output)` Copy and convert bytes from an `InputStream` to chars on a `Writer`.
`static void` `copy(InputStream input, Writer output, int bufferSize)` Copy and convert bytes from an `InputStream` to chars on a `Writer`.
`static void` `copy(InputStream input, Writer output, String encoding)` Copy and convert bytes from an `InputStream` to chars on a `Writer`, using the specified encoding.
`static void` `copy(InputStream input, Writer output, String encoding, int bufferSize)` Copy and convert bytes from an `InputStream` to chars on a `Writer`, using the specified encoding.
`static void` `copy(Reader input, OutputStream output)` Serialize chars from a `Reader` to bytes on an `OutputStream`, and flush the `OutputStream`.
`static void` `copy(Reader input, OutputStream output, int bufferSize)` Serialize chars from a `Reader` to bytes on an `OutputStream`, and flush the `OutputStream`.
`static void` `copy(Reader input, Writer output)` Copy chars from a `Reader` to a `Writer`.
`static void` `copy(Reader input, Writer output, int bufferSize)` Copy chars from a `Reader` to a `Writer`.
`static void` `copy(String input, OutputStream output)` Serialize chars from a `String` to bytes on an `OutputStream`, and flush the `OutputStream`.
`static void` `copy(String input, OutputStream output, int bufferSize)` Serialize chars from a `String` to bytes on an `OutputStream`, and flush the `OutputStream`.
`static void` `copy(String input, Writer output)` Copy chars from a `String` to a `Writer`.
`static byte[]` `toByteArray(InputStream input)` Get the contents of an `InputStream` as a `byte[]`.
`static byte[]` `toByteArray(InputStream input, int bufferSize)` Get the contents of an `InputStream` as a `byte[]`.
`static byte[]` `toByteArray(Reader input)` Get the contents of a `Reader` as a `byte[]`.
`static byte[]` `toByteArray(Reader input, int bufferSize)` Get the contents of a `Reader` as a `byte[]`.
`static byte[]` `toByteArray(String input)` Get the contents of a `String` as a `byte[]`.
`static byte[]` `toByteArray(String input, int bufferSize)` Get the contents of a `String` as a `byte[]`.
`static String` `toString(byte[] input)` Get the contents of a `byte[]` as a String.
`static String` `toString(byte[] input, int bufferSize)` Get the contents of a `byte[]` as a String.
`static String` `toString(byte[] input, String encoding)` Get the contents of a `byte[]` as a String.
`static String` `toString(byte[] input, String encoding, int bufferSize)` Get the contents of a `byte[]` as a String.
`static String` `toString(InputStream input)` Get the contents of an `InputStream` as a String.
`static String` `toString(InputStream input, int bufferSize)` Get the contents of an `InputStream` as a String.
`static String` `toString(InputStream input, String encoding)` Get the contents of an `InputStream` as a String.
`static String` `toString(InputStream input, String encoding, int bufferSize)` Get the contents of an `InputStream` as a String.
`static String` `toString(Reader input)` Get the contents of a `Reader` as a String.
`static String` `toString(Reader input, int bufferSize)` Get the contents of a `Reader` as a String.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Method Detail

#### copy

    public static void copy(InputStream input,
                            OutputStream output)
                     throws IOException

Copy bytes from an `InputStream` to an `OutputStream`.

Throws:
  `IOException`

#### copy

    public static void copy(InputStream input,
                            OutputStream output,
                            int bufferSize)
                     throws IOException

Copy bytes from an `InputStream` to an `OutputStream`.

Parameters:
  `bufferSize` - Size of internal buffer to use.
Throws:
  `IOException`

#### copy

    public static void copy(Reader input,
                            Writer output)
                     throws IOException

Copy chars from a `Reader` to a `Writer`.

Throws:
  `IOException`

#### copy

    public static void copy(Reader input,
                            Writer output,
                            int bufferSize)
                     throws IOException

Copy chars from a `Reader` to a `Writer`.

Parameters:
  `bufferSize` - Size of internal buffer to use.
Throws:
  `IOException`

#### copy

    public static void copy(InputStream input,
                            Writer output)
                     throws IOException

Copy and convert bytes from an `InputStream` to chars on a `Writer`. The platform's default encoding is used for the byte-to-char conversion.

Throws:
  `IOException`

#### copy

    public static void copy(InputStream input,
                            Writer output,
                            int bufferSize)
                     throws IOException

Copy and convert bytes from an `InputStream` to chars on a `Writer`. The platform's default encoding is used for the byte-to-char conversion.

Parameters:
  `bufferSize` - Size of internal buffer to use.
Throws:
  `IOException`

#### copy

    public static void copy(InputStream input,
                            Writer output,
                            String encoding)
                     throws IOException

Copy and convert bytes from an `InputStream` to chars on a `Writer`, using the specified encoding.

Parameters:
  `encoding` - The name of a supported character encoding. See the IANA Charset Registry for a list of valid encoding types.
Throws:
  `IOException`

#### copy

    public static void copy(InputStream input,
                            Writer output,
                            String encoding,
                            int bufferSize)
                     throws IOException

Copy and convert bytes from an `InputStream` to chars on a `Writer`, using the specified encoding.

Parameters:
  `encoding` - The name of a supported character encoding. See the IANA Charset Registry for a list of valid encoding types.
  `bufferSize` - Size of internal buffer to use.
Throws:
  `IOException`

#### toString

    public static String toString(InputStream input)
                           throws IOException

Get the contents of an `InputStream` as a String. The platform's default encoding is used for the byte-to-char conversion.

Throws:
  `IOException`

#### toString

    public static String toString(InputStream input,
                                  int bufferSize)
                           throws IOException

Get the contents of an `InputStream` as a String. The platform's default encoding is used for the byte-to-char conversion.

Parameters:
  `bufferSize` - Size of internal buffer to use.
Throws:
  `IOException`

#### toString

    public static String toString(InputStream input,
                                  String encoding)
                           throws IOException

Get the contents of an `InputStream` as a String.

Parameters:
  `encoding` - The name of a supported character encoding. See the IANA Charset Registry for a list of valid encoding types.
Throws:
  `IOException`

#### toString

    public static String toString(InputStream input,
                                  String encoding,
                                  int bufferSize)
                           throws IOException

Get the contents of an `InputStream` as a String.

Parameters:
  `encoding` - The name of a supported character encoding. See the IANA Charset Registry for a list of valid encoding types.
  `bufferSize` - Size of internal buffer to use.
Throws:
  `IOException`

#### toByteArray

    public static byte[] toByteArray(InputStream input)
                              throws IOException

Get the contents of an `InputStream` as a `byte[]`.

Throws:
  `IOException`

#### toByteArray

    public static byte[] toByteArray(InputStream input,
                                     int bufferSize)
                              throws IOException

Get the contents of an `InputStream` as a `byte[]`.

Parameters:
  `bufferSize` - Size of internal buffer to use.
Throws:
  `IOException`

#### copy

    public static void copy(Reader input,
                            OutputStream output)
                     throws IOException

Serialize chars from a `Reader` to bytes on an `OutputStream`, and flush the `OutputStream`.

Throws:
  `IOException`

#### copy

    public static void copy(Reader input,
                            OutputStream output,
                            int bufferSize)
                     throws IOException

Serialize chars from a `Reader` to bytes on an `OutputStream`, and flush the `OutputStream`.

Parameters:
  `bufferSize` - Size of internal buffer to use.
Throws:
  `IOException`

#### toString

    public static String toString(Reader input)
                           throws IOException

Get the contents of a `Reader` as a String.

Throws:
  `IOException`

#### toString

    public static String toString(Reader input,
                                  int bufferSize)
                           throws IOException

Get the contents of a `Reader` as a String.

Parameters:
  `bufferSize` - Size of internal buffer to use.
Throws:
  `IOException`

#### toByteArray

    public static byte[] toByteArray(Reader input)
                              throws IOException

Get the contents of a `Reader` as a `byte[]`.

Throws:
  `IOException`

#### toByteArray

    public static byte[] toByteArray(Reader input,
                                     int bufferSize)
                              throws IOException

Get the contents of a `Reader` as a `byte[]`.

Parameters:
  `bufferSize` - Size of internal buffer to use.
Throws:
  `IOException`

#### copy

    public static void copy(String input,
                            OutputStream output)
                     throws IOException

Serialize chars from a `String` to bytes on an `OutputStream`, and flush the `OutputStream`.

Throws:
  `IOException`

#### copy

    public static void copy(String input,
                            OutputStream output,
                            int bufferSize)
                     throws IOException

Serialize chars from a `String` to bytes on an `OutputStream`, and flush the `OutputStream`.

Parameters:
  `bufferSize` - Size of internal buffer to use.
Throws:
  `IOException`

#### copy

    public static void copy(String input,
                            Writer output)
                     throws IOException

Copy chars from a `String` to a `Writer`.

Throws:
  `IOException`

#### bufferedCopy

    public static void bufferedCopy(InputStream input,
                                    OutputStream output)
                             throws IOException

Deprecated. Buffering streams is actively harmful! See the class description as to why. Use `copy(InputStream, OutputStream)` instead.
Copy bytes from an `InputStream` to an `OutputStream`, with buffering. This is equivalent to passing a `BufferedInputStream` and `BufferedOutputStream` to `copy(InputStream, OutputStream)`, and flushing the output stream afterwards. The streams are not closed after the copy.

Throws:
  `IOException`

#### toByteArray

    public static byte[] toByteArray(String input)
                              throws IOException

Get the contents of a `String` as a `byte[]`.

Throws:
  `IOException`

#### toByteArray

    public static byte[] toByteArray(String input,
                                     int bufferSize)
                              throws IOException

Get the contents of a `String` as a `byte[]`.

Parameters:
  `bufferSize` - Size of internal buffer to use.
Throws:
  `IOException`

#### copy

    public static void copy(byte[] input,
                            Writer output)
                     throws IOException

Copy and convert bytes from a `byte[]` to chars on a `Writer`. The platform's default encoding is used for the byte-to-char conversion.

Throws:
  `IOException`

#### copy

    public static void copy(byte[] input,
                            Writer output,
                            int bufferSize)
                     throws IOException

Copy and convert bytes from a `byte[]` to chars on a `Writer`. The platform's default encoding is used for the byte-to-char conversion.

Parameters:
  `bufferSize` - Size of internal buffer to use.
Throws:
  `IOException`

#### copy

    public static void copy(byte[] input,
                            Writer output,
                            String encoding)
                     throws IOException

Copy and convert bytes from a `byte[]` to chars on a `Writer`, using the specified encoding.

Parameters:
  `encoding` - The name of a supported character encoding. See the IANA Charset Registry for a list of valid encoding types.
Throws:
  `IOException`

#### copy

    public static void copy(byte[] input,
                            Writer output,
                            String encoding,
                            int bufferSize)
                     throws IOException

Copy and convert bytes from a `byte[]` to chars on a `Writer`, using the specified encoding.

Parameters:
  `encoding` - The name of a supported character encoding. See the IANA Charset Registry for a list of valid encoding types.
  `bufferSize` - Size of internal buffer to use.
Throws:
  `IOException`

#### toString

    public static String toString(byte[] input)
                           throws IOException

Get the contents of a `byte[]` as a String. The platform's default encoding is used for the byte-to-char conversion.

Throws:
  `IOException`

#### toString

    public static String toString(byte[] input,
                                  int bufferSize)
                           throws IOException

Get the contents of a `byte[]` as a String. The platform's default encoding is used for the byte-to-char conversion.

Parameters:
  `bufferSize` - Size of internal buffer to use.
Throws:
  `IOException`

#### toString

    public static String toString(byte[] input,
                                  String encoding)
                           throws IOException

Get the contents of a `byte[]` as a String.

Parameters:
  `encoding` - The name of a supported character encoding. See the IANA Charset Registry for a list of valid encoding types.
Throws:
  `IOException`

#### toString

    public static String toString(byte[] input,
                                  String encoding,
                                  int bufferSize)
                           throws IOException

Get the contents of a `byte[]` as a String.

Parameters:
  `encoding` - The name of a supported character encoding. See the IANA Charset Registry for a list of valid encoding types.
  `bufferSize` - Size of internal buffer to use.
Throws:
  `IOException`

#### copy

    public static void copy(byte[] input,
                            OutputStream output)
                     throws IOException

Copy bytes from a `byte[]` to an `OutputStream`.

Throws:
  `IOException`

#### copy

    public static void copy(byte[] input,
                            OutputStream output,
                            int bufferSize)
                     throws IOException

Copy bytes from a `byte[]` to an `OutputStream`.

Parameters:
  `bufferSize` - Size of internal buffer to use.
Throws:
  `IOException`

#### contentEquals

    public static boolean contentEquals(InputStream input1,
                                        InputStream input2)
                                 throws IOException

Compare the contents of two Streams to determine if they are equal or not.

Parameters:
  `input1` - the first stream
  `input2` - the second stream
Returns:
  true if the content of the streams are equal or they both don't exist, false otherwise
Throws:
  `IOException`

#### close

    public static void close(InputStream inputStream)

Closes the input stream. The input stream can be null and any IOException's will be swallowed.

Parameters:
  `inputStream` - The stream to close.

#### close

    public static void close(Channel channel)

Closes a channel. Channel can be null and any IOException's will be swallowed.

Parameters:
  `channel` - The stream to close.

#### close

    public static void close(OutputStream outputStream)

Closes the output stream. The output stream can be null and any IOException's will be swallowed.

Parameters:
  `outputStream` - The stream to close.

#### close

    public static void close(Reader reader)

Closes the reader. The reader can be null and any IOException's will be swallowed.

Parameters:
  `reader` - The reader to close.

#### close

    public static void close(Writer writer)

Closes the writer. The writer can be null and any IOException's will be swallowed.

Parameters:
  `writer` - The writer to close.