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    
018    package org.apache.commons.net.io;
019    
020    import java.io.IOException;
021    import java.io.InputStream;
022    import java.io.OutputStream;
023    import java.io.Reader;
024    import java.io.Writer;
025    
026    /***
027     * The Util class cannot be instantiated and stores short static convenience
028     * methods that are often quite useful.
029     * <p>
030     * <p>
031     * @see CopyStreamException
032     * @see CopyStreamListener
033     * @see CopyStreamAdapter
034     * @author Daniel F. Savarese
035     ***/
036    
037    public final class Util
038    {
039        /***
040         * The default buffer size used by {@link #copyStream  copyStream }
041         * and {@link #copyReader  copyReader }. It's value is 1024.
042         ***/
043        public static final int DEFAULT_COPY_BUFFER_SIZE = 1024;
044    
045        // Cannot be instantiated
046        private Util()
047        { }
048    
049    
050        /***
051         * Copies the contents of an InputStream to an OutputStream using a
052         * copy buffer of a given size and notifies the provided
053         * CopyStreamListener of the progress of the copy operation by calling
054         * its bytesTransferred(long, int) method after each write to the
055         * destination.  If you wish to notify more than one listener you should
056         * use a CopyStreamAdapter as the listener and register the additional
057         * listeners with the CopyStreamAdapter.
058         * <p>
059         * The contents of the InputStream are
060         * read until the end of the stream is reached, but neither the
061         * source nor the destination are closed.  You must do this yourself
062         * outside of the method call.  The number of bytes read/written is
063         * returned.
064         * <p>
065         * @param source  The source InputStream.
066         * @param dest    The destination OutputStream.
067         * @param bufferSize  The number of bytes to buffer during the copy.
068         * @param streamSize  The number of bytes in the stream being copied.
069         *          Should be set to CopyStreamEvent.UNKNOWN_STREAM_SIZE if unknown.
070         * @param listener  The CopyStreamListener to notify of progress.  If
071         *      this parameter is null, notification is not attempted.
072         * @param flush Whether to flush the output stream after every
073         *        write.  This is necessary for interactive sessions that rely on
074         *        buffered streams.  If you don't flush, the data will stay in
075         *        the stream buffer.
076         * @exception CopyStreamException  If an error occurs while reading from the
077         *            source or writing to the destination.  The CopyStreamException
078         *            will contain the number of bytes confirmed to have been
079         *            transferred before an
080         *            IOException occurred, and it will also contain the IOException
081         *            that caused the error.  These values can be retrieved with
082         *            the CopyStreamException getTotalBytesTransferred() and
083         *            getIOException() methods.
084         ***/
085        public static final long copyStream(InputStream source, OutputStream dest,
086                                            int bufferSize, long streamSize,
087                                            CopyStreamListener listener,
088                                            boolean flush)
089        throws CopyStreamException
090        {
091            int bytes;
092            long total;
093            byte[] buffer;
094    
095            buffer = new byte[bufferSize];
096            total = 0;
097    
098            try
099            {
100                while ((bytes = source.read(buffer)) != -1)
101                {
102                    // Technically, some read(byte[]) methods may return 0 and we cannot
103                    // accept that as an indication of EOF.
104    
105                    if (bytes == 0)
106                    {
107                        bytes = source.read();
108                        if (bytes < 0)
109                            break;
110                        dest.write(bytes);
111                        if(flush)
112                          dest.flush();
113                        ++total;
114                        if (listener != null)
115                            listener.bytesTransferred(total, 1, streamSize);
116                        continue;
117                    }
118    
119                    dest.write(buffer, 0, bytes);
120                    if(flush)
121                      dest.flush();
122                    total += bytes;
123                    if (listener != null)
124                        listener.bytesTransferred(total, bytes, streamSize);
125                }
126            }
127            catch (IOException e)
128            {
129                throw new CopyStreamException("IOException caught while copying.",
130                                              total, e);
131            }
132    
133            return total;
134        }
135    
136    
137        /***
138         * Copies the contents of an InputStream to an OutputStream using a
139         * copy buffer of a given size and notifies the provided
140         * CopyStreamListener of the progress of the copy operation by calling
141         * its bytesTransferred(long, int) method after each write to the
142         * destination.  If you wish to notify more than one listener you should
143         * use a CopyStreamAdapter as the listener and register the additional
144         * listeners with the CopyStreamAdapter.
145         * <p>
146         * The contents of the InputStream are
147         * read until the end of the stream is reached, but neither the
148         * source nor the destination are closed.  You must do this yourself
149         * outside of the method call.  The number of bytes read/written is
150         * returned.
151         * <p>
152         * @param source  The source InputStream.
153         * @param dest    The destination OutputStream.
154         * @param bufferSize  The number of bytes to buffer during the copy.
155         * @param streamSize  The number of bytes in the stream being copied.
156         *          Should be set to CopyStreamEvent.UNKNOWN_STREAM_SIZE if unknown.
157         * @param listener  The CopyStreamListener to notify of progress.  If
158         *      this parameter is null, notification is not attempted.
159         * @exception CopyStreamException  If an error occurs while reading from the
160         *            source or writing to the destination.  The CopyStreamException
161         *            will contain the number of bytes confirmed to have been
162         *            transferred before an
163         *            IOException occurred, and it will also contain the IOException
164         *            that caused the error.  These values can be retrieved with
165         *            the CopyStreamException getTotalBytesTransferred() and
166         *            getIOException() methods.
167         ***/
168        public static final long copyStream(InputStream source, OutputStream dest,
169                                            int bufferSize, long streamSize,
170                                            CopyStreamListener listener)
171        throws CopyStreamException
172        {
173          return copyStream(source, dest, bufferSize, streamSize, listener,
174                            true);
175        }
176    
177    
178        /***
179         * Copies the contents of an InputStream to an OutputStream using a
180         * copy buffer of a given size.  The contents of the InputStream are
181         * read until the end of the stream is reached, but neither the
182         * source nor the destination are closed.  You must do this yourself
183         * outside of the method call.  The number of bytes read/written is
184         * returned.
185         * <p>
186         * @param source  The source InputStream.
187         * @param dest    The destination OutputStream.
188         * @return  The number of bytes read/written in the copy operation.
189         * @exception CopyStreamException  If an error occurs while reading from the
190         *            source or writing to the destination.  The CopyStreamException
191         *            will contain the number of bytes confirmed to have been
192         *            transferred before an
193         *            IOException occurred, and it will also contain the IOException
194         *            that caused the error.  These values can be retrieved with
195         *            the CopyStreamException getTotalBytesTransferred() and
196         *            getIOException() methods.
197         ***/
198        public static final long copyStream(InputStream source, OutputStream dest,
199                                            int bufferSize)
200        throws CopyStreamException
201        {
202            return copyStream(source, dest, bufferSize,
203                              CopyStreamEvent.UNKNOWN_STREAM_SIZE, null);
204        }
205    
206    
207        /***
208         * Same as <code> copyStream(source, dest, DEFAULT_COPY_BUFFER_SIZE); </code>
209         ***/
210        public static final long copyStream(InputStream source, OutputStream dest)
211        throws CopyStreamException
212        {
213            return copyStream(source, dest, DEFAULT_COPY_BUFFER_SIZE);
214        }
215    
216    
217        /***
218         * Copies the contents of a Reader to a Writer using a
219         * copy buffer of a given size and notifies the provided
220         * CopyStreamListener of the progress of the copy operation by calling
221         * its bytesTransferred(long, int) method after each write to the
222         * destination.  If you wish to notify more than one listener you should
223         * use a CopyStreamAdapter as the listener and register the additional
224         * listeners with the CopyStreamAdapter.
225         * <p>
226         * The contents of the Reader are
227         * read until its end is reached, but neither the source nor the
228         * destination are closed.  You must do this yourself outside of the
229         * method call.  The number of characters read/written is returned.
230         * <p>
231         * @param source  The source Reader.
232         * @param dest    The destination writer.
233         * @param bufferSize  The number of characters to buffer during the copy.
234         * @param streamSize  The number of characters in the stream being copied.
235         *          Should be set to CopyStreamEvent.UNKNOWN_STREAM_SIZE if unknown.
236         * @param listener  The CopyStreamListener to notify of progress.  If
237         *      this parameter is null, notification is not attempted.
238         * @return  The number of characters read/written in the copy operation.
239         * @exception CopyStreamException  If an error occurs while reading from the
240         *            source or writing to the destination.  The CopyStreamException
241         *            will contain the number of bytes confirmed to have been
242         *            transferred before an
243         *            IOException occurred, and it will also contain the IOException
244         *            that caused the error.  These values can be retrieved with
245         *            the CopyStreamException getTotalBytesTransferred() and
246         *            getIOException() methods.
247         ***/
248        public static final long copyReader(Reader source, Writer dest,
249                                            int bufferSize, long streamSize,
250                                            CopyStreamListener listener)
251        throws CopyStreamException
252        {
253            int chars;
254            long total;
255            char[] buffer;
256    
257            buffer = new char[bufferSize];
258            total = 0;
259    
260            try
261            {
262                while ((chars = source.read(buffer)) != -1)
263                {
264                    // Technically, some read(char[]) methods may return 0 and we cannot
265                    // accept that as an indication of EOF.
266                    if (chars == 0)
267                    {
268                        chars = source.read();
269                        if (chars < 0)
270                            break;
271                        dest.write(chars);
272                        dest.flush();
273                        ++total;
274                        if (listener != null)
275                            listener.bytesTransferred(total, chars, streamSize);
276                        continue;
277                    }
278    
279                    dest.write(buffer, 0, chars);
280                    dest.flush();
281                    total += chars;
282                    if (listener != null)
283                        listener.bytesTransferred(total, chars, streamSize);
284                }
285            }
286            catch (IOException e)
287            {
288                throw new CopyStreamException("IOException caught while copying.",
289                                              total, e);
290            }
291    
292            return total;
293        }
294    
295    
296        /***
297         * Copies the contents of a Reader to a Writer using a
298         * copy buffer of a given size.  The contents of the Reader are
299         * read until its end is reached, but neither the source nor the
300         * destination are closed.  You must do this yourself outside of the
301         * method call.  The number of characters read/written is returned.
302         * <p>
303         * @param source  The source Reader.
304         * @param dest    The destination writer.
305         * @param bufferSize  The number of characters to buffer during the copy.
306         * @return  The number of characters read/written in the copy operation.
307         * @exception CopyStreamException  If an error occurs while reading from the
308         *            source or writing to the destination.  The CopyStreamException
309         *            will contain the number of bytes confirmed to have been
310         *            transferred before an
311         *            IOException occurred, and it will also contain the IOException
312         *            that caused the error.  These values can be retrieved with
313         *            the CopyStreamException getTotalBytesTransferred() and
314         *            getIOException() methods.
315         ***/
316        public static final long copyReader(Reader source, Writer dest,
317                                            int bufferSize)
318        throws CopyStreamException
319        {
320            return copyReader(source, dest, bufferSize,
321                              CopyStreamEvent.UNKNOWN_STREAM_SIZE, null);
322        }
323    
324    
325        /***
326         * Same as <code> copyReader(source, dest, DEFAULT_COPY_BUFFER_SIZE); </code>
327         ***/
328        public static final long copyReader(Reader source, Writer dest)
329        throws CopyStreamException
330        {
331            return copyReader(source, dest, DEFAULT_COPY_BUFFER_SIZE);
332        }
333    
334    }