001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.io;
018
019import static org.apache.commons.io.IOUtils.EOF;
020
021import java.io.ByteArrayInputStream;
022import java.io.IOException;
023import java.io.InputStream;
024import java.io.InputStreamReader;
025import java.io.OutputStream;
026import java.io.OutputStreamWriter;
027import java.io.Reader;
028import java.io.StringReader;
029import java.io.Writer;
030import java.nio.charset.Charset;
031
032/**
033 * This class provides static utility methods for buffered
034 * copying between sources ({@code InputStream}, {@code Reader},
035 * {@code String} and {@code byte[]}) and destinations
036 * ({@code OutputStream}, {@code Writer}, {@code String} and
037 * {@code byte[]}).
038 * <p>
039 * Unless otherwise noted, these {@code copy} methods do <em>not</em>
040 * flush or close the streams. Often doing so would require making non-portable
041 * assumptions about the streams' origin and further use. This means that both
042 * streams' {@code close()} methods must be called after copying. if one
043 * omits this step, then the stream resources (sockets, file descriptors) are
044 * released when the associated Stream is garbage-collected. It is not a good
045 * idea to rely on this mechanism. For a good overview of the distinction
046 * between "memory management" and "resource management", see
047 * <a href="http://www.unixreview.com/articles/1998/9804/9804ja/ja.htm">this
048 * UnixReview article</a>.
049 * <p>
050 * For byte-to-char methods, a {@code copy} variant allows the encoding
051 * to be selected (otherwise the platform default is used). We would like to
052 * encourage you to always specify the encoding because relying on the platform
053 * default can lead to unexpected results.
054 * <p>
055 * We don't provide special variants for the {@code copy} methods that
056 * let you specify the buffer size because in modern VMs the impact on speed
057 * seems to be minimal. We're using a default buffer size of 4 KB.
058 * <p>
059 * The {@code copy} methods use an internal buffer when copying. It is
060 * therefore advisable <em>not</em> to deliberately wrap the stream arguments
061 * to the {@code copy} methods in {@code Buffered*} streams. For
062 * example, don't do the following:
063 * <pre>
064 *  copy( new BufferedInputStream( in ), new BufferedOutputStream( out ) );
065 *  </pre>
066 * The rationale is as follows:
067 * <p>
068 * Imagine that an InputStream's read() is a very expensive operation, which
069 * would usually suggest wrapping in a BufferedInputStream. The
070 * BufferedInputStream works by issuing infrequent
071 * {@link java.io.InputStream#read(byte[] b, int off, int len)} requests on the
072 * underlying InputStream, to fill an internal buffer, from which further
073 * {@code read} requests can inexpensively get their data (until the buffer
074 * runs out).
075 * <p>
076 * However, the {@code copy} methods do the same thing, keeping an
077 * internal buffer, populated by
078 * {@link InputStream#read(byte[] b, int off, int len)} requests. Having two
079 * buffers (or three if the destination stream is also buffered) is pointless,
080 * and the unnecessary buffer management hurts performance slightly (about 3%,
081 * according to some simple experiments).
082 * <p>
083 * Behold, intrepid explorers; a map of this class:
084 * <pre>
085 *       Method      Input               Output          Dependency
086 *       ------      -----               ------          -------
087 * 1     copy        InputStream         OutputStream    (primitive)
088 * 2     copy        Reader              Writer          (primitive)
089 *
090 * 3     copy        InputStream         Writer          2
091 *
092 * 4     copy        Reader              OutputStream    2
093 *
094 * 5     copy        String              OutputStream    2
095 * 6     copy        String              Writer          (trivial)
096 *
097 * 7     copy        byte[]              Writer          3
098 * 8     copy        byte[]              OutputStream    (trivial)
099 * </pre>
100 * <p>
101 * Note that only the first two methods shuffle bytes; the rest use these
102 * two, or (if possible) copy using native Java copy methods. As there are
103 * method variants to specify the encoding, each row may
104 * correspond to up to 2 methods.
105 * <p>
106 * Origin of code: Excalibur.
107 *
108 * @deprecated Use IOUtils. Will be removed in 3.0.
109 *  Methods renamed to IOUtils.write() or IOUtils.copy().
110 *  Null handling behavior changed in IOUtils (null data does not
111 *  throw NullPointerException).
112 */
113@Deprecated
114public class CopyUtils {
115
116    /**
117     * Instances should NOT be constructed in standard programming.
118     */
119    public CopyUtils() { }
120
121    /**
122     * Copies bytes from a {@code byte[]} to an {@code OutputStream}.
123     * @param input the byte array to read from
124     * @param output the {@code OutputStream} to write to
125     * @throws IOException In case of an I/O problem
126     */
127    public static void copy(final byte[] input, final OutputStream output) throws IOException {
128        output.write(input);
129    }
130
131    /**
132     * Copies and convert bytes from a {@code byte[]} to chars on a
133     * {@code Writer}.
134     * The platform's default encoding is used for the byte-to-char conversion.
135     * @param input the byte array to read from
136     * @param output the {@code Writer} to write to
137     * @throws IOException In case of an I/O problem
138     * @deprecated 2.5 use {@link #copy(byte[], Writer, String)} instead
139     */
140    @Deprecated
141    public static void copy(final byte[] input, final Writer output) throws IOException {
142        final ByteArrayInputStream inputStream = new ByteArrayInputStream(input);
143        copy(inputStream, output);
144    }
145
146    /**
147     * Copies and convert bytes from a {@code byte[]} to chars on a
148     * {@code Writer}, using the specified encoding.
149     * @param input the byte array to read from
150     * @param output the {@code Writer} to write to
151     * @param encoding The name of a supported character encoding. See the
152     * <a href="http://www.iana.org/assignments/character-sets">IANA
153     * Charset Registry</a> for a list of valid encoding types.
154     * @throws IOException In case of an I/O problem
155     */
156    public static void copy(final byte[] input, final Writer output, final String encoding) throws IOException {
157        final ByteArrayInputStream inputStream = new ByteArrayInputStream(input);
158        copy(inputStream, output, encoding);
159    }
160
161    /**
162     * Copies bytes from an {@code InputStream} to an
163     * {@code OutputStream}.
164     * @param input the {@code InputStream} to read from
165     * @param output the {@code OutputStream} to write to
166     * @return the number of bytes copied
167     * @throws IOException In case of an I/O problem
168     */
169    public static int copy(final InputStream input, final OutputStream output) throws IOException {
170        final byte[] buffer = IOUtils.byteArray();
171        int count = 0;
172        int n;
173        while (EOF != (n = input.read(buffer))) {
174            output.write(buffer, 0, n);
175            count += n;
176        }
177        return count;
178    }
179
180    // ----------------------------------------------------------------
181    // Reader -> Writer
182    // ----------------------------------------------------------------
183
184    /**
185     * Copies chars from a {@code Reader} to a {@code Writer}.
186     * @param input the {@code Reader} to read from
187     * @param output the {@code Writer} to write to
188     * @return the number of characters copied
189     * @throws IOException In case of an I/O problem
190     */
191    public static int copy(
192            final Reader input,
193            final Writer output)
194                throws IOException {
195        final char[] buffer = IOUtils.getCharArray();
196        int count = 0;
197        int n;
198        while (EOF != (n = input.read(buffer))) {
199            output.write(buffer, 0, n);
200            count += n;
201        }
202        return count;
203    }
204
205    // ----------------------------------------------------------------
206    // InputStream -> Writer
207    // ----------------------------------------------------------------
208
209    /**
210     * Copies and convert bytes from an {@code InputStream} to chars on a
211     * {@code Writer}.
212     * The platform's default encoding is used for the byte-to-char conversion.
213     * @param input the {@code InputStream} to read from
214     * @param output the {@code Writer} to write to
215     * @throws IOException In case of an I/O problem
216     * @deprecated 2.5 use {@link #copy(InputStream, Writer, String)} instead
217     */
218    @Deprecated
219    public static void copy(
220            final InputStream input,
221            final Writer output)
222                throws IOException {
223        // make explicit the dependency on the default encoding
224        final InputStreamReader in = new InputStreamReader(input, Charset.defaultCharset());
225        copy(in, output);
226    }
227
228    /**
229     * Copies and convert bytes from an {@code InputStream} to chars on a
230     * {@code Writer}, using the specified encoding.
231     * @param input the {@code InputStream} to read from
232     * @param output the {@code Writer} to write to
233     * @param encoding The name of a supported character encoding. See the
234     * <a href="http://www.iana.org/assignments/character-sets">IANA
235     * Charset Registry</a> for a list of valid encoding types.
236     * @throws IOException In case of an I/O problem
237     */
238    public static void copy(
239            final InputStream input,
240            final Writer output,
241            final String encoding)
242                throws IOException {
243        final InputStreamReader in = new InputStreamReader(input, encoding);
244        copy(in, output);
245    }
246
247
248    // ----------------------------------------------------------------
249    // Reader -> OutputStream
250    // ----------------------------------------------------------------
251
252    /**
253     * Serialize chars from a {@code Reader} to bytes on an
254     * {@code OutputStream}, and flush the {@code OutputStream}.
255     * Uses the default platform encoding.
256     * @param input the {@code Reader} to read from
257     * @param output the {@code OutputStream} to write to
258     * @throws IOException In case of an I/O problem
259     * @deprecated 2.5 use {@link #copy(Reader, OutputStream, String)} instead
260     */
261    @Deprecated
262    public static void copy(
263            final Reader input,
264            final OutputStream output)
265                throws IOException {
266        // make explicit the dependency on the default encoding
267        final OutputStreamWriter out = new OutputStreamWriter(output, Charset.defaultCharset());
268        copy(input, out);
269        // XXX Unless anyone is planning on rewriting OutputStreamWriter, we
270        // have to flush here.
271        out.flush();
272    }
273
274    /**
275     * Serialize chars from a {@code Reader} to bytes on an
276     * {@code OutputStream}, and flush the {@code OutputStream}.
277     * @param input the {@code Reader} to read from
278     * @param output the {@code OutputStream} to write to
279     * @param encoding The name of a supported character encoding. See the
280     * <a href="http://www.iana.org/assignments/character-sets">IANA
281     * Charset Registry</a> for a list of valid encoding types.
282     * @throws IOException In case of an I/O problem
283     * @since 2.5
284     */
285    public static void copy(
286            final Reader input,
287            final OutputStream output,
288            final String encoding)
289                throws IOException {
290        final OutputStreamWriter out = new OutputStreamWriter(output, encoding);
291        copy(input, out);
292        // XXX Unless anyone is planning on rewriting OutputStreamWriter, we
293        // have to flush here.
294        out.flush();
295    }
296
297    // ----------------------------------------------------------------
298    // String -> OutputStream
299    // ----------------------------------------------------------------
300
301    /**
302     * Serialize chars from a {@code String} to bytes on an
303     * {@code OutputStream}, and
304     * flush the {@code OutputStream}.
305     * Uses the platform default encoding.
306     * @param input the {@code String} to read from
307     * @param output the {@code OutputStream} to write to
308     * @throws IOException In case of an I/O problem
309     * @deprecated 2.5 use {@link #copy(String, OutputStream, String)} instead
310     */
311    @Deprecated
312    public static void copy(
313            final String input,
314            final OutputStream output)
315                throws IOException {
316        final StringReader in = new StringReader(input);
317        // make explicit the dependency on the default encoding
318        final OutputStreamWriter out = new OutputStreamWriter(output, Charset.defaultCharset());
319        copy(in, out);
320        // XXX Unless anyone is planning on rewriting OutputStreamWriter, we
321        // have to flush here.
322        out.flush();
323    }
324
325    /**
326     * Serialize chars from a {@code String} to bytes on an
327     * {@code OutputStream}, and
328     * flush the {@code OutputStream}.
329     * @param input the {@code String} to read from
330     * @param output the {@code OutputStream} to write to
331     * @param encoding The name of a supported character encoding. See the
332     * <a href="http://www.iana.org/assignments/character-sets">IANA
333     * Charset Registry</a> for a list of valid encoding types.
334     * @throws IOException In case of an I/O problem
335     * @since 2.5
336     */
337    public static void copy(
338            final String input,
339            final OutputStream output,
340            final String encoding)
341                throws IOException {
342        final StringReader in = new StringReader(input);
343        final OutputStreamWriter out = new OutputStreamWriter(output, encoding);
344        copy(in, out);
345        // XXX Unless anyone is planning on rewriting OutputStreamWriter, we
346        // have to flush here.
347        out.flush();
348    }
349
350    // ----------------------------------------------------------------
351    // String -> Writer
352    // ----------------------------------------------------------------
353
354    /**
355     * Copies chars from a {@code String} to a {@code Writer}.
356     * @param input the {@code String} to read from
357     * @param output the {@code Writer} to write to
358     * @throws IOException In case of an I/O problem
359     */
360    public static void copy(final String input, final Writer output)
361                throws IOException {
362        output.write(input);
363    }
364
365}