Javadoc

Author: garydgregory

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

@@ -178,7 +178,9 @@ public static int copy(final InputStream input, final OutputStream output) throw
     /**
      * Copies and convert bytes from an {@link InputStream} to chars on a
      * {@link Writer}.
-     * The platform's default encoding is used for the byte-to-char conversion.
+     * <p>
+     * This method uses the virtual machine's {@link Charset#defaultCharset() default charset} for byte-to-char conversion.
+     * </p>
      *
      * @param input the {@link InputStream} to read from
      * @param output the {@link Writer} to write to
@@ -218,7 +220,9 @@ public static void copy(
     /**
      * Serialize chars from a {@link Reader} to bytes on an
      * {@link OutputStream}, and flush the {@link OutputStream}.
-     * Uses the default platform encoding.
+     * <p>
+     * This method uses the virtual machine's {@link Charset#defaultCharset() default charset} for byte-to-char conversion.
+     * </p>
      *
      * @param input the {@link Reader} to read from
      * @param output the {@link OutputStream} to write to
@@ -288,7 +292,9 @@ public static int copy(
      * Serialize chars from a {@link String} to bytes on an
      * {@link OutputStream}, and
      * flush the {@link OutputStream}.
-     * Uses the platform default encoding.
+     * <p>
+     * This method uses the virtual machine's {@link Charset#defaultCharset() default charset} for byte-to-char conversion.
+     * </p>
      *
      * @param input the {@link String} to read from
      * @param output the {@link OutputStream} to write to

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

@@ -2733,14 +2733,14 @@ public static byte[] readFileToByteArray(final File file) throws IOException {
     }
 
     /**
-     * Reads the contents of a file into a String using the default encoding for the VM.
-     * The file is always closed.
+     * Reads the contents of a file into a String using the virtual machine's {@link Charset#defaultCharset() default charset}. The
+     * file is always closed.
      *
      * @param file the file to read, must not be {@code null}
      * @return the file contents, never {@code null}
      * @throws NullPointerException if file is {@code null}.
-     * @throws IOException if an I/O error occurs, including when the file does not exist, is a directory rather than a
-     *         regular file, or for some other reason why the file cannot be opened for reading.
+     * @throws IOException          if an I/O error occurs, including when the file does not exist, is a directory rather than a regular file, or for some other
+     *                              reason why the file cannot be opened for reading.
      * @since 1.3.1
      * @deprecated Use {@link #readFileToString(File, Charset)} instead (and specify the appropriate encoding)
      */
@@ -2782,14 +2782,14 @@ public static String readFileToString(final File file, final String charsetName)
     }
 
     /**
-     * Reads the contents of a file line by line to a List of Strings using the default encoding for the VM.
+     * Reads the contents of a file line by line to a List of Strings using the virtual machine's {@link Charset#defaultCharset() default charset}.
      * The file is always closed.
      *
      * @param file the file to read, must not be {@code null}
      * @return the list of Strings representing each line in the file, never {@code null}
      * @throws NullPointerException if file is {@code null}.
-     * @throws IOException if an I/O error occurs, including when the file does not exist, is a directory rather than a
-     *         regular file, or for some other reason why the file cannot be opened for reading.
+     * @throws IOException          if an I/O error occurs, including when the file does not exist, is a directory rather than a regular file, or for some other
+     *                              reason why the file cannot be opened for reading.
      * @since 1.3
      * @deprecated Use {@link #readLines(File, Charset)} instead (and specify the appropriate encoding)
      */
