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