Javadoc

Author: garydgregory

src/main/java/org/apache/commons/io/IOUtils.java

@@ -370,7 +370,7 @@ public static byte[] byteArray() {
     /**
      * Returns a new byte array of the given size.
      *
-     * TODO Consider guarding or warning against large allocations...
+     * TODO Consider guarding or warning against large allocations.
      *
      * @param size array size.
      * @return a new byte array of the given size.
@@ -1866,9 +1866,11 @@ public static LineIterator lineIterator(final Reader reader) {
 
     /**
      * Reads bytes from an input stream.
+     * <p>
      * This implementation guarantees that it will read as many bytes
      * as possible before giving up; this may not always be the case for
      * subclasses of {@link InputStream}.
+     * </p>
      *
      * @param input where to read input from.
      * @param buffer destination.
@@ -1882,9 +1884,11 @@ public static int read(final InputStream input, final byte[] buffer) throws IOEx
 
     /**
      * Reads bytes from an input stream.
+     * <p>
      * This implementation guarantees that it will read as many bytes
      * as possible before giving up; this may not always be the case for
      * subclasses of {@link InputStream}.
+     * </p>
      *
      * @param input where to read input.
      * @param buffer destination.
@@ -1960,9 +1964,11 @@ public static int read(final ReadableByteChannel input, final ByteBuffer buffer)
 
     /**
      * Reads characters from an input character stream.
+     * <p>
      * This implementation guarantees that it will read as many characters
      * as possible before giving up; this may not always be the case for
      * subclasses of {@link Reader}.
+     * </p>
      *
      * @param reader where to read input from.
      * @param buffer destination.
@@ -1976,9 +1982,11 @@ public static int read(final Reader reader, final char[] buffer) throws IOExcept
 
     /**
      * Reads characters from an input character stream.
+     * <p>
      * This implementation guarantees that it will read as many characters
      * as possible before giving up; this may not always be the case for
      * subclasses of {@link Reader}.
+     * </p>
      *
      * @param reader where to read input from.
      * @param buffer destination.
@@ -2336,18 +2344,18 @@ public static URL resourceToURL(final String name, final ClassLoader classLoader
 
     /**
      * Skips bytes from an input byte stream.
-     * This implementation guarantees that it will read as many bytes
-     * as possible before giving up; this may not always be the case for
-     * skip() implementations in subclasses of {@link InputStream}.
      * <p>
-     * Note that the implementation uses {@link InputStream#read(byte[], int, int)} rather
-     * than delegating to {@link InputStream#skip(long)}.
-     * This means that the method may be considerably less efficient than using the actual skip implementation,
-     * this is done to guarantee that the correct number of bytes are skipped.
+     * This implementation guarantees that it will read as many bytes as possible before giving up; this may not always be the case for skip() implementations
+     * in subclasses of {@link InputStream}.
+     * </p>
+     * <p>
+     * Note that the implementation uses {@link InputStream#read(byte[], int, int)} rather than delegating to {@link InputStream#skip(long)}. This means that
+     * the method may be considerably less efficient than using the actual skip implementation, this is done to guarantee that the correct number of bytes are
+     * skipped.
      * </p>
      *
      * @param input byte stream to skip.
-     * @param skip number of bytes to skip.
+     * @param skip  number of bytes to skip.
      * @return number of bytes actually skipped.
      * @throws IOException              if there is a problem reading the file.
      * @throws IllegalArgumentException if toSkip is negative.
@@ -2583,22 +2591,18 @@ public static void skipFully(final Reader reader, final long toSkip) throws IOEx
     }
 
     /**
-     * Fetches entire contents of an {@link InputStream} and represent
-     * same data as result InputStream.
+     * Fetches entire contents of an {@link InputStream} and represent same data as result InputStream.
      * <p>
      * This method is useful where,
      * </p>
      * <ul>
      * <li>Source InputStream is slow.</li>
-     * <li>It has network resources associated, so we cannot keep it open for
-     * long time.</li>
+     * <li>It has network resources associated, so we cannot keep it open for long time.</li>
      * <li>It has network timeout associated.</li>
      * </ul>
      * <p>
-     * It can be used in favor of {@link #toByteArray(InputStream)}, since it
-     * avoids unnecessary allocation and copy of byte[].<br>
-     * This method buffers the input internally, so there is no need to use a
-     * {@link BufferedInputStream}.
+     * It can be used in favor of {@link #toByteArray(InputStream)}, since it avoids unnecessary allocation and copy of byte[].<br>
+     * This method buffers the input internally, so there is no need to use a {@link BufferedInputStream}.
      * </p>
      *
      * @param input Stream to be fully buffered.
@@ -2611,26 +2615,22 @@ public static InputStream toBufferedInputStream(final InputStream input) throws
     }
 
     /**
-     * Fetches entire contents of an {@link InputStream} and represent
-     * same data as result InputStream.
+     * Fetches entire contents of an {@link InputStream} and represent same data as result InputStream.
      * <p>
      * This method is useful where,
      * </p>
      * <ul>
      * <li>Source InputStream is slow.</li>
-     * <li>It has network resources associated, so we cannot keep it open for
-     * long time.</li>
+     * <li>It has network resources associated, so we cannot keep it open for long time.</li>
      * <li>It has network timeout associated.</li>
      * </ul>
      * <p>
-     * It can be used in favor of {@link #toByteArray(InputStream)}, since it
-     * avoids unnecessary allocation and copy of byte[].<br>
-     * This method buffers the input internally, so there is no need to use a
-     * {@link BufferedInputStream}.
+     * It can be used in favor of {@link #toByteArray(InputStream)}, since it avoids unnecessary allocation and copy of byte[].<br>
+     * This method buffers the input internally, so there is no need to use a {@link BufferedInputStream}.
      * </p>
      *
      * @param input Stream to be fully buffered.
-     * @param size the initial buffer size
+     * @param size  the initial buffer size.
      * @return A fully buffered stream.
      * @throws IOException if an I/O error occurs.
      * @since 2.5
@@ -2643,9 +2643,9 @@ public static InputStream toBufferedInputStream(final InputStream input, final i
      * Returns the given reader if it is a {@link BufferedReader}, otherwise creates a BufferedReader from the given
      * reader.
      *
-     * @param reader the reader to wrap or return (not null)
-     * @return the given reader or a new {@link BufferedReader} for the given reader
-     * @throws NullPointerException if the input parameter is null
+     * @param reader the reader to wrap or return (not null).
+     * @return the given reader or a new {@link BufferedReader} for the given reader.
+     * @throws NullPointerException if the input parameter is null.
      * @see #buffer(Reader)
      * @since 2.2
      */
@@ -2657,10 +2657,10 @@ public static BufferedReader toBufferedReader(final Reader reader) {
      * Returns the given reader if it is a {@link BufferedReader}, otherwise creates a BufferedReader from the given
      * reader.
      *
-     * @param reader the reader to wrap or return (not null)
+     * @param reader the reader to wrap or return (not null).
      * @param size the buffer size, if a new BufferedReader is created.
-     * @return the given reader or a new {@link BufferedReader} for the given reader
-     * @throws NullPointerException if the input parameter is null
+     * @return the given reader or a new {@link BufferedReader} for the given reader.
+     * @throws NullPointerException if the input parameter is null.
      * @see #buffer(Reader)
      * @since 2.5
      */