org.apache.commons.io: public class: CopyUtils

org.apache.commons.io
public class: CopyUtils [javadoc | source]

java.lang.Object
   org.apache.commons.io.CopyUtils

Deprecated! Use - IOUtils. Will be removed in 2.0. Methods renamed to IOUtils.write() or IOUtils.copy(). Null handling behaviour changed in IOUtils (null data does not throw NullPointerException).

This class provides static utility methods for 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 byte-to-char methods, a copy variant allows the encoding to be selected (otherwise the platform default is used). We would like to encourage you to always specify the encoding because relying on the platform default can lead to unexpected results.

copy methods that let you specify the buffer size because in modern VMs the impact on speed seems to be minimal. We're using a default buffer size of 4 KB.

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 java.io.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).

Behold, intrepid explorers; a map of this class:

Method Input Output Dependency
------ ----- ------ -------
1 copy InputStream OutputStream (primitive)
2 copy Reader Writer (primitive)

3 copy InputStream Writer 2

4 copy Reader OutputStream 2

5 copy String OutputStream 2
6 copy String Writer (trivial)

7 copy byte[] Writer 3
8 copy byte[] OutputStream (trivial)

Note that only the first two methods shuffle bytes; the rest use these two, or (if possible) copy using native Java copy methods. As there are method variants to specify the encoding, each row may correspond to up to 2 methods.

Origin of code: Excalibur.

author: Peter - Donald

author: Jeff - Turner

author: Matthew - Hawthorne

version: $ - Id: CopyUtils.java 437680 2006-08-28 11:57:00Z scolebourne $

Constructor:
public CopyUtils() { } Instances should NOT be constructed in standard programming.

Constructor:

 public CopyUtils() {

}

Instances should NOT be constructed in standard programming.

Method from org.apache.commons.io.CopyUtils Summary:
copy, copy, copy, copy, copy, copy, copy, copy, copy, copy

Methods from java.lang.Object:
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method from org.apache.commons.io.CopyUtils Detail:
public static void copy(byte[] input, OutputStream output) throws IOException { output.write(input); } Deprecated! Copy bytes from a `byte[]` to an `OutputStream`.
public static void copy(byte[] input, Writer output) throws IOException { ByteArrayInputStream in = new ByteArrayInputStream(input); copy(in, output); } Deprecated! 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.
public static int copy(InputStream input, OutputStream output) throws IOException { byte[] buffer = new byte[DEFAULT_BUFFER_SIZE]; int count = 0; int n = 0; while (-1 != (n = input.read(buffer))) { output.write(buffer, 0, n); count += n; } return count; } Deprecated! Copy bytes from an `InputStream` to an `OutputStream`.
public static int copy(Reader input, Writer output) throws IOException { char[] buffer = new char[DEFAULT_BUFFER_SIZE]; int count = 0; int n = 0; while (-1 != (n = input.read(buffer))) { output.write(buffer, 0, n); count += n; } return count; } Deprecated! Copy chars from a `Reader` to a `Writer`.
public static void copy(InputStream input, Writer output) throws IOException { InputStreamReader in = new InputStreamReader(input); copy(in, output); } Deprecated! 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.
public static void copy(Reader input, OutputStream output) throws IOException { OutputStreamWriter out = new OutputStreamWriter(output); copy(input, out); // XXX Unless anyone is planning on rewriting OutputStreamWriter, we // have to flush here. out.flush(); } Deprecated! Serialize chars from a `Reader` to bytes on an `OutputStream`, and flush the `OutputStream`.
public static void copy(String input, OutputStream output) throws IOException { StringReader in = new StringReader(input); OutputStreamWriter out = new OutputStreamWriter(output); copy(in, out); // XXX Unless anyone is planning on rewriting OutputStreamWriter, we // have to flush here. out.flush(); } Deprecated! Serialize chars from a `String` to bytes on an `OutputStream`, and flush the `OutputStream`.
public static void copy(String input, Writer output) throws IOException { output.write(input); } Deprecated! Copy chars from a `String` to a `Writer`.
public static void copy(byte[] input, Writer output, String encoding) throws IOException { ByteArrayInputStream in = new ByteArrayInputStream(input); copy(in, output, encoding); } Deprecated! Copy and convert bytes from a `byte[]` to chars on a `Writer`, using the specified encoding.
public static void copy(InputStream input, Writer output, String encoding) throws IOException { InputStreamReader in = new InputStreamReader(input, encoding); copy(in, output); } Deprecated! Copy and convert bytes from an `InputStream` to chars on a `Writer`, using the specified encoding.

Method from org.apache.commons.io.CopyUtils Detail:

 public static  void copy(byte[] input,
    OutputStream output) throws IOException {
        output.write(input);
}

Deprecated!

byte[]

OutputStream

 public static  void copy(byte[] input,
    Writer output) throws IOException {
        ByteArrayInputStream in = new ByteArrayInputStream(input);
        copy(in, output);
}

Deprecated!

byte[]

Writer

 public static int copy(InputStream input,
    OutputStream output) throws IOException {
        byte[] buffer = new byte[DEFAULT_BUFFER_SIZE];
        int count = 0;
        int n = 0;
        while (-1 != (n = input.read(buffer))) {
            output.write(buffer, 0, n);
            count += n;
        }
        return count;
}

Deprecated!

InputStream

OutputStream

 public static int copy(Reader input,
    Writer output) throws IOException {
        char[] buffer = new char[DEFAULT_BUFFER_SIZE];
        int count = 0;
        int n = 0;
        while (-1 != (n = input.read(buffer))) {
            output.write(buffer, 0, n);
            count += n;
        }
        return count;
}

Deprecated!

Reader

Writer

 public static  void copy(InputStream input,
    Writer output) throws IOException {
        InputStreamReader in = new InputStreamReader(input);
        copy(in, output);
}

Deprecated!

InputStream

Writer

 public static  void copy(Reader input,
    OutputStream output) throws IOException {
        OutputStreamWriter out = new OutputStreamWriter(output);
        copy(input, out);
        // XXX Unless anyone is planning on rewriting OutputStreamWriter, we
        // have to flush here.
        out.flush();
}

Deprecated!

Reader

OutputStream

 public static  void copy(String input,
    OutputStream output) throws IOException {
        StringReader in = new StringReader(input);
        OutputStreamWriter out = new OutputStreamWriter(output);
        copy(in, out);
        // XXX Unless anyone is planning on rewriting OutputStreamWriter, we
        // have to flush here.
        out.flush();
}

Deprecated!

String

OutputStream

 public static  void copy(String input,
    Writer output) throws IOException {
        output.write(input);
}

Deprecated!

String

Writer

 public static  void copy(byte[] input,
    Writer output,
    String encoding) throws IOException {
        ByteArrayInputStream in = new ByteArrayInputStream(input);
        copy(in, output, encoding);
}

Deprecated!

byte[]

Writer

 public static  void copy(InputStream input,
    Writer output,
    String encoding) throws IOException {
        InputStreamReader in = new InputStreamReader(input, encoding);
        copy(in, output);
}

Deprecated!

InputStream

Writer