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