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 = 0; 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 = 0; 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}