@@ -3201,7 +3201,7 @@ public static boolean waitFor(final File file, final int seconds) {
     }
 
     /**
-     * Writes a CharSequence to a file creating the file if it does not exist using the default encoding for the VM.
+     * Writes a CharSequence to a file creating the file if it does not exist using the virtual machine's {@link Charset#defaultCharset() default charset}.
      *
      * @param file the file to write
      * @param data the content to write to the file
@@ -3215,12 +3215,11 @@ public static void write(final File file, final CharSequence data) throws IOExce
     }
 
     /**
-     * Writes a CharSequence to a file creating the file if it does not exist using the default encoding for the VM.
+     * Writes a CharSequence to a file creating the file if it does not exist using the virtual machine's {@link Charset#defaultCharset() default charset}.
      *
      * @param file   the file to write
      * @param data   the content to write to the file
-     * @param append if {@code true}, then the data will be added to the
-     *               end of the file rather than overwriting
+     * @param append if {@code true}, then the data will be added to the end of the file rather than overwriting
      * @throws IOException in case of an I/O error
      * @since 2.1
      * @deprecated Use {@link #write(File, CharSequence, Charset, boolean)} instead (and specify the appropriate encoding)
@@ -3491,7 +3490,7 @@ public static void writeLines(final File file, final String charsetName, final C
     }
 
     /**
-     * Writes a String to a file creating the file if it does not exist using the default encoding for the VM.
+     * Writes a String to a file creating the file if it does not exist using the virtual machine's {@link Charset#defaultCharset() default charset}.
      *
      * @param file the file to write
      * @param data the content to write to the file
@@ -3504,12 +3503,11 @@ public static void writeStringToFile(final File file, final String data) throws
     }
 
     /**
-     * Writes a String to a file creating the file if it does not exist using the default encoding for the VM.
+     * Writes a String to a file creating the file if it does not exist using the virtual machine's {@link Charset#defaultCharset() default charset}.
      *
      * @param file   the file to write
      * @param data   the content to write to the file
-     * @param append if {@code true}, then the String will be added to the
-     *               end of the file rather than overwriting
+     * @param append if {@code true}, then the String will be added to the end of the file rather than overwriting
      * @throws IOException in case of an I/O error
      * @since 2.1
      * @deprecated Use {@link #writeStringToFile(File, String, Charset, boolean)} instead (and specify the appropriate encoding)

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

@@ -168,6 +168,9 @@ public static void dump(final byte[] data, final long offset,
      * All bytes between the given index (inclusive) and the end of the
      * data array are dumped.
      * </p>
+     * <p>
+     * This method uses the virtual machine's {@link Charset#defaultCharset() default charset}.
+     * </p>
      *
      * @param data  the byte array to be dumped
      * @param offset  offset of the byte array within a larger entity

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

@@ -1112,7 +1112,7 @@ public static long copy(final InputStream inputStream, final OutputStream output
 
     /**
      * Copies bytes from an {@link InputStream} to chars on a
-     * {@link Writer} using the default character encoding of the platform.
+     * {@link Writer} using the virtual machine's {@link Charset#defaultCharset() default charset}.
      * <p>
      * This method buffers the input internally, so there is no need to use a
      * {@link BufferedInputStream}.
@@ -1268,8 +1268,8 @@ public static long copy(final Reader reader, final Appendable output, final Char
 
     /**
      * Copies chars from a {@link Reader} to bytes on an
-     * {@link OutputStream} using the default character encoding of the
-     * platform, and calling flush.
+     * {@link OutputStream} using the the virtual machine's {@link Charset#defaultCharset() default charset},
+     * and calling flush.
      * <p>
      * This method buffers the input internally, so there is no need to use a
      * {@link BufferedReader}.
@@ -2173,7 +2173,7 @@ public static List<String> readLines(final CharSequence csq) throws UncheckedIOE
 
     /**
      * Gets the contents of an {@link InputStream} as a list of Strings,
-     * one entry per line, using the default character encoding of the platform.
+     * one entry per line, using the virtual machine's {@link Charset#defaultCharset() default charset}.
      * <p>
      * This method buffers the input internally, so there is no need to use a
      * {@link BufferedInputStream}.
@@ -2793,7 +2793,7 @@ static byte[] toByteArray(final IOTriFunction<byte[], Integer, Integer, Integer>
 
     /**
      * Gets the contents of a {@link Reader} as a {@code byte[]}
-     * using the default character encoding of the platform.
+     * using the virtual machine's {@link Charset#defaultCharset() default charset}.
      * <p>
      * This method buffers the input internally, so there is no need to use a
      * {@link BufferedReader}.
@@ -2858,7 +2858,7 @@ public static byte[] toByteArray(final Reader reader, final String charsetName)
 
     /**
      * Gets the contents of a {@link String} as a {@code byte[]}
-     * using the default character encoding of the platform.
+     * using the virtual machine's {@link Charset#defaultCharset() default charset}.
      * <p>
      * This is the same as {@link String#getBytes()}.
      * </p>
@@ -2919,7 +2919,7 @@ public static byte[] toByteArray(final URLConnection urlConnection) throws IOExc
 
     /**
      * Gets the contents of an {@link InputStream} as a character array
-     * using the default character encoding of the platform.
+     * using the virtual machine's {@link Charset#defaultCharset() default charset}.
      * <p>
      * This method buffers the input internally, so there is no need to use a
      * {@link BufferedInputStream}.
@@ -3004,7 +3004,7 @@ public static char[] toCharArray(final Reader reader) throws IOException {
 
     /**
      * Converts the specified CharSequence to an input stream, encoded as bytes
-     * using the default character encoding of the platform.
+     * using the virtual machine's {@link Charset#defaultCharset() default charset}.
      *
      * @param input the CharSequence to convert
      * @return an input stream
@@ -3049,7 +3049,7 @@ public static InputStream toInputStream(final CharSequence input, final String c
 
     /**
      * Converts the specified string to an input stream, encoded as bytes
-     * using the default character encoding of the platform.
+     * using the virtual machine's {@link Charset#defaultCharset() default charset}.
      *
      * @param input the string to convert
      * @return an input stream
@@ -3094,7 +3094,7 @@ public static InputStream toInputStream(final String input, final String charset
 
     /**
      * Gets the contents of a {@code byte[]} as a String
-     * using the default character encoding of the platform.
+     * using the virtual machine's {@link Charset#defaultCharset() default charset}.
      *
      * @param input the byte array to read
      * @return the requested String
@@ -3126,7 +3126,7 @@ public static String toString(final byte[] input, final String charsetName) {
 
     /**
      * Gets the contents of an {@link InputStream} as a String
-     * using the default character encoding of the platform.
+     * using the virtual machine's {@link Charset#defaultCharset() default charset}.
      * <p>
      * This method buffers the input internally, so there is no need to use a
      * {@link BufferedInputStream}.
@@ -3255,7 +3255,7 @@ public static String toString(final Reader reader) throws IOException {
     }
 
     /**
-     * Gets the contents at the given URI.
+     * Gets the contents at the given URI using the virtual machine's {@link Charset#defaultCharset() default charset}.
      *
      * @param uri The URI source.
      * @return The contents of the URL as a String.
@@ -3296,7 +3296,7 @@ public static String toString(final URI uri, final String charsetName) throws IO
     }
 
     /**
-     * Gets the contents at the given URL.
+     * Gets the contents at the given URL using the virtual machine's {@link Charset#defaultCharset() default charset}.
      *
      * @param url The URL source.
      * @return The contents of the URL as a String.
@@ -3355,7 +3355,7 @@ public static void write(final byte[] data, final OutputStream output)
 
     /**
      * Writes bytes from a {@code byte[]} to chars on a {@link Writer}
-     * using the default character encoding of the platform.
+     * using the virtual machine's {@link Charset#defaultCharset() default charset}.
      * <p>
      * This method uses {@link String#String(byte[])}.
      * </p>
@@ -3422,8 +3422,7 @@ public static void write(final byte[] data, final Writer writer, final String ch
      * Writes chars from a {@code char[]} to bytes on an
      * {@link OutputStream}.
      * <p>
-     * This method uses {@link String#String(char[])} and
-     * {@link String#getBytes()}.
+     * This method uses the virtual machine's {@link Charset#defaultCharset() default charset}.
      * </p>
      *
      * @param data the char array to write, do not modify during output,
@@ -3506,8 +3505,7 @@ public static void write(final char[] data, final Writer writer) throws IOExcept
 
     /**
      * Writes chars from a {@link CharSequence} to bytes on an
-     * {@link OutputStream} using the default character encoding of the
-     * platform.
+     * {@link OutputStream} using the virtual machine's {@link Charset#defaultCharset() default charset}.
      * <p>
      * This method uses {@link String#getBytes()}.
      * </p>
@@ -3587,8 +3585,7 @@ public static void write(final CharSequence data, final Writer writer) throws IO
 
     /**
      * Writes chars from a {@link String} to bytes on an
-     * {@link OutputStream} using the default character encoding of the
-     * platform.
+     * {@link OutputStream} using the virtual machine's {@link Charset#defaultCharset() default charset}.
      * <p>
      * This method uses {@link String#getBytes()}.
      * </p>
@@ -3789,8 +3786,8 @@ public static void writeChunked(final char[] data, final Writer writer) throws I
 
     /**
      * Writes the {@link #toString()} value of each item in a collection to
-     * an {@link OutputStream} line by line, using the default character
-     * encoding of the platform and the specified line ending.
+     * an {@link OutputStream} line by line, using the virtual machine's {@link Charset#defaultCharset() default charset}
+     * 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

src/main/java/org/apache/commons/io/charset/CharsetDecoders.java

@@ -29,6 +29,9 @@ public final class CharsetDecoders {
 
     /**
      * Returns the given non-null CharsetDecoder or a new default CharsetDecoder.
+     * <p>
+     * Null input maps to the virtual machine's {@link Charset#defaultCharset() default charset} decoder.
+     * </p>
      *
      * @param charsetDecoder The CharsetDecoder to test.
      * @return the given non-null CharsetDecoder or a new default CharsetDecoder.

src/main/java/org/apache/commons/io/charset/CharsetEncoders.java

@@ -30,6 +30,9 @@ public final class CharsetEncoders {
 
     /**
      * Returns the given non-null CharsetEncoder or a new default CharsetEncoder.
+     * <p>
+     * Null input maps to the virtual machine's {@link Charset#defaultCharset() default charset} decoder.
+     * </p>
      *
      * @param charsetEncoder The CharsetEncoder to test.
      * @return the given non-null CharsetEncoder or a new default CharsetEncoder.

src/main/java/org/apache/commons/io/filefilter/MagicNumberFileFilter.java

@@ -215,9 +215,11 @@ public MagicNumberFileFilter(final String magicNumber) {
      * </p>
      *
      * <pre>
-     * MagicNumberFileFilter tarFileFilter =
-     *     MagicNumberFileFilter("ustar", 257);
+     * MagicNumberFileFilter tarFileFilter = MagicNumberFileFilter("ustar", 257);
      * </pre>
+     * <p>
+     * This method uses the virtual machine's {@link Charset#defaultCharset() default charset}.
+     * </p>
      *
      * @param magicNumber the magic number to look for in the file.
      *        The string is converted to bytes using the platform default charset.

src/main/java/org/apache/commons/io/input/ReaderInputStream.java

@@ -220,8 +220,8 @@ private static CharsetEncoder newEncoder(final Charset charset) {
     private boolean endOfInput;
 
     /**
-     * Constructs a new {@link ReaderInputStream} that uses the default character encoding with a default input buffer size of
-     * {@value IOUtils#DEFAULT_BUFFER_SIZE} characters.
+     * Constructs a new {@link ReaderInputStream} that uses the virtual machine's {@link Charset#defaultCharset() default charset} with a default input buffer
+     * size of {@value IOUtils#DEFAULT_BUFFER_SIZE} characters.
      *
      * @param reader the target {@link Reader}
      * @deprecated Use {@link ReaderInputStream#builder()} instead

src/main/java/org/apache/commons/io/input/ReversedLinesFileReader.java

@@ -307,8 +307,7 @@ public static Builder builder() {
     private boolean trailingNewlineOfFileSkipped;
 
     /**
-     * Constructs a ReversedLinesFileReader with default block size of 4KB and the
-     * platform's default encoding.
+     * Constructs a ReversedLinesFileReader with default block size of 4KB and the virtual machine's {@link Charset#defaultCharset() default charset}.
      *
      * @param file the file to be read
      * @throws IOException if an I/O error occurs.

src/main/java/org/apache/commons/io/input/Tailer.java

@@ -475,7 +475,9 @@ public String toString() {
 
     private static final String RAF_READ_ONLY_MODE = "r";
 
-    // The default charset used for reading files
+    /**
+     * The the virtual machine's {@link Charset#defaultCharset() default charset} used for reading files.
+     */
     private static final Charset DEFAULT_CHARSET = Charset.defaultCharset();
 
     /**