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