View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.fileupload.util;
18  
19  import java.io.ByteArrayOutputStream;
20  import java.io.IOException;
21  import java.io.InputStream;
22  import java.io.OutputStream;
23  
24  
25  /** Utility class for working with streams.
26   */
27  public final class Streams {
28      /**
29       * Private constructor, to prevent instantiation.
30       * This class has only static methods.
31       */
32      private Streams() {
33          // Does nothing
34      }
35  
36      /**
37       * Default buffer size for use in
38       * {@link #copy(InputStream, OutputStream, boolean)}.
39       */
40      private static final int DEFAULT_BUFFER_SIZE = 8192;
41  
42      /**
43       * Copies the contents of the given {@link InputStream}
44       * to the given {@link OutputStream}. Shortcut for
45       * <pre>
46       *   copy(pInputStream, pOutputStream, new byte[8192]);
47       * </pre>
48       * @param pInputStream The input stream, which is being read.
49       * It is guaranteed, that {@link InputStream#close()} is called
50       * on the stream.
51       * @param pOutputStream The output stream, to which data should
52       * be written. May be null, in which case the input streams
53       * contents are simply discarded.
54       * @param pClose True guarantees, that {@link OutputStream#close()}
55       * is called on the stream. False indicates, that only
56       * {@link OutputStream#flush()} should be called finally.
57       *
58       * @return Number of bytes, which have been copied.
59       * @throws IOException An I/O error occurred.
60       */
61      public static long copy(InputStream pInputStream,
62              OutputStream pOutputStream, boolean pClose)
63              throws IOException {
64          return copy(pInputStream, pOutputStream, pClose,
65                  new byte[DEFAULT_BUFFER_SIZE]);
66      }
67  
68      /**
69       * Copies the contents of the given {@link InputStream}
70       * to the given {@link OutputStream}.
71       * @param pIn The input stream, which is being read.
72       *   It is guaranteed, that {@link InputStream#close()} is called
73       *   on the stream.
74       * @param pOut The output stream, to which data should
75       *   be written. May be null, in which case the input streams
76       *   contents are simply discarded.
77       * @param pClose True guarantees, that {@link OutputStream#close()}
78       *   is called on the stream. False indicates, that only
79       *   {@link OutputStream#flush()} should be called finally.
80       * @param pBuffer Temporary buffer, which is to be used for
81       *   copying data.
82       * @return Number of bytes, which have been copied.
83       * @throws IOException An I/O error occurred.
84       */
85      public static long copy(InputStream pIn,
86              OutputStream pOut, boolean pClose,
87              byte[] pBuffer)
88      throws IOException {
89          OutputStream out = pOut;
90          InputStream in = pIn;
91          try {
92              long total = 0;
93              for (;;) {
94                  int res = in.read(pBuffer);
95                  if (res == -1) {
96                      break;
97                  }
98                  if (res > 0) {
99                      total += res;
100                     if (out != null) {
101                         out.write(pBuffer, 0, res);
102                     }
103                 }
104             }
105             if (out != null) {
106                 if (pClose) {
107                     out.close();
108                 } else {
109                     out.flush();
110                 }
111                 out = null;
112             }
113             in.close();
114             in = null;
115             return total;
116         } finally {
117             if (in != null) {
118                 try {
119                     in.close();
120                 } catch (Throwable t) {
121                     /* Ignore me */
122                 }
123             }
124             if (pClose  &&  out != null) {
125                 try {
126                     out.close();
127                 } catch (Throwable t) {
128                     /* Ignore me */
129                 }
130             }
131         }
132     }
133 
134     /**
135      * This convenience method allows to read a
136      * {@link org.apache.commons.fileupload.FileItemStream}'s
137      * content into a string. The platform's default character encoding
138      * is used for converting bytes into characters.
139      * @param pStream The input stream to read.
140      * @see #asString(InputStream, String)
141      * @return The streams contents, as a string.
142      * @throws IOException An I/O error occurred.
143      */
144     public static String asString(InputStream pStream) throws IOException {
145         ByteArrayOutputStream baos = new ByteArrayOutputStream();
146         copy(pStream, baos, true);
147         return baos.toString();
148     }
149 
150     /**
151      * This convenience method allows to read a
152      * {@link org.apache.commons.fileupload.FileItemStream}'s
153      * content into a string, using the given character encoding.
154      * @param pStream The input stream to read.
155      * @param pEncoding The character encoding, typically "UTF-8".
156      * @see #asString(InputStream)
157      * @return The streams contents, as a string.
158      * @throws IOException An I/O error occurred.
159      */
160     public static String asString(InputStream pStream, String pEncoding)
161             throws IOException {
162         ByteArrayOutputStream baos = new ByteArrayOutputStream();
163         copy(pStream, baos, true);
164         return baos.toString(pEncoding);
165     }
166 }