Modified: commons/proper/io/trunk/src/main/java/org/apache/commons/io/IOUtils.java URL: http://svn.apache.org/viewvc/commons/proper/io/trunk/src/main/java/org/apache/commons/io/IOUtils.java?rev=1686747&r1=1686746&r2=1686747&view=diff ============================================================================== --- commons/proper/io/trunk/src/main/java/org/apache/commons/io/IOUtils.java (original) +++ commons/proper/io/trunk/src/main/java/org/apache/commons/io/IOUtils.java Sun Jun 21 18:44:49 2015 @@ -32,7 +32,6 @@ import java.io.OutputStream; import java.io.OutputStreamWriter; import java.io.PrintWriter; import java.io.Reader; -import java.io.UnsupportedEncodingException; import java.io.Writer; import java.net.HttpURLConnection; import java.net.ServerSocket; @@ -44,7 +43,6 @@ import java.nio.ByteBuffer; import java.nio.channels.ReadableByteChannel; import java.nio.channels.Selector; import java.nio.charset.Charset; -import java.nio.charset.UnsupportedCharsetException; import java.util.ArrayList; import java.util.Collection; import java.util.List; @@ -54,7 +52,7 @@ import org.apache.commons.io.output.Stri /** * General IO stream manipulation utilities. - * <p> + * <p/> * This class provides static utility methods for input/output operations. * <ul> * <li>closeQuietly - these methods close a stream ignoring nulls and exceptions @@ -63,19 +61,19 @@ import org.apache.commons.io.output.Stri * <li>copy - these methods copy all the data from one stream to another * <li>contentEquals - these methods compare the content of two streams * </ul> - * <p> + * <p/> * The byte-to-char methods and char-to-byte methods involve a conversion step. * Two methods are provided in each case, one that uses the platform default * encoding and the other which allows you to specify an encoding. You are * encouraged to always specify an encoding because relying on the platform * default can lead to unexpected results, for example when moving from * development to production. - * <p> + * <p/> * All the methods in this class that read a stream are buffered internally. * This means that there is no cause to use a <code>BufferedInputStream</code> * or <code>BufferedReader</code>. The default buffer size of 4K has been shown * to be efficient in tests. - * <p> + * <p/> * The various copy methods all delegate the actual copying to one of the following methods: * <ul> * <li>{@link #copyLarge(InputStream, OutputStream, byte[])}</li> @@ -86,15 +84,15 @@ import org.apache.commons.io.output.Stri * For example, {@link #copy(InputStream, OutputStream)} calls {@link #copyLarge(InputStream, OutputStream)} * which calls {@link #copy(InputStream, OutputStream, int)} which creates the buffer and calls * {@link #copyLarge(InputStream, OutputStream, byte[])}. - * <p> + * <p/> * Applications can re-use buffers by using the underlying methods directly. * This may improve performance for applications that need to do a lot of copying. - * <p> + * <p/> * Wherever possible, the methods in this class do <em>not</em> flush or close * the stream. This is to avoid making non-portable assumptions about the * streams' origin and further use. Thus the caller is still responsible for * closing streams after use. - * <p> + * <p/> * Origin of code: Excalibur. * * @version $Id$ @@ -193,10 +191,10 @@ public class IOUtils { /** * Closes an <code>Reader</code> unconditionally. - * <p> + * <p/> * Equivalent to {@link Reader#close()}, except any exceptions will be ignored. * This is typically used in finally blocks. - * <p> + * <p/> * Example code: * <pre> * char[] data = new char[1024]; @@ -212,18 +210,18 @@ public class IOUtils { * } * </pre> * - * @param input the Reader to close, may be null or already closed + * @param input the Reader to close, may be null or already closed */ public static void closeQuietly(final Reader input) { - closeQuietly((Closeable)input); + closeQuietly((Closeable) input); } /** * Closes an <code>Writer</code> unconditionally. - * <p> + * <p/> * Equivalent to {@link Writer#close()}, except any exceptions will be ignored. * This is typically used in finally blocks. - * <p> + * <p/> * Example code: * <pre> * Writer out = null; @@ -238,18 +236,18 @@ public class IOUtils { * } * </pre> * - * @param output the Writer to close, may be null or already closed + * @param output the Writer to close, may be null or already closed */ public static void closeQuietly(final Writer output) { - closeQuietly((Closeable)output); + closeQuietly((Closeable) output); } /** * Closes an <code>InputStream</code> unconditionally. - * <p> + * <p/> * Equivalent to {@link InputStream#close()}, except any exceptions will be ignored. * This is typically used in finally blocks. - * <p> + * <p/> * Example code: * <pre> * byte[] data = new byte[1024]; @@ -265,18 +263,18 @@ public class IOUtils { * } * </pre> * - * @param input the InputStream to close, may be null or already closed + * @param input the InputStream to close, may be null or already closed */ public static void closeQuietly(final InputStream input) { - closeQuietly((Closeable)input); + closeQuietly((Closeable) input); } /** * Closes an <code>OutputStream</code> unconditionally. - * <p> + * <p/> * Equivalent to {@link OutputStream#close()}, except any exceptions will be ignored. * This is typically used in finally blocks. - * <p> + * <p/> * Example code: * <pre> * byte[] data = "Hello, World".getBytes(); @@ -293,20 +291,20 @@ public class IOUtils { * } * </pre> * - * @param output the OutputStream to close, may be null or already closed + * @param output the OutputStream to close, may be null or already closed */ public static void closeQuietly(final OutputStream output) { - closeQuietly((Closeable)output); + closeQuietly((Closeable) output); } /** * Closes a <code>Closeable</code> unconditionally. - * <p> + * <p/> * Equivalent to {@link Closeable#close()}, except any exceptions will be ignored. This is typically used in * finally blocks. - * <p> + * <p/> * Example code: - * + * <p/> * <pre> * Closeable closeable = null; * try { @@ -319,9 +317,9 @@ public class IOUtils { * IOUtils.closeQuietly(closeable); * } * </pre> - * + * <p/> * Closing all streams: - * + * <p/> * <pre> * try { * return IOUtils.copy(inputStream, outputStream); @@ -331,8 +329,7 @@ public class IOUtils { * } * </pre> * - * @param closeable - * the objects to close, may be null or already closed + * @param closeable the objects to close, may be null or already closed * @since 2.0 */ public static void closeQuietly(final Closeable closeable) { @@ -347,9 +344,9 @@ public class IOUtils { /** * Closes a <code>Closeable</code> unconditionally. - * <p> + * <p/> * Equivalent to {@link Closeable#close()}, except any exceptions will be ignored. - * <p> + * <p/> * This is typically used in finally blocks to ensure that the closeable is closed * even if an Exception was thrown before the normal close statement was reached. * <br> @@ -358,9 +355,9 @@ public class IOUtils { * <br> * It is only intended to simplify tidying up where normal processing has already failed * and reporting close failure as well is not necessary or useful. - * <p> + * <p/> * Example code: - * + * <p/> * <pre> * Closeable closeable = null; * try { @@ -373,7 +370,7 @@ public class IOUtils { * <b>IOUtils.closeQuietly(closeable); // In case normal close was skipped due to Exception</b> * } * </pre> - * + * <p/> * Closing all streams: * <br> * <pre> @@ -384,10 +381,9 @@ public class IOUtils { * } * </pre> * - * @param closeables - * the objects to close, may be null or already closed - * @since 2.5 + * @param closeables the objects to close, may be null or already closed * @see #closeQuietly(Closeable) + * @since 2.5 */ public static void closeQuietly(final Closeable... closeables) { if (closeables == null) { @@ -400,10 +396,10 @@ public class IOUtils { /** * Closes a <code>Socket</code> unconditionally. - * <p> + * <p/> * Equivalent to {@link Socket#close()}, except any exceptions will be ignored. * This is typically used in finally blocks. - * <p> + * <p/> * Example code: * <pre> * Socket socket = null; @@ -421,8 +417,8 @@ public class IOUtils { * @param sock the Socket to close, may be null or already closed * @since 2.0 */ - public static void closeQuietly(final Socket sock){ - if (sock != null){ + public static void closeQuietly(final Socket sock) { + if (sock != null) { try { sock.close(); } catch (final IOException ioe) { @@ -433,10 +429,10 @@ public class IOUtils { /** * Closes a <code>Selector</code> unconditionally. - * <p> + * <p/> * Equivalent to {@link Selector#close()}, except any exceptions will be ignored. * This is typically used in finally blocks. - * <p> + * <p/> * Example code: * <pre> * Selector selector = null; @@ -454,10 +450,10 @@ public class IOUtils { * @param selector the Selector to close, may be null or already closed * @since 2.2 */ - public static void closeQuietly(final Selector selector){ - if (selector != null){ + public static void closeQuietly(final Selector selector) { + if (selector != null) { try { - selector.close(); + selector.close(); } catch (final IOException ioe) { // ignored } @@ -466,10 +462,10 @@ public class IOUtils { /** * Closes a <code>ServerSocket</code> unconditionally. - * <p> + * <p/> * Equivalent to {@link ServerSocket#close()}, except any exceptions will be ignored. * This is typically used in finally blocks. - * <p> + * <p/> * Example code: * <pre> * ServerSocket socket = null; @@ -487,8 +483,8 @@ public class IOUtils { * @param sock the ServerSocket to close, may be null or already closed * @since 2.2 */ - public static void closeQuietly(final ServerSocket sock){ - if (sock != null){ + public static void closeQuietly(final ServerSocket sock) { + if (sock != null) { try { sock.close(); } catch (final IOException ioe) { @@ -500,7 +496,7 @@ public class IOUtils { /** * Fetches entire contents of an <code>InputStream</code> and represent * same data as result InputStream. - * <p> + * <p/> * This method is useful where, * <ul> * <li>Source InputStream is slow.</li> @@ -525,7 +521,7 @@ public class IOUtils { /** * Fetches entire contents of an <code>InputStream</code> and represent * same data as result InputStream. - * <p> + * <p/> * This method is useful where, * <ul> * <li>Source InputStream is slow.</li> @@ -552,12 +548,11 @@ public class IOUtils { * 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) * @return the given reader or a new {@link BufferedReader} for the given reader - * @since 2.2 - * @see #buffer(Reader) * @throws NullPointerException if the input parameter is null + * @see #buffer(Reader) + * @since 2.2 */ public static BufferedReader toBufferedReader(final Reader reader) { return reader instanceof BufferedReader ? (BufferedReader) reader : new BufferedReader(reader); @@ -567,162 +562,158 @@ public class IOUtils { * 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 - * @since 2.5 - * @see #buffer(Reader) * @throws NullPointerException if the input parameter is null + * @see #buffer(Reader) + * @since 2.5 */ public static BufferedReader toBufferedReader(final Reader reader, int size) { return reader instanceof BufferedReader ? (BufferedReader) reader : new BufferedReader(reader, size); } /** - * Returns the given reader if it is already a {@link BufferedReader}, otherwise creates a BufferedReader from the given - * reader. + * Returns the given reader if it is already 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) * @return the given reader or a new {@link BufferedReader} for the given reader - * @since 2.5 * @throws NullPointerException if the input parameter is null + * @since 2.5 */ public static BufferedReader buffer(final Reader reader) { return reader instanceof BufferedReader ? (BufferedReader) reader : new BufferedReader(reader); } /** - * Returns the given reader if it is already a {@link BufferedReader}, otherwise creates a BufferedReader from the given - * reader. + * Returns the given reader if it is already 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 - * @since 2.5 * @throws NullPointerException if the input parameter is null + * @since 2.5 */ public static BufferedReader buffer(final Reader reader, int size) { return reader instanceof BufferedReader ? (BufferedReader) reader : new BufferedReader(reader, size); } /** - * Returns the given Writer if it is already a {@link BufferedWriter}, otherwise creates a BufferedWriter from the given - * Writer. + * Returns the given Writer if it is already a {@link BufferedWriter}, otherwise creates a BufferedWriter from the + * given Writer. * - * @param writer - * the Writer to wrap or return (not null) + * @param writer the Writer to wrap or return (not null) * @return the given Writer or a new {@link BufferedWriter} for the given Writer - * @since 2.5 * @throws NullPointerException if the input parameter is null + * @since 2.5 */ public static BufferedWriter buffer(final Writer writer) { return writer instanceof BufferedWriter ? (BufferedWriter) writer : new BufferedWriter(writer); } /** - * Returns the given Writer if it is already a {@link BufferedWriter}, otherwise creates a BufferedWriter from the given - * Writer. + * Returns the given Writer if it is already a {@link BufferedWriter}, otherwise creates a BufferedWriter from the + * given Writer. * - * @param writer - * the Writer to wrap or return (not null) + * @param writer the Writer to wrap or return (not null) * @param size the buffer size, if a new BufferedWriter is created. * @return the given Writer or a new {@link BufferedWriter} for the given Writer - * @since 2.5 * @throws NullPointerException if the input parameter is null + * @since 2.5 */ public static BufferedWriter buffer(final Writer writer, int size) { return writer instanceof BufferedWriter ? (BufferedWriter) writer : new BufferedWriter(writer, size); } /** - * Returns the given OutputStream if it is already a {@link BufferedOutputStream}, otherwise creates a BufferedOutputStream from the given - * OutputStream. + * Returns the given OutputStream if it is already a {@link BufferedOutputStream}, otherwise creates a + * BufferedOutputStream from the given OutputStream. * - * @param outputStream - * the OutputStream to wrap or return (not null) + * @param outputStream the OutputStream to wrap or return (not null) * @return the given OutputStream or a new {@link BufferedOutputStream} for the given OutputStream - * @since 2.5 * @throws NullPointerException if the input parameter is null + * @since 2.5 */ public static BufferedOutputStream buffer(final OutputStream outputStream) { // reject null early on rather than waiting for IO operation to fail if (outputStream == null) { // not checked by BufferedOutputStream throw new NullPointerException(); } - return outputStream instanceof BufferedOutputStream ? (BufferedOutputStream) outputStream : new BufferedOutputStream(outputStream); + return outputStream instanceof BufferedOutputStream ? + (BufferedOutputStream) outputStream : new BufferedOutputStream(outputStream); } /** - * Returns the given OutputStream if it is already a {@link BufferedOutputStream}, otherwise creates a BufferedOutputStream from the given - * OutputStream. + * Returns the given OutputStream if it is already a {@link BufferedOutputStream}, otherwise creates a + * BufferedOutputStream from the given OutputStream. * - * @param outputStream - * the OutputStream to wrap or return (not null) + * @param outputStream the OutputStream to wrap or return (not null) * @param size the buffer size, if a new BufferedOutputStream is created. * @return the given OutputStream or a new {@link BufferedOutputStream} for the given OutputStream - * @since 2.5 * @throws NullPointerException if the input parameter is null + * @since 2.5 */ public static BufferedOutputStream buffer(final OutputStream outputStream, int size) { // reject null early on rather than waiting for IO operation to fail if (outputStream == null) { // not checked by BufferedOutputStream throw new NullPointerException(); } - return outputStream instanceof BufferedOutputStream ? (BufferedOutputStream) outputStream : new BufferedOutputStream(outputStream, size); + return outputStream instanceof BufferedOutputStream ? + (BufferedOutputStream) outputStream : new BufferedOutputStream(outputStream, size); } /** - * Returns the given InputStream if it is already a {@link BufferedInputStream}, otherwise creates a BufferedInputStream from the given - * InputStream. + * Returns the given InputStream if it is already a {@link BufferedInputStream}, otherwise creates a + * BufferedInputStream from the given InputStream. * - * @param inputStream - * the InputStream to wrap or return (not null) + * @param inputStream the InputStream to wrap or return (not null) * @return the given InputStream or a new {@link BufferedInputStream} for the given InputStream - * @since 2.5 * @throws NullPointerException if the input parameter is null + * @since 2.5 */ public static BufferedInputStream buffer(final InputStream inputStream) { // reject null early on rather than waiting for IO operation to fail if (inputStream == null) { // not checked by BufferedInputStream throw new NullPointerException(); } - return inputStream instanceof BufferedInputStream ? (BufferedInputStream) inputStream : new BufferedInputStream(inputStream); + return inputStream instanceof BufferedInputStream ? + (BufferedInputStream) inputStream : new BufferedInputStream(inputStream); } /** - * Returns the given InputStream if it is already a {@link BufferedInputStream}, otherwise creates a BufferedInputStream from the given - * InputStream. + * Returns the given InputStream if it is already a {@link BufferedInputStream}, otherwise creates a + * BufferedInputStream from the given InputStream. * - * @param inputStream - * the InputStream to wrap or return (not null) + * @param inputStream the InputStream to wrap or return (not null) * @param size the buffer size, if a new BufferedInputStream is created. * @return the given InputStream or a new {@link BufferedInputStream} for the given InputStream - * @since 2.5 * @throws NullPointerException if the input parameter is null + * @since 2.5 */ public static BufferedInputStream buffer(final InputStream inputStream, int size) { // reject null early on rather than waiting for IO operation to fail if (inputStream == null) { // not checked by BufferedInputStream throw new NullPointerException(); } - return inputStream instanceof BufferedInputStream ? (BufferedInputStream) inputStream : new BufferedInputStream(inputStream, size); + return inputStream instanceof BufferedInputStream ? + (BufferedInputStream) inputStream : new BufferedInputStream(inputStream, size); } // read toByteArray //----------------------------------------------------------------------- + /** * Gets the contents of an <code>InputStream</code> as a <code>byte[]</code>. - * <p> + * <p/> * This method buffers the input internally, so there is no need to use a * <code>BufferedInputStream</code>. * - * @param input the <code>InputStream</code> to read from + * @param input the <code>InputStream</code> to read from * @return the requested byte array * @throws NullPointerException if the input is null - * @throws IOException if an I/O error occurs + * @throws IOException if an I/O error occurs */ public static byte[] toByteArray(final InputStream input) throws IOException { final ByteArrayOutputStream output = new ByteArrayOutputStream(); @@ -741,28 +732,31 @@ public class IOUtils { * @param input the <code>InputStream</code> to read from * @param size the size of <code>InputStream</code> * @return the requested byte array - * @throws IOException if an I/O error occurs or <code>InputStream</code> size differ from parameter size + * @throws IOException if an I/O error occurs or <code>InputStream</code> size differ from parameter + * size * @throws IllegalArgumentException if size is less than zero or size is greater than Integer.MAX_VALUE * @see IOUtils#toByteArray(java.io.InputStream, int) * @since 2.1 */ public static byte[] toByteArray(final InputStream input, final long size) throws IOException { - if(size > Integer.MAX_VALUE) { - throw new IllegalArgumentException("Size cannot be greater than Integer max value: " + size); - } + if (size > Integer.MAX_VALUE) { + throw new IllegalArgumentException("Size cannot be greater than Integer max value: " + size); + } - return toByteArray(input, (int) size); + return toByteArray(input, (int) size); } /** * Gets the contents of an <code>InputStream</code> as a <code>byte[]</code>. * Use this method instead of <code>toByteArray(InputStream)</code> * when <code>InputStream</code> size is known + * * @param input the <code>InputStream</code> to read from * @param size the size of <code>InputStream</code> * @return the requested byte array - * @throws IOException if an I/O error occurs or <code>InputStream</code> size differ from parameter size + * @throws IOException if an I/O error occurs or <code>InputStream</code> size differ from parameter + * size * @throws IllegalArgumentException if size is less than zero * @since 2.1 */ @@ -794,14 +788,14 @@ public class IOUtils { /** * Gets the contents of a <code>Reader</code> as a <code>byte[]</code> * using the default character encoding of the platform. - * <p> + * <p/> * This method buffers the input internally, so there is no need to use a * <code>BufferedReader</code>. * - * @param input the <code>Reader</code> to read from + * @param input the <code>Reader</code> to read from * @return the requested byte array * @throws NullPointerException if the input is null - * @throws IOException if an I/O error occurs + * @throws IOException if an I/O error occurs * @deprecated 2.5 use {@link #toByteArray(Reader, Charset)} instead */ @Deprecated @@ -812,15 +806,15 @@ public class IOUtils { /** * Gets the contents of a <code>Reader</code> as a <code>byte[]</code> * using the specified character encoding. - * <p> + * <p/> * This method buffers the input internally, so there is no need to use a * <code>BufferedReader</code>. * - * @param input the <code>Reader</code> to read from - * @param encoding the encoding to use, null means platform default + * @param input the <code>Reader</code> to read from + * @param encoding the encoding to use, null means platform default * @return the requested byte array * @throws NullPointerException if the input is null - * @throws IOException if an I/O error occurs + * @throws IOException if an I/O error occurs * @since 2.3 */ public static byte[] toByteArray(final Reader input, final Charset encoding) throws IOException { @@ -832,21 +826,21 @@ public class IOUtils { /** * Gets the contents of a <code>Reader</code> as a <code>byte[]</code> * using the specified character encoding. - * <p> + * <p/> * Character encoding names can be found at * <a href="http://www.iana.org/assignments/character-sets";>IANA</a>. - * <p> + * <p/> * This method buffers the input internally, so there is no need to use a * <code>BufferedReader</code>. * - * @param input the <code>Reader</code> to read from - * @param encoding the encoding to use, null means platform default + * @param input the <code>Reader</code> to read from + * @param encoding the encoding to use, null means platform default * @return the requested byte array - * @throws NullPointerException if the input is null - * @throws IOException if an I/O error occurs - * @throws UnsupportedCharsetException - * thrown instead of {@link UnsupportedEncodingException} in version 2.2 if the encoding is not - * supported. + * @throws NullPointerException if the input is null + * @throws IOException if an I/O error occurs + * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io + * .UnsupportedEncodingException} in version 2.2 if the + * encoding is not supported. * @since 1.1 */ public static byte[] toByteArray(final Reader input, final String encoding) throws IOException { @@ -856,13 +850,13 @@ public class IOUtils { /** * Gets the contents of a <code>String</code> as a <code>byte[]</code> * using the default character encoding of the platform. - * <p> + * <p/> * This is the same as {@link String#getBytes()}. * - * @param input the <code>String</code> to convert + * @param input the <code>String</code> to convert * @return the requested byte array * @throws NullPointerException if the input is null - * @throws IOException if an I/O error occurs (never occurs) + * @throws IOException if an I/O error occurs (never occurs) * @deprecated 2.5 Use {@link String#getBytes()} instead */ @Deprecated @@ -874,13 +868,10 @@ public class IOUtils { /** * Gets the contents of a <code>URI</code> as a <code>byte[]</code>. * - * @param uri - * the <code>URI</code> to read + * @param uri the <code>URI</code> to read * @return the requested byte array - * @throws NullPointerException - * if the uri is null - * @throws IOException - * if an I/O exception occurs + * @throws NullPointerException if the uri is null + * @throws IOException if an I/O exception occurs * @since 2.4 */ public static byte[] toByteArray(final URI uri) throws IOException { @@ -890,13 +881,10 @@ public class IOUtils { /** * Gets the contents of a <code>URL</code> as a <code>byte[]</code>. * - * @param url - * the <code>URL</code> to read + * @param url the <code>URL</code> to read * @return the requested byte array - * @throws NullPointerException - * if the input is null - * @throws IOException - * if an I/O exception occurs + * @throws NullPointerException if the input is null + * @throws IOException if an I/O exception occurs * @since 2.4 */ public static byte[] toByteArray(final URL url) throws IOException { @@ -911,13 +899,10 @@ public class IOUtils { /** * Gets the contents of a <code>URLConnection</code> as a <code>byte[]</code>. * - * @param urlConn - * the <code>URLConnection</code> to read + * @param urlConn the <code>URLConnection</code> to read * @return the requested byte array - * @throws NullPointerException - * if the urlConn is null - * @throws IOException - * if an I/O exception occurs + * @throws NullPointerException if the urlConn is null + * @throws IOException if an I/O exception occurs * @since 2.4 */ public static byte[] toByteArray(final URLConnection urlConn) throws IOException { @@ -931,17 +916,18 @@ public class IOUtils { // read char[] //----------------------------------------------------------------------- + /** * Gets the contents of an <code>InputStream</code> as a character array * using the default character encoding of the platform. - * <p> + * <p/> * This method buffers the input internally, so there is no need to use a * <code>BufferedInputStream</code>. * - * @param is the <code>InputStream</code> to read from + * @param is the <code>InputStream</code> to read from * @return the requested character array * @throws NullPointerException if the input is null - * @throws IOException if an I/O error occurs + * @throws IOException if an I/O error occurs * @since 1.1 * @deprecated 2.5 use {@link #toCharArray(InputStream, Charset)} instead */ @@ -953,15 +939,15 @@ public class IOUtils { /** * Gets the contents of an <code>InputStream</code> as a character array * using the specified character encoding. - * <p> + * <p/> * This method buffers the input internally, so there is no need to use a * <code>BufferedInputStream</code>. * - * @param is the <code>InputStream</code> to read from - * @param encoding the encoding to use, null means platform default + * @param is the <code>InputStream</code> to read from + * @param encoding the encoding to use, null means platform default * @return the requested character array * @throws NullPointerException if the input is null - * @throws IOException if an I/O error occurs + * @throws IOException if an I/O error occurs * @since 2.3 */ public static char[] toCharArray(final InputStream is, final Charset encoding) @@ -974,21 +960,21 @@ public class IOUtils { /** * Gets the contents of an <code>InputStream</code> as a character array * using the specified character encoding. - * <p> + * <p/> * Character encoding names can be found at * <a href="http://www.iana.org/assignments/character-sets";>IANA</a>. - * <p> + * <p/> * This method buffers the input internally, so there is no need to use a * <code>BufferedInputStream</code>. * - * @param is the <code>InputStream</code> to read from - * @param encoding the encoding to use, null means platform default + * @param is the <code>InputStream</code> to read from + * @param encoding the encoding to use, null means platform default * @return the requested character array - * @throws NullPointerException if the input is null - * @throws IOException if an I/O error occurs - * @throws UnsupportedCharsetException - * thrown instead of {@link UnsupportedEncodingException} in version 2.2 if the encoding is not - * supported. + * @throws NullPointerException if the input is null + * @throws IOException if an I/O error occurs + * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io + * .UnsupportedEncodingException} in version 2.2 if the + * encoding is not supported. * @since 1.1 */ public static char[] toCharArray(final InputStream is, final String encoding) throws IOException { @@ -997,14 +983,14 @@ public class IOUtils { /** * Gets the contents of a <code>Reader</code> as a character array. - * <p> + * <p/> * This method buffers the input internally, so there is no need to use a * <code>BufferedReader</code>. * - * @param input the <code>Reader</code> to read from + * @param input the <code>Reader</code> to read from * @return the requested character array * @throws NullPointerException if the input is null - * @throws IOException if an I/O error occurs + * @throws IOException if an I/O error occurs * @since 1.1 */ public static char[] toCharArray(final Reader input) throws IOException { @@ -1015,17 +1001,18 @@ public class IOUtils { // read toString //----------------------------------------------------------------------- + /** * Gets the contents of an <code>InputStream</code> as a String * using the default character encoding of the platform. - * <p> + * <p/> * This method buffers the input internally, so there is no need to use a * <code>BufferedInputStream</code>. * - * @param input the <code>InputStream</code> to read from + * @param input the <code>InputStream</code> to read from * @return the requested String * @throws NullPointerException if the input is null - * @throws IOException if an I/O error occurs + * @throws IOException if an I/O error occurs * @deprecated 2.5 use {@link #toString(InputStream, Charset)} instead */ @Deprecated @@ -1040,11 +1027,12 @@ public class IOUtils { * This method buffers the input internally, so there is no need to use a * <code>BufferedInputStream</code>. * </p> - * @param input the <code>InputStream</code> to read from - * @param encoding the encoding to use, null means platform default + * + * @param input the <code>InputStream</code> to read from + * @param encoding the encoding to use, null means platform default * @return the requested String * @throws NullPointerException if the input is null - * @throws IOException if an I/O error occurs + * @throws IOException if an I/O error occurs * @since 2.3 */ public static String toString(final InputStream input, final Charset encoding) throws IOException { @@ -1056,21 +1044,21 @@ public class IOUtils { /** * Gets the contents of an <code>InputStream</code> as a String * using the specified character encoding. - * <p> + * <p/> * Character encoding names can be found at * <a href="http://www.iana.org/assignments/character-sets";>IANA</a>. - * <p> + * <p/> * This method buffers the input internally, so there is no need to use a * <code>BufferedInputStream</code>. * - * @param input the <code>InputStream</code> to read from - * @param encoding the encoding to use, null means platform default + * @param input the <code>InputStream</code> to read from + * @param encoding the encoding to use, null means platform default * @return the requested String - * @throws NullPointerException if the input is null - * @throws IOException if an I/O error occurs - * @throws UnsupportedCharsetException - * thrown instead of {@link UnsupportedEncodingException} in version 2.2 if the encoding is not - * supported. + * @throws NullPointerException if the input is null + * @throws IOException if an I/O error occurs + * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io + * .UnsupportedEncodingException} in version 2.2 if the + * encoding is not supported. */ public static String toString(final InputStream input, final String encoding) throws IOException { @@ -1079,14 +1067,14 @@ public class IOUtils { /** * Gets the contents of a <code>Reader</code> as a String. - * <p> + * <p/> * This method buffers the input internally, so there is no need to use a * <code>BufferedReader</code>. * - * @param input the <code>Reader</code> to read from + * @param input the <code>Reader</code> to read from * @return the requested String * @throws NullPointerException if the input is null - * @throws IOException if an I/O error occurs + * @throws IOException if an I/O error occurs */ public static String toString(final Reader input) throws IOException { final StringBuilderWriter sw = new StringBuilderWriter(); @@ -1097,8 +1085,7 @@ public class IOUtils { /** * Gets the contents at the given URI. * - * @param uri - * The URI source. + * @param uri The URI source. * @return The contents of the URL as a String. * @throws IOException if an I/O exception occurs. * @since 2.1 @@ -1112,10 +1099,8 @@ public class IOUtils { /** * Gets the contents at the given URI. * - * @param uri - * The URI source. - * @param encoding - * The encoding name for the URL contents. + * @param uri The URI source. + * @param encoding The encoding name for the URL contents. * @return The contents of the URL as a String. * @throws IOException if an I/O exception occurs. * @since 2.3. @@ -1127,15 +1112,13 @@ public class IOUtils { /** * Gets the contents at the given URI. * - * @param uri - * The URI source. - * @param encoding - * The encoding name for the URL contents. + * @param uri The URI source. + * @param encoding The encoding name for the URL contents. * @return The contents of the URL as a String. - * @throws IOException if an I/O exception occurs. - * @throws UnsupportedCharsetException - * thrown instead of {@link UnsupportedEncodingException} in version 2.2 if the encoding is not - * supported. + * @throws IOException if an I/O exception occurs. + * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io + * .UnsupportedEncodingException} in version 2.2 if the + * encoding is not supported. * @since 2.1 */ public static String toString(final URI uri, final String encoding) throws IOException { @@ -1145,8 +1128,7 @@ public class IOUtils { /** * Gets the contents at the given URL. * - * @param url - * The URL source. + * @param url The URL source. * @return The contents of the URL as a String. * @throws IOException if an I/O exception occurs. * @since 2.1 @@ -1160,10 +1142,8 @@ public class IOUtils { /** * Gets the contents at the given URL. * - * @param url - * The URL source. - * @param encoding - * The encoding name for the URL contents. + * @param url The URL source. + * @param encoding The encoding name for the URL contents. * @return The contents of the URL as a String. * @throws IOException if an I/O exception occurs. * @since 2.3 @@ -1180,15 +1160,13 @@ public class IOUtils { /** * Gets the contents at the given URL. * - * @param url - * The URL source. - * @param encoding - * The encoding name for the URL contents. + * @param url The URL source. + * @param encoding The encoding name for the URL contents. * @return The contents of the URL as a String. - * @throws IOException if an I/O exception occurs. - * @throws UnsupportedCharsetException - * thrown instead of {@link UnsupportedEncodingException} in version 2.2 if the encoding is not - * supported. + * @throws IOException if an I/O exception occurs. + * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io + * .UnsupportedEncodingException} in version 2.2 if the + * encoding is not supported. * @since 2.1 */ public static String toString(final URL url, final String encoding) throws IOException { @@ -1202,7 +1180,7 @@ public class IOUtils { * @param input the byte array to read from * @return the requested String * @throws NullPointerException if the input is null - * @throws IOException if an I/O error occurs (never occurs) + * @throws IOException if an I/O error occurs (never occurs) * @deprecated 2.5 Use {@link String#String(byte[])} instead */ @Deprecated @@ -1214,15 +1192,15 @@ public class IOUtils { /** * Gets the contents of a <code>byte[]</code> as a String * using the specified character encoding. - * <p> + * <p/> * Character encoding names can be found at * <a href="http://www.iana.org/assignments/character-sets";>IANA</a>. * * @param input the byte array to read from - * @param encoding the encoding to use, null means platform default + * @param encoding the encoding to use, null means platform default * @return the requested String * @throws NullPointerException if the input is null - * @throws IOException if an I/O error occurs (never occurs) + * @throws IOException if an I/O error occurs (never occurs) */ public static String toString(final byte[] input, final String encoding) throws IOException { return new String(input, Charsets.toCharset(encoding)); @@ -1230,17 +1208,18 @@ public class IOUtils { // readLines //----------------------------------------------------------------------- + /** * Gets the contents of an <code>InputStream</code> as a list of Strings, * one entry per line, using the default character encoding of the platform. - * <p> + * <p/> * This method buffers the input internally, so there is no need to use a * <code>BufferedInputStream</code>. * - * @param input the <code>InputStream</code> to read from, not null + * @param input the <code>InputStream</code> to read from, not null * @return the list of Strings, never null * @throws NullPointerException if the input is null - * @throws IOException if an I/O error occurs + * @throws IOException if an I/O error occurs * @since 1.1 * @deprecated 2.5 use {@link #readLines(InputStream, Charset)} instead */ @@ -1252,15 +1231,15 @@ public class IOUtils { /** * Gets the contents of an <code>InputStream</code> as a list of Strings, * one entry per line, using the specified character encoding. - * <p> + * <p/> * This method buffers the input internally, so there is no need to use a * <code>BufferedInputStream</code>. * - * @param input the <code>InputStream</code> to read from, not null - * @param encoding the encoding to use, null means platform default + * @param input the <code>InputStream</code> to read from, not null + * @param encoding the encoding to use, null means platform default * @return the list of Strings, never null * @throws NullPointerException if the input is null - * @throws IOException if an I/O error occurs + * @throws IOException if an I/O error occurs * @since 2.3 */ public static List<String> readLines(final InputStream input, final Charset encoding) throws IOException { @@ -1271,21 +1250,21 @@ public class IOUtils { /** * Gets the contents of an <code>InputStream</code> as a list of Strings, * one entry per line, using the specified character encoding. - * <p> + * <p/> * Character encoding names can be found at * <a href="http://www.iana.org/assignments/character-sets";>IANA</a>. - * <p> + * <p/> * This method buffers the input internally, so there is no need to use a * <code>BufferedInputStream</code>. * - * @param input the <code>InputStream</code> to read from, not null - * @param encoding the encoding to use, null means platform default + * @param input the <code>InputStream</code> to read from, not null + * @param encoding the encoding to use, null means platform default * @return the list of Strings, never null - * @throws NullPointerException if the input is null - * @throws IOException if an I/O error occurs - * @throws UnsupportedCharsetException - * thrown instead of {@link UnsupportedEncodingException} in version 2.2 if the encoding is not - * supported. + * @throws NullPointerException if the input is null + * @throws IOException if an I/O error occurs + * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io + * .UnsupportedEncodingException} in version 2.2 if the + * encoding is not supported. * @since 1.1 */ public static List<String> readLines(final InputStream input, final String encoding) throws IOException { @@ -1295,14 +1274,14 @@ public class IOUtils { /** * Gets the contents of a <code>Reader</code> as a list of Strings, * one entry per line. - * <p> + * <p/> * This method buffers the input internally, so there is no need to use a * <code>BufferedReader</code>. * - * @param input the <code>Reader</code> to read from, not null + * @param input the <code>Reader</code> to read from, not null * @return the list of Strings, never null * @throws NullPointerException if the input is null - * @throws IOException if an I/O error occurs + * @throws IOException if an I/O error occurs * @since 1.1 */ public static List<String> readLines(final Reader input) throws IOException { @@ -1318,15 +1297,16 @@ public class IOUtils { // lineIterator //----------------------------------------------------------------------- + /** * Returns an Iterator for the lines in a <code>Reader</code>. - * <p> + * <p/> * <code>LineIterator</code> holds a reference to the open * <code>Reader</code> specified here. When you have finished with the * iterator you should close the reader to free internal resources. * This can be done by closing the reader directly, or by calling * {@link LineIterator#close()} or {@link LineIterator#closeQuietly(LineIterator)}. - * <p> + * <p/> * The recommended usage pattern is: * <pre> * try { @@ -1340,7 +1320,7 @@ public class IOUtils { * } * </pre> * - * @param reader the <code>Reader</code> to read from, not null + * @param reader the <code>Reader</code> to read from, not null * @return an Iterator of the lines in the reader, never null * @throws IllegalArgumentException if the reader is null * @since 1.2 @@ -1352,13 +1332,13 @@ public class IOUtils { /** * Returns an Iterator for the lines in an <code>InputStream</code>, using * the character encoding specified (or default encoding if null). - * <p> + * <p/> * <code>LineIterator</code> holds a reference to the open * <code>InputStream</code> specified here. When you have finished with * the iterator you should close the stream to free internal resources. * This can be done by closing the stream directly, or by calling * {@link LineIterator#close()} or {@link LineIterator#closeQuietly(LineIterator)}. - * <p> + * <p/> * The recommended usage pattern is: * <pre> * try { @@ -1372,11 +1352,11 @@ public class IOUtils { * } * </pre> * - * @param input the <code>InputStream</code> to read from, not null - * @param encoding the encoding to use, null means platform default + * @param input the <code>InputStream</code> to read from, not null + * @param encoding the encoding to use, null means platform default * @return an Iterator of the lines in the reader, never null * @throws IllegalArgumentException if the input is null - * @throws IOException if an I/O error occurs, such as if the encoding is invalid + * @throws IOException if an I/O error occurs, such as if the encoding is invalid * @since 2.3 */ public static LineIterator lineIterator(final InputStream input, final Charset encoding) throws IOException { @@ -1386,13 +1366,13 @@ public class IOUtils { /** * Returns an Iterator for the lines in an <code>InputStream</code>, using * the character encoding specified (or default encoding if null). - * <p> + * <p/> * <code>LineIterator</code> holds a reference to the open * <code>InputStream</code> specified here. When you have finished with * the iterator you should close the stream to free internal resources. * This can be done by closing the stream directly, or by calling * {@link LineIterator#close()} or {@link LineIterator#closeQuietly(LineIterator)}. - * <p> + * <p/> * The recommended usage pattern is: * <pre> * try { @@ -1406,14 +1386,14 @@ public class IOUtils { * } * </pre> * - * @param input the <code>InputStream</code> to read from, not null - * @param encoding the encoding to use, null means platform default + * @param input the <code>InputStream</code> to read from, not null + * @param encoding the encoding to use, null means platform default * @return an Iterator of the lines in the reader, never null - * @throws IllegalArgumentException if the input is null - * @throws IOException if an I/O error occurs, such as if the encoding is invalid - * @throws UnsupportedCharsetException - * thrown instead of {@link UnsupportedEncodingException} in version 2.2 if the encoding is not - * supported. + * @throws IllegalArgumentException if the input is null + * @throws IOException if an I/O error occurs, such as if the encoding is invalid + * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io + * .UnsupportedEncodingException} in version 2.2 if the + * encoding is not supported. * @since 1.2 */ public static LineIterator lineIterator(final InputStream input, final String encoding) throws IOException { @@ -1421,6 +1401,7 @@ public class IOUtils { } //----------------------------------------------------------------------- + /** * Converts the specified CharSequence to an input stream, encoded as bytes * using the default character encoding of the platform. @@ -1451,17 +1432,17 @@ public class IOUtils { /** * Converts the specified CharSequence to an input stream, encoded as bytes * using the specified character encoding. - * <p> + * <p/> * Character encoding names can be found at * <a href="http://www.iana.org/assignments/character-sets";>IANA</a>. * * @param input the CharSequence to convert * @param encoding the encoding to use, null means platform default * @return an input stream - * @throws IOException if the encoding is invalid - * @throws UnsupportedCharsetException - * thrown instead of {@link UnsupportedEncodingException} in version 2.2 if the encoding is not - * supported. + * @throws IOException if the encoding is invalid + * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io + * .UnsupportedEncodingException} in version 2.2 if the + * encoding is not supported. * @since 2.0 */ public static InputStream toInputStream(final CharSequence input, final String encoding) throws IOException { @@ -1469,6 +1450,7 @@ public class IOUtils { } //----------------------------------------------------------------------- + /** * Converts the specified string to an input stream, encoded as bytes * using the default character encoding of the platform. @@ -1499,17 +1481,17 @@ public class IOUtils { /** * Converts the specified string to an input stream, encoded as bytes * using the specified character encoding. - * <p> + * <p/> * Character encoding names can be found at * <a href="http://www.iana.org/assignments/character-sets";>IANA</a>. * * @param input the string to convert * @param encoding the encoding to use, null means platform default * @return an input stream - * @throws IOException if the encoding is invalid - * @throws UnsupportedCharsetException - * thrown instead of {@link UnsupportedEncodingException} in version 2.2 if the encoding is not - * supported. + * @throws IOException if the encoding is invalid + * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io + * .UnsupportedEncodingException} in version 2.2 if the + * encoding is not supported. * @since 1.1 */ public static InputStream toInputStream(final String input, final String encoding) throws IOException { @@ -1519,14 +1501,15 @@ public class IOUtils { // write byte[] //----------------------------------------------------------------------- + /** * Writes bytes from a <code>byte[]</code> to an <code>OutputStream</code>. * - * @param data the byte array to write, do not modify during output, + * @param data the byte array to write, do not modify during output, * null ignored - * @param output the <code>OutputStream</code> to write to + * @param output the <code>OutputStream</code> to write to * @throws NullPointerException if output is null - * @throws IOException if an I/O error occurs + * @throws IOException if an I/O error occurs * @since 1.1 */ public static void write(final byte[] data, final OutputStream output) @@ -1541,11 +1524,11 @@ public class IOUtils { * This is intended for writing very large byte arrays which might otherwise cause excessive * memory usage if the native code has to allocate a copy. * - * @param data the byte array to write, do not modify during output, + * @param data the byte array to write, do not modify during output, * null ignored - * @param output the <code>OutputStream</code> to write to + * @param output the <code>OutputStream</code> to write to * @throws NullPointerException if output is null - * @throws IOException if an I/O error occurs + * @throws IOException if an I/O error occurs * @since 2.5 */ public static void writeChunked(final byte[] data, final OutputStream output) @@ -1553,7 +1536,7 @@ public class IOUtils { if (data != null) { int bytes = data.length; int offset = 0; - while(bytes > 0) { + while (bytes > 0) { int chunk = Math.min(bytes, DEFAULT_BUFFER_SIZE); output.write(data, offset, chunk); bytes -= chunk; @@ -1565,14 +1548,14 @@ public class IOUtils { /** * Writes bytes from a <code>byte[]</code> to chars on a <code>Writer</code> * using the default character encoding of the platform. - * <p> + * <p/> * This method uses {@link String#String(byte[])}. * - * @param data the byte array to write, do not modify during output, + * @param data the byte array to write, do not modify during output, * null ignored - * @param output the <code>Writer</code> to write to + * @param output the <code>Writer</code> to write to * @throws NullPointerException if output is null - * @throws IOException if an I/O error occurs + * @throws IOException if an I/O error occurs * @since 1.1 * @deprecated 2.5 use {@link #write(byte[], Writer, Charset)} instead */ @@ -1584,15 +1567,15 @@ public class IOUtils { /** * Writes bytes from a <code>byte[]</code> to chars on a <code>Writer</code> * using the specified character encoding. - * <p> + * <p/> * This method uses {@link String#String(byte[], String)}. * - * @param data the byte array to write, do not modify during output, + * @param data the byte array to write, do not modify during output, * null ignored - * @param output the <code>Writer</code> to write to - * @param encoding the encoding to use, null means platform default + * @param output the <code>Writer</code> to write to + * @param encoding the encoding to use, null means platform default * @throws NullPointerException if output is null - * @throws IOException if an I/O error occurs + * @throws IOException if an I/O error occurs * @since 2.3 */ public static void write(final byte[] data, final Writer output, final Charset encoding) throws IOException { @@ -1604,21 +1587,21 @@ public class IOUtils { /** * Writes bytes from a <code>byte[]</code> to chars on a <code>Writer</code> * using the specified character encoding. - * <p> + * <p/> * Character encoding names can be found at * <a href="http://www.iana.org/assignments/character-sets";>IANA</a>. - * <p> + * <p/> * This method uses {@link String#String(byte[], String)}. * - * @param data the byte array to write, do not modify during output, + * @param data the byte array to write, do not modify during output, * null ignored - * @param output the <code>Writer</code> to write to - * @param encoding the encoding to use, null means platform default - * @throws NullPointerException if output is null - * @throws IOException if an I/O error occurs - * @throws UnsupportedCharsetException - * thrown instead of {@link UnsupportedEncodingException} in version 2.2 if the encoding is not - * supported. + * @param output the <code>Writer</code> to write to + * @param encoding the encoding to use, null means platform default + * @throws NullPointerException if output is null + * @throws IOException if an I/O error occurs + * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io + * .UnsupportedEncodingException} in version 2.2 if the + * encoding is not supported. * @since 1.1 */ public static void write(final byte[] data, final Writer output, final String encoding) throws IOException { @@ -1627,14 +1610,15 @@ public class IOUtils { // write char[] //----------------------------------------------------------------------- + /** * Writes chars from a <code>char[]</code> to a <code>Writer</code> * - * @param data the char array to write, do not modify during output, + * @param data the char array to write, do not modify during output, * null ignored - * @param output the <code>Writer</code> to write to + * @param output the <code>Writer</code> to write to * @throws NullPointerException if output is null - * @throws IOException if an I/O error occurs + * @throws IOException if an I/O error occurs * @since 1.1 */ public static void write(final char[] data, final Writer output) throws IOException { @@ -1648,18 +1632,18 @@ public class IOUtils { * This is intended for writing very large byte arrays which might otherwise cause excessive * memory usage if the native code has to allocate a copy. * - * @param data the char array to write, do not modify during output, + * @param data the char array to write, do not modify during output, * null ignored - * @param output the <code>Writer</code> to write to + * @param output the <code>Writer</code> to write to * @throws NullPointerException if output is null - * @throws IOException if an I/O error occurs + * @throws IOException if an I/O error occurs * @since 2.5 */ public static void writeChunked(final char[] data, final Writer output) throws IOException { if (data != null) { int bytes = data.length; int offset = 0; - while(bytes > 0) { + while (bytes > 0) { int chunk = Math.min(bytes, DEFAULT_BUFFER_SIZE); output.write(data, offset, chunk); bytes -= chunk; @@ -1671,15 +1655,15 @@ public class IOUtils { /** * Writes chars from a <code>char[]</code> to bytes on an * <code>OutputStream</code>. - * <p> + * <p/> * This method uses {@link String#String(char[])} and * {@link String#getBytes()}. * - * @param data the char array to write, do not modify during output, + * @param data the char array to write, do not modify during output, * null ignored - * @param output the <code>OutputStream</code> to write to + * @param output the <code>OutputStream</code> to write to * @throws NullPointerException if output is null - * @throws IOException if an I/O error occurs + * @throws IOException if an I/O error occurs * @since 1.1 * @deprecated 2.5 use {@link #write(char[], OutputStream, Charset)} instead */ @@ -1692,16 +1676,16 @@ public class IOUtils { /** * Writes chars from a <code>char[]</code> to bytes on an * <code>OutputStream</code> using the specified character encoding. - * <p> + * <p/> * This method uses {@link String#String(char[])} and * {@link String#getBytes(String)}. * - * @param data the char array to write, do not modify during output, + * @param data the char array to write, do not modify during output, * null ignored - * @param output the <code>OutputStream</code> to write to - * @param encoding the encoding to use, null means platform default + * @param output the <code>OutputStream</code> to write to + * @param encoding the encoding to use, null means platform default * @throws NullPointerException if output is null - * @throws IOException if an I/O error occurs + * @throws IOException if an I/O error occurs * @since 2.3 */ public static void write(final char[] data, final OutputStream output, final Charset encoding) throws IOException { @@ -1713,22 +1697,21 @@ public class IOUtils { /** * Writes chars from a <code>char[]</code> to bytes on an * <code>OutputStream</code> using the specified character encoding. - * <p> + * <p/> * Character encoding names can be found at * <a href="http://www.iana.org/assignments/character-sets";>IANA</a>. - * <p> + * <p/> * This method uses {@link String#String(char[])} and * {@link String#getBytes(String)}. * - * @param data the char array to write, do not modify during output, + * @param data the char array to write, do not modify during output, * null ignored - * @param output the <code>OutputStream</code> to write to - * @param encoding the encoding to use, null means platform default - * @throws NullPointerException if output is null - * @throws IOException if an I/O error occurs - * @throws UnsupportedCharsetException - * thrown instead of {@link UnsupportedEncodingException} in version 2.2 if the encoding is not - * supported. + * @param output the <code>OutputStream</code> to write to + * @param encoding the encoding to use, null means platform default + * @throws NullPointerException if output is null + * @throws IOException if an I/O error occurs + * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io + * .UnsupportedEncodingException} in version 2.2 if the encoding is not supported. * @since 1.1 */ public static void write(final char[] data, final OutputStream output, final String encoding) @@ -1738,13 +1721,14 @@ public class IOUtils { // write CharSequence //----------------------------------------------------------------------- + /** * Writes chars from a <code>CharSequence</code> to a <code>Writer</code>. * - * @param data the <code>CharSequence</code> to write, null ignored - * @param output the <code>Writer</code> to write to + * @param data the <code>CharSequence</code> to write, null ignored + * @param output the <code>Writer</code> to write to * @throws NullPointerException if output is null - * @throws IOException if an I/O error occurs + * @throws IOException if an I/O error occurs * @since 2.0 */ public static void write(final CharSequence data, final Writer output) throws IOException { @@ -1757,13 +1741,13 @@ public class IOUtils { * Writes chars from a <code>CharSequence</code> to bytes on an * <code>OutputStream</code> using the default character encoding of the * platform. - * <p> + * <p/> * This method uses {@link String#getBytes()}. * - * @param data the <code>CharSequence</code> to write, null ignored - * @param output the <code>OutputStream</code> to write to + * @param data the <code>CharSequence</code> to write, null ignored + * @param output the <code>OutputStream</code> to write to * @throws NullPointerException if output is null - * @throws IOException if an I/O error occurs + * @throws IOException if an I/O error occurs * @since 2.0 * @deprecated 2.5 use {@link #write(CharSequence, OutputStream, Charset)} instead */ @@ -1776,17 +1760,18 @@ public class IOUtils { /** * Writes chars from a <code>CharSequence</code> to bytes on an * <code>OutputStream</code> using the specified character encoding. - * <p> + * <p/> * This method uses {@link String#getBytes(String)}. * - * @param data the <code>CharSequence</code> to write, null ignored - * @param output the <code>OutputStream</code> to write to - * @param encoding the encoding to use, null means platform default + * @param data the <code>CharSequence</code> to write, null ignored + * @param output the <code>OutputStream</code> to write to + * @param encoding the encoding to use, null means platform default * @throws NullPointerException if output is null - * @throws IOException if an I/O error occurs + * @throws IOException if an I/O error occurs * @since 2.3 */ - public static void write(final CharSequence data, final OutputStream output, final Charset encoding) throws IOException { + public static void write(final CharSequence data, final OutputStream output, final Charset encoding) + throws IOException { if (data != null) { write(data.toString(), output, encoding); } @@ -1795,35 +1780,36 @@ public class IOUtils { /** * Writes chars from a <code>CharSequence</code> to bytes on an * <code>OutputStream</code> using the specified character encoding. - * <p> + * <p/> * Character encoding names can be found at * <a href="http://www.iana.org/assignments/character-sets";>IANA</a>. - * <p> + * <p/> * This method uses {@link String#getBytes(String)}. * - * @param data the <code>CharSequence</code> to write, null ignored - * @param output the <code>OutputStream</code> to write to - * @param encoding the encoding to use, null means platform default - * @throws NullPointerException if output is null - * @throws IOException if an I/O error occurs - * @throws UnsupportedCharsetException - * thrown instead of {@link UnsupportedEncodingException} in version 2.2 if the encoding is not - * supported. + * @param data the <code>CharSequence</code> to write, null ignored + * @param output the <code>OutputStream</code> to write to + * @param encoding the encoding to use, null means platform default + * @throws NullPointerException if output is null + * @throws IOException if an I/O error occurs + * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io + * .UnsupportedEncodingException} in version 2.2 if the encoding is not supported. * @since 2.0 */ - public static void write(final CharSequence data, final OutputStream output, final String encoding) throws IOException { + public static void write(final CharSequence data, final OutputStream output, final String encoding) + throws IOException { write(data, output, Charsets.toCharset(encoding)); } // write String //----------------------------------------------------------------------- + /** * Writes chars from a <code>String</code> to a <code>Writer</code>. * - * @param data the <code>String</code> to write, null ignored - * @param output the <code>Writer</code> to write to + * @param data the <code>String</code> to write, null ignored + * @param output the <code>Writer</code> to write to * @throws NullPointerException if output is null - * @throws IOException if an I/O error occurs + * @throws IOException if an I/O error occurs * @since 1.1 */ public static void write(final String data, final Writer output) throws IOException { @@ -1836,13 +1822,13 @@ public class IOUtils { * Writes chars from a <code>String</code> to bytes on an * <code>OutputStream</code> using the default character encoding of the * platform. - * <p> + * <p/> * This method uses {@link String#getBytes()}. * - * @param data the <code>String</code> to write, null ignored - * @param output the <code>OutputStream</code> to write to + * @param data the <code>String</code> to write, null ignored + * @param output the <code>OutputStream</code> to write to * @throws NullPointerException if output is null - * @throws IOException if an I/O error occurs + * @throws IOException if an I/O error occurs * @since 1.1 * @deprecated 2.5 use {@link #write(String, OutputStream, Charset)} instead */ @@ -1855,14 +1841,14 @@ public class IOUtils { /** * Writes chars from a <code>String</code> to bytes on an * <code>OutputStream</code> using the specified character encoding. - * <p> + * <p/> * This method uses {@link String#getBytes(String)}. * - * @param data the <code>String</code> to write, null ignored - * @param output the <code>OutputStream</code> to write to - * @param encoding the encoding to use, null means platform default + * @param data the <code>String</code> to write, null ignored + * @param output the <code>OutputStream</code> to write to + * @param encoding the encoding to use, null means platform default * @throws NullPointerException if output is null - * @throws IOException if an I/O error occurs + * @throws IOException if an I/O error occurs * @since 2.3 */ public static void write(final String data, final OutputStream output, final Charset encoding) throws IOException { @@ -1874,20 +1860,19 @@ public class IOUtils { /** * Writes chars from a <code>String</code> to bytes on an * <code>OutputStream</code> using the specified character encoding. - * <p> + * <p/> * Character encoding names can be found at * <a href="http://www.iana.org/assignments/character-sets";>IANA</a>. - * <p> + * <p/> * This method uses {@link String#getBytes(String)}. * - * @param data the <code>String</code> to write, null ignored - * @param output the <code>OutputStream</code> to write to - * @param encoding the encoding to use, null means platform default - * @throws NullPointerException if output is null - * @throws IOException if an I/O error occurs - * @throws UnsupportedCharsetException - * thrown instead of {@link UnsupportedEncodingException} in version 2.2 if the encoding is not - * supported. + * @param data the <code>String</code> to write, null ignored + * @param output the <code>OutputStream</code> to write to + * @param encoding the encoding to use, null means platform default + * @throws NullPointerException if output is null + * @throws IOException if an I/O error occurs + * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io + * .UnsupportedEncodingException} in version 2.2 if the encoding is not supported. * @since 1.1 */ public static void write(final String data, final OutputStream output, final String encoding) @@ -1897,13 +1882,14 @@ public class IOUtils { // write StringBuffer //----------------------------------------------------------------------- + /** * Writes chars from a <code>StringBuffer</code> to a <code>Writer</code>. * - * @param data the <code>StringBuffer</code> to write, null ignored - * @param output the <code>Writer</code> to write to + * @param data the <code>StringBuffer</code> to write, null ignored + * @param output the <code>Writer</code> to write to * @throws NullPointerException if output is null - * @throws IOException if an I/O error occurs + * @throws IOException if an I/O error occurs * @since 1.1 * @deprecated replaced by write(CharSequence, Writer) */ @@ -1919,13 +1905,13 @@ public class IOUtils { * Writes chars from a <code>StringBuffer</code> to bytes on an * <code>OutputStream</code> using the default character encoding of the * platform. - * <p> + * <p/> * This method uses {@link String#getBytes()}. * - * @param data the <code>StringBuffer</code> to write, null ignored - * @param output the <code>OutputStream</code> to write to + * @param data the <code>StringBuffer</code> to write, null ignored + * @param output the <code>OutputStream</code> to write to * @throws NullPointerException if output is null - * @throws IOException if an I/O error occurs + * @throws IOException if an I/O error occurs * @since 1.1 * @deprecated replaced by write(CharSequence, OutputStream) */ @@ -1938,25 +1924,25 @@ public class IOUtils { /** * Writes chars from a <code>StringBuffer</code> to bytes on an * <code>OutputStream</code> using the specified character encoding. - * <p> + * <p/> * Character encoding names can be found at * <a href="http://www.iana.org/assignments/character-sets";>IANA</a>. - * <p> + * <p/> * This method uses {@link String#getBytes(String)}. * - * @param data the <code>StringBuffer</code> to write, null ignored - * @param output the <code>OutputStream</code> to write to - * @param encoding the encoding to use, null means platform default - * @throws NullPointerException if output is null - * @throws IOException if an I/O error occurs - * @throws UnsupportedCharsetException - * thrown instead of {@link UnsupportedEncodingException} in version 2.2 if the encoding is not - * supported. + * @param data the <code>StringBuffer</code> to write, null ignored + * @param output the <code>OutputStream</code> to write to + * @param encoding the encoding to use, null means platform default + * @throws NullPointerException if output is null + * @throws IOException if an I/O error occurs + * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io + * .UnsupportedEncodingException} in version 2.2 if the encoding is not supported. * @since 1.1 * @deprecated replaced by write(CharSequence, OutputStream, String) */ @Deprecated - public static void write(final StringBuffer data, final OutputStream output, final String encoding) throws IOException { + public static void write(final StringBuffer data, final OutputStream output, final String encoding) + throws IOException { if (data != null) { output.write(data.toString().getBytes(Charsets.toCharset(encoding))); } @@ -1964,22 +1950,23 @@ public class IOUtils { // writeLines //----------------------------------------------------------------------- + /** * Writes the <code>toString()</code> value of each item in a collection to * an <code>OutputStream</code> line by line, using the default character * encoding of the platform and the specified line ending. * - * @param lines the lines to write, null entries produce blank lines - * @param lineEnding the line separator to use, null is system default - * @param output the <code>OutputStream</code> to write to, not null, not closed + * @param lines the lines to write, null entries produce blank lines + * @param lineEnding the line separator to use, null is system default + * @param output the <code>OutputStream</code> to write to, not null, not closed * @throws NullPointerException if the output is null - * @throws IOException if an I/O error occurs + * @throws IOException if an I/O error occurs * @since 1.1 * @deprecated 2.5 use {@link #writeLines(Collection, String, OutputStream, Charset)} instead */ @Deprecated public static void writeLines(final Collection<?> lines, final String lineEnding, - final OutputStream output) throws IOException { + final OutputStream output) throws IOException { writeLines(lines, lineEnding, output, Charset.defaultCharset()); } @@ -1988,16 +1975,16 @@ public class IOUtils { * an <code>OutputStream</code> line by line, using the specified character * encoding and the specified line ending. * - * @param lines the lines to write, null entries produce blank lines - * @param lineEnding the line separator to use, null is system default - * @param output the <code>OutputStream</code> to write to, not null, not closed - * @param encoding the encoding to use, null means platform default + * @param lines the lines to write, null entries produce blank lines + * @param lineEnding the line separator to use, null is system default + * @param output the <code>OutputStream</code> to write to, not null, not closed + * @param encoding the encoding to use, null means platform default * @throws NullPointerException if the output is null - * @throws IOException if an I/O error occurs + * @throws IOException if an I/O error occurs * @since 2.3 */ - public static void writeLines(final Collection<?> lines, String lineEnding, final OutputStream output, final Charset encoding) - throws IOException { + public static void writeLines(final Collection<?> lines, String lineEnding, final OutputStream output, + final Charset encoding) throws IOException { if (lines == null) { return; } @@ -2017,23 +2004,23 @@ public class IOUtils { * Writes the <code>toString()</code> value of each item in a collection to * an <code>OutputStream</code> line by line, using the specified character * encoding and the specified line ending. - * <p> + * <p/> * Character encoding names can be found at * <a href="http://www.iana.org/assignments/character-sets";>IANA</a>. * - * @param lines the lines to write, null entries produce blank lines - * @param lineEnding the line separator to use, null is system default - * @param output the <code>OutputStream</code> to write to, not null, not closed - * @param encoding the encoding to use, null means platform default - * @throws NullPointerException if the output is null - * @throws IOException if an I/O error occurs - * @throws UnsupportedCharsetException - * thrown instead of {@link UnsupportedEncodingException} in version 2.2 if the encoding is not - * supported. + * @param lines the lines to write, null entries produce blank lines + * @param lineEnding the line separator to use, null is system default + * @param output the <code>OutputStream</code> to write to, not null, not closed + * @param encoding the encoding to use, null means platform default + * @throws NullPointerException if the output is null + * @throws IOException if an I/O error occurs + * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io + * .UnsupportedEncodingException} in version 2.2 if the + * encoding is not supported. * @since 1.1 */ public static void writeLines(final Collection<?> lines, final String lineEnding, - final OutputStream output, final String encoding) throws IOException { + final OutputStream output, final String encoding) throws IOException { writeLines(lines, lineEnding, output, Charsets.toCharset(encoding)); } @@ -2041,15 +2028,15 @@ public class IOUtils { * Writes the <code>toString()</code> value of each item in a collection to * a <code>Writer</code> line by line, using the specified line ending. * - * @param lines the lines to write, null entries produce blank lines - * @param lineEnding the line separator to use, null is system default - * @param writer the <code>Writer</code> to write to, not null, not closed + * @param lines the lines to write, null entries produce blank lines + * @param lineEnding the line separator to use, null is system default + * @param writer the <code>Writer</code> to write to, not null, not closed * @throws NullPointerException if the input is null - * @throws IOException if an I/O error occurs + * @throws IOException if an I/O error occurs * @since 1.1 */ public static void writeLines(final Collection<?> lines, String lineEnding, - final Writer writer) throws IOException { + final Writer writer) throws IOException { if (lines == null) { return; } @@ -2066,23 +2053,24 @@ public class IOUtils { // copy from InputStream //----------------------------------------------------------------------- + /** * Copies bytes from an <code>InputStream</code> to an * <code>OutputStream</code>. - * <p> + * <p/> * This method buffers the input internally, so there is no need to use a * <code>BufferedInputStream</code>. - * <p> + * <p/> * Large streams (over 2GB) will return a bytes copied value of * <code>-1</code> after the copy has completed since the correct * number of bytes cannot be returned as an int. For large streams * use the <code>copyLarge(InputStream, OutputStream)</code> method. * - * @param input the <code>InputStream</code> to read from - * @param output the <code>OutputStream</code> to write to + * @param input the <code>InputStream</code> to read from + * @param output the <code>OutputStream</code> to write to * @return the number of bytes copied, or -1 if > Integer.MAX_VALUE * @throws NullPointerException if the input or output is null - * @throws IOException if an I/O error occurs + * @throws IOException if an I/O error occurs * @since 1.1 */ public static int copy(final InputStream input, final OutputStream output) throws IOException { @@ -2096,40 +2084,37 @@ public class IOUtils { /** * Copies bytes from an <code>InputStream</code> to an <code>OutputStream</code> using an internal buffer of the * given size. - * <p> + * <p/> * This method buffers the input internally, so there is no need to use a <code>BufferedInputStream</code>. - * <p> - * @param input - * the <code>InputStream</code> to read from - * @param output - * the <code>OutputStream</code> to write to - * @param bufferSize - * the bufferSize used to copy from the input to the output + * <p/> + * + * @param input the <code>InputStream</code> to read from + * @param output the <code>OutputStream</code> to write to + * @param bufferSize the bufferSize used to copy from the input to the output * @return the number of bytes copied - * @throws NullPointerException - * if the input or output is null - * @throws IOException - * if an I/O error occurs + * @throws NullPointerException if the input or output is null + * @throws IOException if an I/O error occurs * @since 2.5 */ - public static long copy(final InputStream input, final OutputStream output, final int bufferSize) throws IOException { + public static long copy(final InputStream input, final OutputStream output, final int bufferSize) + throws IOException { return copyLarge(input, output, new byte[bufferSize]); } /**
[... 742 lines stripped ...]
