This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-io.git
The following commit(s) were added to refs/heads/master by this push:
new c20dacf8a Javadoc
c20dacf8a is described below
commit c20dacf8a42d0962b44ee7cd7f69a2acf3248c20
Author: Gary D. Gregory <garydgreg...@gmail.com>
AuthorDate: Sat Feb 1 09:46:00 2025 -0500
Javadoc
---
src/main/java/org/apache/commons/io/CopyUtils.java | 12 +++++--
src/main/java/org/apache/commons/io/FileUtils.java | 28 +++++++--------
src/main/java/org/apache/commons/io/HexDump.java | 3 ++
src/main/java/org/apache/commons/io/IOUtils.java | 41 ++++++++++------------
.../apache/commons/io/charset/CharsetDecoders.java | 3 ++
.../apache/commons/io/charset/CharsetEncoders.java | 3 ++
.../io/filefilter/MagicNumberFileFilter.java | 6 ++--
.../apache/commons/io/input/ReaderInputStream.java | 4 +--
.../commons/io/input/ReversedLinesFileReader.java | 3 +-
.../java/org/apache/commons/io/input/Tailer.java | 4 ++-
.../io/output/AbstractByteArrayOutputStream.java | 4 +--
.../commons/io/output/LockableFileWriter.java | 3 ++
.../commons/io/output/WriterOutputStream.java | 5 +--
13 files changed, 68 insertions(+), 51 deletions(-)
diff --git a/src/main/java/org/apache/commons/io/CopyUtils.java
b/src/main/java/org/apache/commons/io/CopyUtils.java
index 72da100a5..bd651f76c 100644
--- a/src/main/java/org/apache/commons/io/CopyUtils.java
+++ b/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
diff --git a/src/main/java/org/apache/commons/io/FileUtils.java
b/src/main/java/org/apache/commons/io/FileUtils.java
index 6a998c01b..e81e976df 100644
--- a/src/main/java/org/apache/commons/io/FileUtils.java
+++ b/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)
diff --git a/src/main/java/org/apache/commons/io/HexDump.java
b/src/main/java/org/apache/commons/io/HexDump.java
index 2a463726f..9f63fa90e 100644
--- a/src/main/java/org/apache/commons/io/HexDump.java
+++ b/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
diff --git a/src/main/java/org/apache/commons/io/IOUtils.java
b/src/main/java/org/apache/commons/io/IOUtils.java
index 93b31ba33..bfda61c36 100644
--- a/src/main/java/org/apache/commons/io/IOUtils.java
+++ b/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
diff --git a/src/main/java/org/apache/commons/io/charset/CharsetDecoders.java
b/src/main/java/org/apache/commons/io/charset/CharsetDecoders.java
index b5a182e79..425f59621 100644
--- a/src/main/java/org/apache/commons/io/charset/CharsetDecoders.java
+++ b/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.
diff --git a/src/main/java/org/apache/commons/io/charset/CharsetEncoders.java
b/src/main/java/org/apache/commons/io/charset/CharsetEncoders.java
index fe8c4c272..7731f9349 100644
--- a/src/main/java/org/apache/commons/io/charset/CharsetEncoders.java
+++ b/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.
diff --git
a/src/main/java/org/apache/commons/io/filefilter/MagicNumberFileFilter.java
b/src/main/java/org/apache/commons/io/filefilter/MagicNumberFileFilter.java
index 70e4d18d9..14c881fa3 100644
--- a/src/main/java/org/apache/commons/io/filefilter/MagicNumberFileFilter.java
+++ b/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.
diff --git a/src/main/java/org/apache/commons/io/input/ReaderInputStream.java
b/src/main/java/org/apache/commons/io/input/ReaderInputStream.java
index d28ae6434..9fb5185f2 100644
--- a/src/main/java/org/apache/commons/io/input/ReaderInputStream.java
+++ b/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
diff --git
a/src/main/java/org/apache/commons/io/input/ReversedLinesFileReader.java
b/src/main/java/org/apache/commons/io/input/ReversedLinesFileReader.java
index a8a2ee2ca..9b8d8a99d 100644
--- a/src/main/java/org/apache/commons/io/input/ReversedLinesFileReader.java
+++ b/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.
diff --git a/src/main/java/org/apache/commons/io/input/Tailer.java
b/src/main/java/org/apache/commons/io/input/Tailer.java
index f45fee3d2..1638ce0e9 100644
--- a/src/main/java/org/apache/commons/io/input/Tailer.java
+++ b/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();
/**
diff --git
a/src/main/java/org/apache/commons/io/output/AbstractByteArrayOutputStream.java
b/src/main/java/org/apache/commons/io/output/AbstractByteArrayOutputStream.java
index ba3f29bc1..9695e9ecb 100644
---
a/src/main/java/org/apache/commons/io/output/AbstractByteArrayOutputStream.java
+++
b/src/main/java/org/apache/commons/io/output/AbstractByteArrayOutputStream.java
@@ -277,8 +277,8 @@ protected <T extends InputStream> InputStream
toInputStream(final InputStreamCon
}
/**
- * Gets the current contents of this byte stream as a string
- * using the platform default charset.
+ * Gets the current contents of this byte stream as a string using the
virtual machine's {@link Charset#defaultCharset() default charset}.
+ *
* @return the contents of the byte array as a String
* @see java.io.ByteArrayOutputStream#toString()
* @see Charset#defaultCharset()
diff --git a/src/main/java/org/apache/commons/io/output/LockableFileWriter.java
b/src/main/java/org/apache/commons/io/output/LockableFileWriter.java
index 3e406473b..bafb7524f 100644
--- a/src/main/java/org/apache/commons/io/output/LockableFileWriter.java
+++ b/src/main/java/org/apache/commons/io/output/LockableFileWriter.java
@@ -195,6 +195,9 @@ public LockableFileWriter(final File file, final boolean
append) throws IOExcept
/**
* Constructs a LockableFileWriter.
+ * <p>
+ * The new instance uses the virtual machine's {@link
Charset#defaultCharset() default charset}.
+ * </p>
*
* @param file the file to write to, not null
* @param append true if content should be appended, false to overwrite
diff --git a/src/main/java/org/apache/commons/io/output/WriterOutputStream.java
b/src/main/java/org/apache/commons/io/output/WriterOutputStream.java
index f767ed36b..39fdb2f8f 100644
--- a/src/main/java/org/apache/commons/io/output/WriterOutputStream.java
+++ b/src/main/java/org/apache/commons/io/output/WriterOutputStream.java
@@ -245,8 +245,9 @@ private static void checkIbmJdkWithBrokenUTF16(final
Charset charset) {
private final CharBuffer decoderOut;
/**
- * Constructs a new {@link WriterOutputStream} that uses the default
character encoding and with a default output buffer size of {@value
#BUFFER_SIZE}
- * characters. The output buffer will only be flushed when it overflows or
when {@link #flush()} or {@link #close()} is called.
+ * Constructs a new {@link WriterOutputStream} that uses the virtual
machine's {@link Charset#defaultCharset() default charset} and with a default
output
+ * buffer size of {@value #BUFFER_SIZE} characters. The output buffer will
only be flushed when it overflows or when {@link #flush()} or {@link #close()}
is
+ * called.
*
* @param writer the target {@link Writer}
* @deprecated Use {@link #builder()}, {@link Builder}, and {@link
Builder#get()}
