    View Javadoc
    1   package org.apache.commons.net.io;
    2
    3   /* ====================================================================
    4    * The Apache Software License, Version 1.1
    5    *
    6    * Copyright (c) 2001 The Apache Software Foundation.  All rights
    7    * reserved.
    8    *
    9    * Redistribution and use in source and binary forms, with or without
    10   * modification, are permitted provided that the following conditions
    11   * are met:
    12   *
    13   * 1. Redistributions of source code must retain the above copyright
    14   *    notice, this list of conditions and the following disclaimer.
    15   *
    16   * 2. Redistributions in binary form must reproduce the above copyright
    17   *    notice, this list of conditions and the following disclaimer in
    18   *    the documentation and/or other materials provided with the
    19   *    distribution.
    20   *
    21   * 3. The end-user documentation included with the redistribution,
    22   *    if any, must include the following acknowledgment:
    23   *       "This product includes software developed by the
    24   *        Apache Software Foundation (http://www.apache.org/)."
    25   *    Alternately, this acknowledgment may appear in the software itself,
    26   *    if and wherever such third-party acknowledgments normally appear.
    27   *
    28   * 4. The names "Apache" and "Apache Software Foundation" and
    29   *    "Apache Commons" must not be used to endorse or promote products
    30   *    derived from this software without prior written permission. For
    31   *    written permission, please contact apache@apache.org.
    32   *
    33   * 5. Products derived from this software may not be called "Apache",
    34   *    nor may "Apache" appear in their name, without
    35   *    prior written permission of the Apache Software Foundation.
    36   *
    37   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
    38   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
    39   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
    40   * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
    41   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
    42   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
    43   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
    44   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
    45   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
    46   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
    47   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
    48   * SUCH DAMAGE.
    49   * ====================================================================
    50   *
    51   * This software consists of voluntary contributions made by many
    52   * individuals on behalf of the Apache Software Foundation.  For more
    53   * information on the Apache Software Foundation, please see
    54   * <http://www.apache.org/>;.
    55   */
    56
    57  import java.io.IOException;
    58  import java.io.InputStream;
    59  import java.io.OutputStream;
    60  import java.io.Reader;
    61  import java.io.Writer;
    62
    63  /****
    64   * The Util class cannot be instantiated and stores short static convenience
    65   * methods that are often quite useful.
    66   * <p>
    67   * <p>
    68   * @see CopyStreamException
    69   * @see CopyStreamListener
    70   * @see CopyStreamAdapter
    71   * @author Daniel F. Savarese
    72   ***/
    73
    74  public final class Util
    75  {
    76      /****
    77       * The default buffer size used by <a href="#copyStream"> copyStream </a>
    78       * and <a href="#copyReader"> copyReader </a>. It's value is 1024.
    79       ***/
    80      public static final int DEFAULT_COPY_BUFFER_SIZE = 1024;
    81
    82      // Cannot be instantiated
    83      private Util()
    84      { }
    85
    86
    87      /****
    88       * Copies the contents of an InputStream to an OutputStream using a
    89       * copy buffer of a given size and notifies the provided
    90       * CopyStreamListener of the progress of the copy operation by calling
    91       * its bytesTransferred(long, int) method after each write to the
    92       * destination.  If you wish to notify more than one listener you should
    93       * use a CopyStreamAdapter as the listener and register the additional
    94       * listeners with the CopyStreamAdapter.
    95       * <p>
    96       * The contents of the InputStream are
    97       * read until the end of the stream is reached, but neither the
    98       * source nor the destination are closed.  You must do this yourself
    99       * outside of the method call.  The number of bytes read/written is
    100      * returned.
    101      * <p>
    102      * @param source  The source InputStream.
    103      * @param dest    The destination OutputStream.
    104      * @param bufferSize  The number of bytes to buffer during the copy.
    105      * @param streamSize  The number of bytes in the stream being copied.
    106      *          Should be set to CopyStreamEvent.UNKNOWN_STREAM_SIZE if unknown.
    107      * @param listener  The CopyStreamListener to notify of progress.  If
    108      *      this parameter is null, notification is not attempted.
    109      * @exception CopyStreamException  If an error occurs while reading from the
    110      *            source or writing to the destination.  The CopyStreamException
    111      *            will contain the number of bytes confirmed to have been
    112      *            transferred before an
    113      *            IOException occurred, and it will also contain the IOException
    114      *            that caused the error.  These values can be retrieved with
    115      *            the CopyStreamException getTotalBytesTransferred() and
    116      *            getIOException() methods.
    117      ***/
    118     public static final long copyStream(InputStream source, OutputStream dest,
    119                                         int bufferSize, long streamSize,
    120                                         CopyStreamListener listener)
    121     throws CopyStreamException
    122     {
    123         int bytes;
    124         long total;
    125         byte[] buffer;
    126
    127         buffer = new byte[bufferSize];
    128         total = 0;
    129
    130         try
    131         {
    132             while ((bytes = source.read(buffer)) != -1)
    133             {
    134                 // Technically, some read(byte[]) methods may return 0 and we cannot
    135                 // accept that as an indication of EOF.
    136
    137                 if (bytes == 0)
    138                 {
    139                     bytes = source.read();
    140                     if (bytes < 0)
    141                         break;
    142                     dest.write(bytes);
    143                     dest.flush();
    144                     ++total;
    145                     if (listener != null)
    146                         listener.bytesTransferred(total, 1, streamSize);
    147                     continue;
    148                 }
    149
    150                 dest.write(buffer, 0, bytes);
    151                 dest.flush();
    152                 total += bytes;
    153                 if (listener != null)
    154                     listener.bytesTransferred(total, bytes, streamSize);
    155             }
    156         }
    157         catch (IOException e)
    158         {
    159             throw new CopyStreamException("IOException caught while copying.",
    160                                           total, e);
    161         }
    162
    163         return total;
    164     }
    165
    166
    167     /****
    168      * Copies the contents of an InputStream to an OutputStream using a
    169      * copy buffer of a given size.  The contents of the InputStream are
    170      * read until the end of the stream is reached, but neither the
    171      * source nor the destination are closed.  You must do this yourself
    172      * outside of the method call.  The number of bytes read/written is
    173      * returned.
    174      * <p>
    175      * @param source  The source InputStream.
    176      * @param dest    The destination OutputStream.
    177      * @return  The number of bytes read/written in the copy operation.
    178      * @exception CopyStreamException  If an error occurs while reading from the
    179      *            source or writing to the destination.  The CopyStreamException
    180      *            will contain the number of bytes confirmed to have been
    181      *            transferred before an
    182      *            IOException occurred, and it will also contain the IOException
    183      *            that caused the error.  These values can be retrieved with
    184      *            the CopyStreamException getTotalBytesTransferred() and
    185      *            getIOException() methods.
    186      ***/
    187     public static final long copyStream(InputStream source, OutputStream dest,
    188                                         int bufferSize)
    189     throws CopyStreamException
    190     {
    191         return copyStream(source, dest, bufferSize,
    192                           CopyStreamEvent.UNKNOWN_STREAM_SIZE, null);
    193     }
    194
    195
    196     /****
    197      * Same as <code> copyStream(source, dest, DEFAULT_COPY_BUFFER_SIZE); </code>
    198      ***/
    199     public static final long copyStream(InputStream source, OutputStream dest)
    200     throws CopyStreamException
    201     {
    202         return copyStream(source, dest, DEFAULT_COPY_BUFFER_SIZE);
    203     }
    204
    205
    206     /****
    207      * Copies the contents of a Reader to a Writer using a
    208      * copy buffer of a given size and notifies the provided
    209      * CopyStreamListener of the progress of the copy operation by calling
    210      * its bytesTransferred(long, int) method after each write to the
    211      * destination.  If you wish to notify more than one listener you should
    212      * use a CopyStreamAdapter as the listener and register the additional
    213      * listeners with the CopyStreamAdapter.
    214      * <p>
    215      * The contents of the Reader are
    216      * read until its end is reached, but neither the source nor the
    217      * destination are closed.  You must do this yourself outside of the
    218      * method call.  The number of characters read/written is returned.
    219      * <p>
    220      * @param source  The source Reader.
    221      * @param dest    The destination writer.
    222      * @param bufferSize  The number of characters to buffer during the copy.
    223      * @param streamSize  The number of characters in the stream being copied.
    224      *          Should be set to CopyStreamEvent.UNKNOWN_STREAM_SIZE if unknown.
    225      * @param listener  The CopyStreamListener to notify of progress.  If
    226      *      this parameter is null, notification is not attempted.
    227      * @return  The number of characters read/written in the copy operation.
    228      * @exception CopyStreamException  If an error occurs while reading from the
    229      *            source or writing to the destination.  The CopyStreamException
    230      *            will contain the number of bytes confirmed to have been
    231      *            transferred before an
    232      *            IOException occurred, and it will also contain the IOException
    233      *            that caused the error.  These values can be retrieved with
    234      *            the CopyStreamException getTotalBytesTransferred() and
    235      *            getIOException() methods.
    236      ***/
    237     public static final long copyReader(Reader source, Writer dest,
    238                                         int bufferSize, long streamSize,
    239                                         CopyStreamListener listener)
    240     throws CopyStreamException
    241     {
    242         int chars;
    243         long total;
    244         char[] buffer;
    245
    246         buffer = new char[bufferSize];
    247         total = 0;
    248
    249         try
    250         {
    251             while ((chars = source.read(buffer)) != -1)
    252             {
    253                 // Technically, some read(char[]) methods may return 0 and we cannot
    254                 // accept that as an indication of EOF.
    255                 if (chars == 0)
    256                 {
    257                     chars = source.read();
    258                     if (chars < 0)
    259                         break;
    260                     dest.write(chars);
    261                     dest.flush();
    262                     ++total;
    263                     if (listener != null)
    264                         listener.bytesTransferred(total, chars, streamSize);
    265                     continue;
    266                 }
    267
    268                 dest.write(buffer, 0, chars);
    269                 dest.flush();
    270                 total += chars;
    271                 if (listener != null)
    272                     listener.bytesTransferred(total, chars, streamSize);
    273             }
    274         }
    275         catch (IOException e)
    276         {
    277             throw new CopyStreamException("IOException caught while copying.",
    278                                           total, e);
    279         }
    280
    281         return total;
    282     }
    283
    284
    285     /****
    286      * Copies the contents of a Reader to a Writer using a
    287      * copy buffer of a given size.  The contents of the Reader are
    288      * read until its end is reached, but neither the source nor the
    289      * destination are closed.  You must do this yourself outside of the
    290      * method call.  The number of characters read/written is returned.
    291      * <p>
    292      * @param source  The source Reader.
    293      * @param dest    The destination writer.
    294      * @param bufferSize  The number of characters to buffer during the copy.
    295      * @return  The number of characters read/written in the copy operation.
    296      * @exception CopyStreamException  If an error occurs while reading from the
    297      *            source or writing to the destination.  The CopyStreamException
    298      *            will contain the number of bytes confirmed to have been
    299      *            transferred before an
    300      *            IOException occurred, and it will also contain the IOException
    301      *            that caused the error.  These values can be retrieved with
    302      *            the CopyStreamException getTotalBytesTransferred() and
    303      *            getIOException() methods.
    304      ***/
    305     public static final long copyReader(Reader source, Writer dest,
    306                                         int bufferSize)
    307     throws CopyStreamException
    308     {
    309         return copyReader(source, dest, bufferSize,
    310                           CopyStreamEvent.UNKNOWN_STREAM_SIZE, null);
    311     }
    312
    313
    314     /****
    315      * Same as <code> copyReader(source, dest, DEFAULT_COPY_BUFFER_SIZE); </code>
    316      ***/
    317     public static final long copyReader(Reader source, Writer dest)
    318     throws CopyStreamException
    319     {
    320         return copyReader(source, dest, DEFAULT_COPY_BUFFER_SIZE);
    321     }
    322
    323 }

This page was automatically generated by Maven