| Charset | + *Description | + *
|---|---|
| {@code US-ASCII} | + *Seven-bit ASCII, a.k.a. ISO646-US, a.k.a. the Basic Latin block of the Unicode character set. | + *
| {@code ISO-8859-1} | + *ISO Latin Alphabet No. 1, a.k.a. ISO-LATIN-1. | + *
| {@code UTF-8} | + *Eight-bit Unicode Transformation Format. | + *
| {@code UTF-16BE} | + *Sixteen-bit Unicode Transformation Format, big-endian byte order. | + *
| {@code UTF-16LE} | + *Sixteen-bit Unicode Transformation Format, little-endian byte order. | + *
| {@code UTF-16} | + *Sixteen-bit Unicode Transformation Format, byte order specified by a mandatory initial byte-order mark (either order + * accepted on input, big-endian used on output.) | + *
* For byte-to-char methods, a {@code copy} variant allows the encoding @@ -115,9 +117,10 @@ public class CopyUtils { /** * Copies bytes from a {@code byte[]} to an {@link OutputStream}. - * @param input the byte array to read from - * @param output the {@link OutputStream} to write to - * @throws IOException In case of an I/O problem + * + * @param input the byte array to read from. + * @param output the {@link OutputStream} to write to. + * @throws IOException In case of an I/O problem. */ public static void copy(final byte[] input, final OutputStream output) throws IOException { output.write(input); @@ -128,10 +131,10 @@ public static void copy(final byte[] input, final OutputStream output) throws IO * {@link Writer}. * The platform's default encoding is used for the byte-to-char conversion. * - * @param input the byte array to read from - * @param output the {@link Writer} to write to - * @throws IOException In case of an I/O problem - * @deprecated Use {@link #copy(byte[], Writer, String)} instead + * @param input the byte array to read from. + * @param output the {@link Writer} to write to. + * @throws IOException In case of an I/O problem. + * @deprecated Use {@link #copy(byte[], Writer, String)} instead. */ @Deprecated public static void copy(final byte[] input, final Writer output) throws IOException { @@ -143,12 +146,12 @@ public static void copy(final byte[] input, final Writer output) throws IOExcept * Copies and convert bytes from a {@code byte[]} to chars on a * {@link Writer}, using the specified encoding. * - * @param input the byte array to read from - * @param output the {@link Writer} to write to + * @param input the byte array to read from. + * @param output the {@link Writer} to write to. * @param encoding The name of a supported character encoding. See the - * IANA + * IANA * Charset Registry for a list of valid encoding types. - * @throws IOException In case of an I/O problem + * @throws IOException In case of an I/O problem. */ public static void copy(final byte[] input, final Writer output, final String encoding) throws IOException { final ByteArrayInputStream inputStream = new ByteArrayInputStream(input); @@ -159,10 +162,10 @@ public static void copy(final byte[] input, final Writer output, final String en * Copies bytes from an {@link InputStream} to an * {@link OutputStream}. * - * @param input the {@link InputStream} to read from - * @param output the {@link OutputStream} to write to - * @return the number of bytes copied - * @throws IOException In case of an I/O problem + * @param input the {@link InputStream} to read from. + * @param output the {@link OutputStream} to write to. + * @return the number of bytes copied. + * @throws IOException In case of an I/O problem. */ public static int copy(final InputStream input, final OutputStream output) throws IOException { final byte[] buffer = IOUtils.byteArray(); @@ -179,13 +182,13 @@ 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}. *
- * This method uses the virtual machine's {@link Charset#defaultCharset() default charset} for byte-to-char conversion. + * This method uses the virtual machine's {@linkplain Charset#defaultCharset() default charset} for byte-to-char conversion. *
* - * @param input the {@link InputStream} to read from - * @param output the {@link Writer} to write to - * @throws IOException In case of an I/O problem - * @deprecated Use {@link #copy(InputStream, Writer, String)} instead + * @param input the {@link InputStream} to read from. + * @param output the {@link Writer} to write to. + * @throws IOException In case of an I/O problem. + * @deprecated Use {@link #copy(InputStream, Writer, String)} instead. */ @Deprecated public static void copy( @@ -201,12 +204,12 @@ public static void copy( * Copies and convert bytes from an {@link InputStream} to chars on a * {@link Writer}, using the specified encoding. * - * @param input the {@link InputStream} to read from - * @param output the {@link Writer} to write to + * @param input the {@link InputStream} to read from. + * @param output the {@link Writer} to write to. * @param encoding The name of a supported character encoding. See the - * IANA + * IANA * Charset Registry for a list of valid encoding types. - * @throws IOException In case of an I/O problem + * @throws IOException In case of an I/O problem. */ public static void copy( final InputStream input, @@ -221,13 +224,13 @@ public static void copy( * Serialize chars from a {@link Reader} to bytes on an * {@link OutputStream}, and flush the {@link OutputStream}. *- * This method uses the virtual machine's {@link Charset#defaultCharset() default charset} for byte-to-char conversion. + * This method uses the virtual machine's {@linkplain Charset#defaultCharset() default charset} for byte-to-char conversion. *
* - * @param input the {@link Reader} to read from - * @param output the {@link OutputStream} to write to - * @throws IOException In case of an I/O problem - * @deprecated Use {@link #copy(Reader, OutputStream, String)} instead + * @param input the {@link Reader} to read from. + * @param output the {@link OutputStream} to write to. + * @throws IOException In case of an I/O problem. + * @deprecated Use {@link #copy(Reader, OutputStream, String)} instead. */ @Deprecated public static void copy( @@ -246,12 +249,12 @@ public static void copy( * Serialize chars from a {@link Reader} to bytes on an * {@link OutputStream}, and flush the {@link OutputStream}. * - * @param input the {@link Reader} to read from - * @param output the {@link OutputStream} to write to + * @param input the {@link Reader} to read from. + * @param output the {@link OutputStream} to write to. * @param encoding The name of a supported character encoding. See the - * IANA + * IANA * Charset Registry for a list of valid encoding types. - * @throws IOException In case of an I/O problem + * @throws IOException In case of an I/O problem. * @since 2.5 */ public static void copy( @@ -269,23 +272,25 @@ public static void copy( /** * Copies chars from a {@link Reader} to a {@link Writer}. * - * @param input the {@link Reader} to read from - * @param output the {@link Writer} to write to - * @return the number of characters copied - * @throws IOException In case of an I/O problem + * @param input the {@link Reader} to read from. + * @param output the {@link Writer} to write to. + * @return the number of characters copied. + * @throws IOException In case of an I/O problem. */ public static int copy( final Reader input, final Writer output) throws IOException { - final char[] buffer = IOUtils.getScratchCharArray(); - int count = 0; - int n; - while (EOF != (n = input.read(buffer))) { - output.write(buffer, 0, n); - count += n; + try (ScratchChars scratch = IOUtils.ScratchChars.get()) { + final char[] buffer = scratch.array(); + int count = 0; + int n; + while (EOF != (n = input.read(buffer))) { + output.write(buffer, 0, n); + count += n; + } + return count; } - return count; } /** @@ -293,13 +298,13 @@ public static int copy( * {@link OutputStream}, and * flush the {@link OutputStream}. *- * This method uses the virtual machine's {@link Charset#defaultCharset() default charset} for byte-to-char conversion. + * This method uses the virtual machine's {@linkplain Charset#defaultCharset() default charset} for byte-to-char conversion. *
* - * @param input the {@link String} to read from - * @param output the {@link OutputStream} to write to - * @throws IOException In case of an I/O problem - * @deprecated Use {@link #copy(String, OutputStream, String)} instead + * @param input the {@link String} to read from. + * @param output the {@link OutputStream} to write to. + * @throws IOException In case of an I/O problem. + * @deprecated Use {@link #copy(String, OutputStream, String)} instead. */ @Deprecated public static void copy( @@ -320,12 +325,12 @@ public static void copy( * {@link OutputStream}, and * flush the {@link OutputStream}. * - * @param input the {@link String} to read from - * @param output the {@link OutputStream} to write to + * @param input the {@link String} to read from. + * @param output the {@link OutputStream} to write to. * @param encoding The name of a supported character encoding. See the - * IANA + * IANA * Charset Registry for a list of valid encoding types. - * @throws IOException In case of an I/O problem + * @throws IOException In case of an I/O problem. * @since 2.5 */ public static void copy( @@ -344,9 +349,9 @@ public static void copy( /** * Copies chars from a {@link String} to a {@link Writer}. * - * @param input the {@link String} to read from - * @param output the {@link Writer} to write to - * @throws IOException In case of an I/O problem + * @param input the {@link String} to read from. + * @param output the {@link Writer} to write to. + * @throws IOException In case of an I/O problem. */ public static void copy(final String input, final Writer output) throws IOException { diff --git a/src/main/java/org/apache/commons/io/DirectoryWalker.java b/src/main/java/org/apache/commons/io/DirectoryWalker.java index ac3d8bd5fd7..1d2a7678fd4 100644 --- a/src/main/java/org/apache/commons/io/DirectoryWalker.java +++ b/src/main/java/org/apache/commons/io/DirectoryWalker.java @@ -167,7 +167,7 @@ ** Two possible scenarios are envisaged for cancellation: @@ -196,14 +196,14 @@ *
* public class FooDirectoryWalker extends DirectoryWalker {
*
- * private volatile boolean cancelled = false;
+ * private volatile boolean canceled = false;
*
* public void cancel() {
- * cancelled = true;
+ * canceled = true;
* }
*
* protected boolean handleIsCancelled(File file, int depth, Collection results) {
- * return cancelled;
+ * return canceled;
* }
*
* protected void handleCancelled(File startDirectory, Collection results, CancelException cancel) {
@@ -265,6 +265,7 @@ public static class CancelException extends IOException {
/** The file being processed when the exception was thrown. */
private final File file;
+
/** The file depth when the exception was thrown. */
private final int depth;
@@ -272,8 +273,8 @@ public static class CancelException extends IOException {
* Constructs a {@link CancelException} with
* the file and depth when cancellation occurred.
*
- * @param file the file when the operation was cancelled, may be null
- * @param depth the depth when the operation was cancelled, may be null
+ * @param file the file when the operation was canceled, may be null.
+ * @param depth the depth when the operation was canceled, may be null.
*/
public CancelException(final File file, final int depth) {
this("Operation Cancelled", file, depth);
@@ -284,9 +285,9 @@ public CancelException(final File file, final int depth) {
* an appropriate message and the file and depth when
* cancellation occurred.
*
- * @param message the detail message
- * @param file the file when the operation was cancelled
- * @param depth the depth when the operation was cancelled
+ * @param message the detail message.
+ * @param file the file when the operation was canceled.
+ * @param depth the depth when the operation was canceled.
*/
public CancelException(final String message, final File file, final int depth) {
super(message);
@@ -295,23 +296,24 @@ public CancelException(final String message, final File file, final int depth) {
}
/**
- * Returns the depth when the operation was cancelled.
+ * Returns the depth when the operation was canceled.
*
- * @return the depth when the operation was cancelled
+ * @return the depth when the operation was canceled.
*/
public int getDepth() {
return depth;
}
/**
- * Returns the file when the operation was cancelled.
+ * Returns the file when the operation was canceled.
*
- * @return the file when the operation was cancelled
+ * @return the file when the operation was canceled.
*/
public File getFile() {
return file;
}
}
+
/**
* The file filter to use to filter files and directories.
*/
@@ -338,9 +340,9 @@ protected DirectoryWalker() {
* filtering should occur and all files and directories will be visited.
*
*
- * @param filter the filter to apply, null means visit all files
+ * @param filter the filter to apply, null means visit all files.
* @param depthLimit controls how deep the hierarchy is
- * navigated to (less than 0 means unlimited)
+ * navigated to (less than 0 means unlimited).
*/
protected DirectoryWalker(final FileFilter filter, final int depthLimit) {
this.filter = filter;
@@ -357,10 +359,10 @@ protected DirectoryWalker(final FileFilter filter, final int depthLimit) {
* A {@code null} filter means that no filtering should occur.
*
*
- * @param directoryFilter the filter to apply to directories, null means visit all directories
- * @param fileFilter the filter to apply to files, null means visit all files
+ * @param directoryFilter the filter to apply to directories, null means visit all directories.
+ * @param fileFilter the filter to apply to files, null means visit all files.
* @param depthLimit controls how deep the hierarchy is
- * navigated to (less than 0 means unlimited)
+ * navigated to (less than 0 means unlimited).
*/
protected DirectoryWalker(IOFileFilter directoryFilter, IOFileFilter fileFilter, final int depthLimit) {
if (directoryFilter == null && fileFilter == null) {
@@ -376,7 +378,7 @@ protected DirectoryWalker(IOFileFilter directoryFilter, IOFileFilter fileFilter,
}
/**
- * Checks whether the walk has been cancelled by calling {@link #handleIsCancelled},
+ * Checks whether the walk has been canceled by calling {@link #handleIsCancelled},
* throwing a {@link CancelException} if it has.
*
* Writers of subclasses should not normally call this method as it is called
@@ -385,10 +387,10 @@ protected DirectoryWalker(IOFileFilter directoryFilter, IOFileFilter fileFilter,
* you may wish to check for cancellation by calling this method.
*
*
- * @param file the current file being processed
- * @param depth the current file level (starting directory = 0)
- * @param results the collection of result objects, may be updated
- * @throws IOException if an I/O Error occurs
+ * @param file the current file being processed.
+ * @param depth the current file level (starting directory = 0).
+ * @param results the collection of result objects, may be updated.
+ * @throws IOException if an I/O Error occurs.
*/
protected final void checkIfCancelled(final File file, final int depth, final Collection results) throws
IOException {
@@ -403,11 +405,11 @@ protected final void checkIfCancelled(final File file, final int depth, final Co
* This implementation returns the files unchanged
*
*
- * @param directory the current directory being processed
- * @param depth the current directory level (starting directory = 0)
+ * @param directory the current directory being processed.
+ * @param depth the current directory level (starting directory = 0).
* @param files the files (possibly filtered) in the directory, may be {@code null}
- * @return the filtered list of files
- * @throws IOException if an I/O Error occurs
+ * @return the filtered list of files.
+ * @throws IOException if an I/O Error occurs.
* @since 2.0
*/
@SuppressWarnings("unused") // Possibly thrown from subclasses.
@@ -417,18 +419,18 @@ protected File[] filterDirectoryContents(final File directory, final int depth,
}
/**
- * Overridable callback method invoked when the operation is cancelled.
+ * Overridable callback method invoked when the operation is canceled.
* The file being processed when the cancellation occurred can be
* obtained from the exception.
*
* This implementation just re-throws the {@link CancelException}.
*
*
- * @param startDirectory the directory that the walk started from
- * @param results the collection of result objects, may be updated
+ * @param startDirectory the directory that the walk started from.
+ * @param results the collection of result objects, may be updated.
* @param cancel the exception throw to cancel further processing
* containing details at the point of cancellation.
- * @throws IOException if an I/O Error occurs
+ * @throws IOException if an I/O Error occurs.
*/
protected void handleCancelled(final File startDirectory, final Collection results,
final CancelException cancel) throws IOException {
@@ -447,11 +449,11 @@ protected void handleCancelled(final File startDirectory, final Collection re
* This implementation does nothing and returns true.
*
*
- * @param directory the current directory being processed
- * @param depth the current directory level (starting directory = 0)
- * @param results the collection of result objects, may be updated
- * @return true to process this directory, false to skip this directory
- * @throws IOException if an I/O Error occurs
+ * @param directory the current directory being processed.
+ * @param depth the current directory level (starting directory = 0).
+ * @param results the collection of result objects, may be updated.
+ * @return true to process this directory, false to skip this directory.
+ * @throws IOException if an I/O Error occurs.
*/
@SuppressWarnings("unused") // Possibly thrown from subclasses.
protected boolean handleDirectory(final File directory, final int depth, final Collection results) throws
@@ -466,10 +468,10 @@ protected boolean handleDirectory(final File directory, final int depth, final C
* This implementation does nothing.
*
*
- * @param directory the directory being processed
- * @param depth the current directory level (starting directory = 0)
- * @param results the collection of result objects, may be updated
- * @throws IOException if an I/O Error occurs
+ * @param directory the directory being processed.
+ * @param depth the current directory level (starting directory = 0).
+ * @param results the collection of result objects, may be updated.
+ * @throws IOException if an I/O Error occurs.
*/
@SuppressWarnings("unused") // Possibly thrown from subclasses.
protected void handleDirectoryEnd(final File directory, final int depth, final Collection results) throws
@@ -483,10 +485,10 @@ protected void handleDirectoryEnd(final File directory, final int depth, final C
* This implementation does nothing.
*
*
- * @param directory the current directory being processed
- * @param depth the current directory level (starting directory = 0)
- * @param results the collection of result objects, may be updated
- * @throws IOException if an I/O Error occurs
+ * @param directory the current directory being processed.
+ * @param depth the current directory level (starting directory = 0).
+ * @param results the collection of result objects, may be updated.
+ * @throws IOException if an I/O Error occurs.
*/
@SuppressWarnings("unused") // Possibly thrown from subclasses.
protected void handleDirectoryStart(final File directory, final int depth, final Collection results) throws
@@ -500,8 +502,8 @@ protected void handleDirectoryStart(final File directory, final int depth, final
* This implementation does nothing.
*
*
- * @param results the collection of result objects, may be updated
- * @throws IOException if an I/O Error occurs
+ * @param results the collection of result objects, may be updated.
+ * @throws IOException if an I/O Error occurs.
*/
@SuppressWarnings("unused") // Possibly thrown from subclasses.
protected void handleEnd(final Collection results) throws IOException {
@@ -514,10 +516,10 @@ protected void handleEnd(final Collection results) throws IOException {
* This implementation does nothing.
*
*
- * @param file the current file being processed
- * @param depth the current directory level (starting directory = 0)
- * @param results the collection of result objects, may be updated
- * @throws IOException if an I/O Error occurs
+ * @param file the current file being processed.
+ * @param depth the current directory level (starting directory = 0).
+ * @param results the collection of result objects, may be updated.
+ * @throws IOException if an I/O Error occurs.
*/
@SuppressWarnings("unused") // Possibly thrown from subclasses.
protected void handleFile(final File file, final int depth, final Collection results) throws IOException {
@@ -526,7 +528,7 @@ protected void handleFile(final File file, final int depth, final Collection
/**
* Overridable callback method invoked to determine if the entire walk
- * operation should be immediately cancelled.
+ * operation should be immediately canceled.
*
* This method should be implemented by those subclasses that want to
* provide a public {@code cancel()} method available from another
@@ -534,13 +536,13 @@ protected void handleFile(final File file, final int depth, final Collection
*
*
* public class FooDirectoryWalker extends DirectoryWalker {
- * private volatile boolean cancelled = false;
+ * private volatile boolean canceled = false;
*
* public void cancel() {
- * cancelled = true;
+ * canceled = true;
* }
* private void handleIsCancelled(File file, int depth, Collection results) {
- * return cancelled;
+ * return canceled;
* }
* protected void handleCancelled(File startDirectory,
* Collection results, CancelException cancel) {
@@ -550,23 +552,23 @@ protected void handleFile(final File file, final int depth, final Collection
*
*
* If this method returns true, then the directory walk is immediately
- * cancelled. The next callback method will be {@link #handleCancelled}.
+ * canceled. The next callback method will be {@link #handleCancelled}.
*
*
* This implementation returns false.
*
*
- * @param file the file or directory being processed
- * @param depth the current directory level (starting directory = 0)
- * @param results the collection of result objects, may be updated
- * @return true if the walk has been cancelled
- * @throws IOException if an I/O Error occurs
+ * @param file the file or directory being processed.
+ * @param depth the current directory level (starting directory = 0).
+ * @param results the collection of result objects, may be updated.
+ * @return true if the walk has been canceled.
+ * @throws IOException if an I/O Error occurs.
*/
@SuppressWarnings("unused") // Possibly thrown from subclasses.
protected boolean handleIsCancelled(
final File file, final int depth, final Collection results) throws IOException {
// do nothing - overridable by subclass
- return false; // not cancelled
+ return false; // not canceled
}
/**
@@ -575,10 +577,10 @@ protected boolean handleIsCancelled(
* This implementation does nothing.
*
*
- * @param directory the restricted directory
- * @param depth the current directory level (starting directory = 0)
- * @param results the collection of result objects, may be updated
- * @throws IOException if an I/O Error occurs
+ * @param directory the restricted directory.
+ * @param depth the current directory level (starting directory = 0).
+ * @param results the collection of result objects, may be updated.
+ * @throws IOException if an I/O Error occurs.
*/
@SuppressWarnings("unused") // Possibly thrown from subclasses.
protected void handleRestricted(final File directory, final int depth, final Collection results) throws
@@ -592,9 +594,9 @@ protected void handleRestricted(final File directory, final int depth, final Col
* This implementation does nothing.
*
*
- * @param startDirectory the directory to start from
- * @param results the collection of result objects, may be updated
- * @throws IOException if an I/O Error occurs
+ * @param startDirectory the directory to start from.
+ * @param results the collection of result objects, may be updated.
+ * @throws IOException if an I/O Error occurs.
*/
@SuppressWarnings("unused") // Possibly thrown from subclasses.
protected void handleStart(final File startDirectory, final Collection results) throws IOException {
@@ -613,10 +615,10 @@ protected void handleStart(final File startDirectory, final Collection result
* The event methods have the prefix {@code handle}.
*
*
- * @param startDirectory the directory to start from, not null
- * @param results the collection of result objects, may be updated
- * @throws NullPointerException if the start directory is null
- * @throws IOException if an I/O Error occurs
+ * @param startDirectory the directory to start from, not null.
+ * @param results the collection of result objects, may be updated.
+ * @throws NullPointerException if the start directory is null.
+ * @throws IOException if an I/O Error occurs.
*/
protected final void walk(final File startDirectory, final Collection results) throws IOException {
Objects.requireNonNull(startDirectory, "startDirectory");
@@ -632,10 +634,10 @@ protected final void walk(final File startDirectory, final Collection results
/**
* Main recursive method to examine the directory hierarchy.
*
- * @param directory the directory to examine, not null
- * @param depth the directory level (starting directory = 0)
- * @param results the collection of result objects, may be updated
- * @throws IOException if an I/O Error occurs
+ * @param directory the directory to examine, not null.
+ * @param depth the directory level (starting directory = 0).
+ * @param results the collection of result objects, may be updated.
+ * @throws IOException if an I/O Error occurs.
*/
private void walk(final File directory, final int depth, final Collection results) throws IOException {
checkIfCancelled(directory, depth, results);
diff --git a/src/main/java/org/apache/commons/io/EndianUtils.java b/src/main/java/org/apache/commons/io/EndianUtils.java
index 6b4d58eeba3..cae06b8345e 100644
--- a/src/main/java/org/apache/commons/io/EndianUtils.java
+++ b/src/main/java/org/apache/commons/io/EndianUtils.java
@@ -50,9 +50,10 @@ public class EndianUtils {
/**
* Reads the next byte from the input stream.
- * @param input the stream
- * @return the byte
- * @throws IOException if the end of file is reached
+ *
+ * @param input the stream.
+ * @return the byte.
+ * @throws IOException if the end of file is reached.
*/
private static int read(final InputStream input) throws IOException {
final int value = input.read();
@@ -65,10 +66,10 @@ private static int read(final InputStream input) throws IOException {
/**
* Reads a little-endian {@code double} value from a byte array at a given offset.
*
- * @param data source byte array
- * @param offset starting offset in the byte array
- * @return the value read
- * @throws IllegalArgumentException if the part of the byte array starting at offset does not have at least 8 bytes
+ * @param data source byte array.
+ * @param offset starting offset in the byte array.
+ * @return the value read.
+ * @throws IllegalArgumentException if the part of the byte array starting at offset does not have at least 8 bytes.
*/
public static double readSwappedDouble(final byte[] data, final int offset) {
return Double.longBitsToDouble(readSwappedLong(data, offset));
@@ -77,9 +78,9 @@ public static double readSwappedDouble(final byte[] data, final int offset) {
/**
* Reads a little-endian {@code double} value from an InputStream.
*
- * @param input source InputStream
- * @return the value just read
- * @throws IOException in case of an I/O problem
+ * @param input source InputStream.
+ * @return the value just read.
+ * @throws IOException in case of an I/O problem.
*/
public static double readSwappedDouble(final InputStream input) throws IOException {
return Double.longBitsToDouble(readSwappedLong(input));
@@ -88,10 +89,10 @@ public static double readSwappedDouble(final InputStream input) throws IOExcepti
/**
* Reads a little-endian {@code float} value from a byte array at a given offset.
*
- * @param data source byte array
- * @param offset starting offset in the byte array
- * @return the value read
- * @throws IllegalArgumentException if the part of the byte array starting at offset does not have at least 4 bytes
+ * @param data source byte array.
+ * @param offset starting offset in the byte array.
+ * @return the value read.
+ * @throws IllegalArgumentException if the part of the byte array starting at offset does not have at least 4 bytes.
*/
public static float readSwappedFloat(final byte[] data, final int offset) {
return Float.intBitsToFloat(readSwappedInteger(data, offset));
@@ -100,9 +101,9 @@ public static float readSwappedFloat(final byte[] data, final int offset) {
/**
* Reads a little-endian {@code float} value from an InputStream.
*
- * @param input source InputStream
- * @return the value just read
- * @throws IOException in case of an I/O problem
+ * @param input source InputStream.
+ * @return the value just read.
+ * @throws IOException in case of an I/O problem.
*/
public static float readSwappedFloat(final InputStream input) throws IOException {
return Float.intBitsToFloat(readSwappedInteger(input));
@@ -111,10 +112,10 @@ public static float readSwappedFloat(final InputStream input) throws IOException
/**
* Reads a little-endian {@code int} value from a byte array at a given offset.
*
- * @param data source byte array
- * @param offset starting offset in the byte array
- * @return the value read
- * @throws IllegalArgumentException if the part of the byte array starting at offset does not have at least 4 bytes
+ * @param data source byte array.
+ * @param offset starting offset in the byte array.
+ * @return the value read.
+ * @throws IllegalArgumentException if the part of the byte array starting at offset does not have at least 4 bytes.
*/
public static int readSwappedInteger(final byte[] data, final int offset) {
validateByteArrayOffset(data, offset, Integer.SIZE / Byte.SIZE);
@@ -127,9 +128,9 @@ public static int readSwappedInteger(final byte[] data, final int offset) {
/**
* Reads a little-endian {@code int} value from an InputStream.
*
- * @param input source InputStream
- * @return the value just read
- * @throws IOException in case of an I/O problem
+ * @param input source InputStream.
+ * @return the value just read.
+ * @throws IOException in case of an I/O problem.
*/
public static int readSwappedInteger(final InputStream input) throws IOException {
final int value1 = read(input);
@@ -142,10 +143,10 @@ public static int readSwappedInteger(final InputStream input) throws IOException
/**
* Reads a little-endian {@code long} value from a byte array at a given offset.
*
- * @param data source byte array
- * @param offset starting offset in the byte array
- * @return the value read
- * @throws IllegalArgumentException if the part of the byte array starting at offset does not have at least 8 bytes
+ * @param data source byte array.
+ * @param offset starting offset in the byte array.
+ * @return the value read.
+ * @throws IllegalArgumentException if the part of the byte array starting at offset does not have at least 8 bytes.
*/
public static long readSwappedLong(final byte[] data, final int offset) {
validateByteArrayOffset(data, offset, Long.SIZE / Byte.SIZE);
@@ -157,9 +158,9 @@ public static long readSwappedLong(final byte[] data, final int offset) {
/**
* Reads a little-endian {@code long} value from an InputStream.
*
- * @param input source InputStream
- * @return the value just read
- * @throws IOException in case of an I/O problem
+ * @param input source InputStream.
+ * @return the value just read.
+ * @throws IOException in case of an I/O problem.
*/
public static long readSwappedLong(final InputStream input) throws IOException {
final byte[] bytes = new byte[8];
@@ -172,10 +173,10 @@ public static long readSwappedLong(final InputStream input) throws IOException {
/**
* Reads a little-endian {@code short} value from a byte array at a given offset.
*
- * @param data source byte array
- * @param offset starting offset in the byte array
- * @return the value read
- * @throws IllegalArgumentException if the part of the byte array starting at offset does not have at least 2 bytes
+ * @param data source byte array.
+ * @param offset starting offset in the byte array.
+ * @return the value read.
+ * @throws IllegalArgumentException if the part of the byte array starting at offset does not have at least 2 bytes.
*/
public static short readSwappedShort(final byte[] data, final int offset) {
validateByteArrayOffset(data, offset, Short.SIZE / Byte.SIZE);
@@ -185,9 +186,9 @@ public static short readSwappedShort(final byte[] data, final int offset) {
/**
* Reads a little-endian {@code short} value from an InputStream.
*
- * @param input source InputStream
- * @return the value just read
- * @throws IOException in case of an I/O problem
+ * @param input source InputStream.
+ * @return the value just read.
+ * @throws IOException in case of an I/O problem.
*/
public static short readSwappedShort(final InputStream input) throws IOException {
return (short) (((read(input) & 0xff) << 0) + ((read(input) & 0xff) << 8));
@@ -197,10 +198,10 @@ public static short readSwappedShort(final InputStream input) throws IOException
* Reads a little-endian unsigned integer (32-bit) value from a byte array at a given
* offset.
*
- * @param data source byte array
- * @param offset starting offset in the byte array
- * @return the value read
- * @throws IllegalArgumentException if the part of the byte array starting at offset does not have at least 4 bytes
+ * @param data source byte array.
+ * @param offset starting offset in the byte array.
+ * @return the value read.
+ * @throws IllegalArgumentException if the part of the byte array starting at offset does not have at least 4 bytes.
*/
public static long readSwappedUnsignedInteger(final byte[] data, final int offset) {
validateByteArrayOffset(data, offset, Integer.SIZE / Byte.SIZE);
@@ -214,9 +215,9 @@ public static long readSwappedUnsignedInteger(final byte[] data, final int offse
/**
* Reads a little-endian unsigned integer (32-bit) from an InputStream.
*
- * @param input source InputStream
- * @return the value just read
- * @throws IOException in case of an I/O problem
+ * @param input source InputStream.
+ * @return the value just read.
+ * @throws IOException in case of an I/O problem.
*/
public static long readSwappedUnsignedInteger(final InputStream input) throws IOException {
final int value1 = read(input);
@@ -232,10 +233,10 @@ public static long readSwappedUnsignedInteger(final InputStream input) throws IO
* Reads an unsigned short (16-bit) value from a byte array in little-endian order at a given
* offset.
*
- * @param data source byte array
- * @param offset starting offset in the byte array
- * @return the value read
- * @throws IllegalArgumentException if the part of the byte array starting at offset does not have at least 2 bytes
+ * @param data source byte array.
+ * @param offset starting offset in the byte array.
+ * @return the value read.
+ * @throws IllegalArgumentException if the part of the byte array starting at offset does not have at least 2 bytes.
*/
public static int readSwappedUnsignedShort(final byte[] data, final int offset) {
validateByteArrayOffset(data, offset, Short.SIZE / Byte.SIZE);
@@ -245,9 +246,9 @@ public static int readSwappedUnsignedShort(final byte[] data, final int offset)
/**
* Reads an unsigned short (16-bit) from an InputStream in little-endian order.
*
- * @param input source InputStream
- * @return the value just read
- * @throws IOException in case of an I/O problem
+ * @param input source InputStream.
+ * @return the value just read.
+ * @throws IOException in case of an I/O problem.
*/
public static int readSwappedUnsignedShort(final InputStream input) throws IOException {
final int value1 = read(input);
@@ -263,8 +264,8 @@ public static int readSwappedUnsignedShort(final InputStream input) throws IOExc
* This can be useful if you have a number that was read from the
* underlying source in the wrong endianness.
*
- * @param value value to convert
- * @return the converted value
+ * @param value value to convert.
+ * @return the converted value.
*/
public static double swapDouble(final double value) {
return Double.longBitsToDouble(swapLong(Double.doubleToLongBits(value)));
@@ -273,8 +274,8 @@ public static double swapDouble(final double value) {
/**
* Converts a {@code float} value from big-endian to little-endian and vice versa.
*
- * @param value value to convert
- * @return the converted value
+ * @param value value to convert.
+ * @return the converted value.
*/
public static float swapFloat(final float value) {
return Float.intBitsToFloat(swapInteger(Float.floatToIntBits(value)));
@@ -283,8 +284,8 @@ public static float swapFloat(final float value) {
/**
* Converts an {@code int} value from big-endian to little-endian and vice versa.
*
- * @param value value to convert
- * @return the converted value
+ * @param value value to convert.
+ * @return the converted value.
*/
public static int swapInteger(final int value) {
return
@@ -297,8 +298,8 @@ public static int swapInteger(final int value) {
/**
* Converts a {@code long} value from big-endian to little-endian and vice versa.
*
- * @param value value to convert
- * @return the converted value
+ * @param value value to convert.
+ * @return the converted value.
*/
public static long swapLong(final long value) {
return
@@ -315,8 +316,8 @@ public static long swapLong(final long value) {
/**
* Converts a {@code short} value from big-endian to little-endian and vice versa.
*
- * @param value value to convert
- * @return the converted value
+ * @param value value to convert.
+ * @return the converted value.
*/
public static short swapShort(final short value) {
return (short) (((value >> 0 & 0xff) << 8) +
@@ -326,10 +327,10 @@ public static short swapShort(final short value) {
/**
* Validates if the provided byte array has enough data.
*
- * @param data the input byte array
- * @param offset the input offset
- * @param byteNeeded the needed number of bytes
- * @throws IllegalArgumentException if the byte array does not have enough data
+ * @param data the input byte array.
+ * @param offset the input offset.
+ * @param byteNeeded the needed number of bytes.
+ * @throws IllegalArgumentException if the byte array does not have enough data.
*/
private static void validateByteArrayOffset(final byte[] data, final int offset, final int byteNeeded) {
if (data.length < offset + byteNeeded) {
@@ -340,10 +341,10 @@ private static void validateByteArrayOffset(final byte[] data, final int offset,
/**
* Writes the 8 bytes of a {@code double} to a byte array at a given offset in little-endian order.
*
- * @param data target byte array
- * @param offset starting offset in the byte array
- * @param value value to write
- * @throws IllegalArgumentException if the part of the byte array starting at offset does not have at least 8 bytes
+ * @param data target byte array.
+ * @param offset starting offset in the byte array.
+ * @param value value to write.
+ * @throws IllegalArgumentException if the part of the byte array starting at offset does not have at least 8 bytes.
*/
public static void writeSwappedDouble(final byte[] data, final int offset, final double value) {
writeSwappedLong(data, offset, Double.doubleToLongBits(value));
@@ -352,9 +353,9 @@ public static void writeSwappedDouble(final byte[] data, final int offset, final
/**
* Writes the 8 bytes of a {@code double} to an output stream in little-endian order.
*
- * @param output target OutputStream
- * @param value value to write
- * @throws IOException in case of an I/O problem
+ * @param output target OutputStream.
+ * @param value value to write.
+ * @throws IOException in case of an I/O problem.
*/
public static void writeSwappedDouble(final OutputStream output, final double value) throws IOException {
writeSwappedLong(output, Double.doubleToLongBits(value));
@@ -363,10 +364,10 @@ public static void writeSwappedDouble(final OutputStream output, final double va
/**
* Writes the 4 bytes of a {@code float} to a byte array at a given offset in little-endian order.
*
- * @param data target byte array
- * @param offset starting offset in the byte array
- * @param value value to write
- * @throws IllegalArgumentException if the part of the byte array starting at offset does not have at least 4 bytes
+ * @param data target byte array.
+ * @param offset starting offset in the byte array.
+ * @param value value to write.
+ * @throws IllegalArgumentException if the part of the byte array starting at offset does not have at least 4 bytes.
*/
public static void writeSwappedFloat(final byte[] data, final int offset, final float value) {
writeSwappedInteger(data, offset, Float.floatToIntBits(value));
@@ -375,9 +376,9 @@ public static void writeSwappedFloat(final byte[] data, final int offset, final
/**
* Writes the 4 bytes of a {@code float} to an output stream in little-endian order.
*
- * @param output target OutputStream
- * @param value value to write
- * @throws IOException in case of an I/O problem
+ * @param output target OutputStream.
+ * @param value value to write.
+ * @throws IOException in case of an I/O problem.
*/
public static void writeSwappedFloat(final OutputStream output, final float value) throws IOException {
writeSwappedInteger(output, Float.floatToIntBits(value));
@@ -386,10 +387,10 @@ public static void writeSwappedFloat(final OutputStream output, final float valu
/**
* Writes the 4 bytes of an {@code int} to a byte array at a given offset in little-endian order.
*
- * @param data target byte array
- * @param offset starting offset in the byte array
- * @param value value to write
- * @throws IllegalArgumentException if the part of the byte array starting at offset does not have at least 4 bytes
+ * @param data target byte array.
+ * @param offset starting offset in the byte array.
+ * @param value value to write.
+ * @throws IllegalArgumentException if the part of the byte array starting at offset does not have at least 4 bytes.
*/
public static void writeSwappedInteger(final byte[] data, final int offset, final int value) {
validateByteArrayOffset(data, offset, Integer.SIZE / Byte.SIZE);
@@ -402,9 +403,9 @@ public static void writeSwappedInteger(final byte[] data, final int offset, fina
/**
* Writes the 4 bytes of an {@code int} to an output stream in little-endian order.
*
- * @param output target OutputStream
- * @param value value to write
- * @throws IOException in case of an I/O problem
+ * @param output target OutputStream.
+ * @param value value to write.
+ * @throws IOException in case of an I/O problem.
*/
public static void writeSwappedInteger(final OutputStream output, final int value) throws IOException {
output.write((byte) (value >> 0 & 0xff));
@@ -416,10 +417,10 @@ public static void writeSwappedInteger(final OutputStream output, final int valu
/**
* Writes the 8 bytes of a {@code long} to a byte array at a given offset in little-endian order.
*
- * @param data target byte array
- * @param offset starting offset in the byte array
- * @param value value to write
- * @throws IllegalArgumentException if the part of the byte array starting at offset does not have at least 8 bytes
+ * @param data target byte array.
+ * @param offset starting offset in the byte array.
+ * @param value value to write.
+ * @throws IllegalArgumentException if the part of the byte array starting at offset does not have at least 8 bytes.
*/
public static void writeSwappedLong(final byte[] data, final int offset, final long value) {
validateByteArrayOffset(data, offset, Long.SIZE / Byte.SIZE);
@@ -436,9 +437,9 @@ public static void writeSwappedLong(final byte[] data, final int offset, final l
/**
* Writes the 8 bytes of a {@code long} to an output stream in little-endian order.
*
- * @param output target OutputStream
- * @param value value to write
- * @throws IOException in case of an I/O problem
+ * @param output target OutputStream.
+ * @param value value to write.
+ * @throws IOException in case of an I/O problem.
*/
public static void writeSwappedLong(final OutputStream output, final long value) throws IOException {
output.write((byte) (value >> 0 & 0xff));
@@ -454,10 +455,10 @@ public static void writeSwappedLong(final OutputStream output, final long value)
/**
* Writes the 2 bytes of a {@code short} to a byte array at a given offset in little-endian order.
*
- * @param data target byte array
- * @param offset starting offset in the byte array
- * @param value value to write
- * @throws IllegalArgumentException if the part of the byte array starting at offset does not have at least 2 bytes
+ * @param data target byte array.
+ * @param offset starting offset in the byte array.
+ * @param value value to write.
+ * @throws IllegalArgumentException if the part of the byte array starting at offset does not have at least 2 bytes.
*/
public static void writeSwappedShort(final byte[] data, final int offset, final short value) {
validateByteArrayOffset(data, offset, Short.SIZE / Byte.SIZE);
@@ -468,9 +469,9 @@ public static void writeSwappedShort(final byte[] data, final int offset, final
/**
* Writes the 2 bytes of a {@code short} to an output stream using little-endian encoding.
*
- * @param output target OutputStream
- * @param value value to write
- * @throws IOException in case of an I/O problem
+ * @param output target OutputStream.
+ * @param value value to write.
+ * @throws IOException in case of an I/O problem.
*/
public static void writeSwappedShort(final OutputStream output, final short value) throws IOException {
output.write((byte) (value >> 0 & 0xff));
diff --git a/src/main/java/org/apache/commons/io/FileCleaner.java b/src/main/java/org/apache/commons/io/FileCleaner.java
index 5ffdd7db219..df9bc924f49 100644
--- a/src/main/java/org/apache/commons/io/FileCleaner.java
+++ b/src/main/java/org/apache/commons/io/FileCleaner.java
@@ -53,7 +53,7 @@ public class FileCleaner {
* loader it was started from terminates. This can constitute a memory leak.
*
* For example, suppose that you have developed a web application, which
- * contains the commons-io jar file in your WEB-INF/lib directory. In other
+ * contains the Commons IO jar file in your WEB-INF/lib directory. In other
* words, the FileCleaner class is loaded through the class loader of your
* web application. If the web application is terminated, but the servlet
* container is still running, then the file cleaner thread will still exist,
@@ -63,6 +63,7 @@ public class FileCleaner {
* in the resource cleanup code, such as
* {@code javax.servlet.ServletContextListener.contextDestroyed(javax.servlet.ServletContextEvent)}.
* One called, no new objects can be tracked by the file cleaner.
+ *
* @deprecated Use {@link FileCleaningTracker#exitWhenFinished()}.
*/
@Deprecated
@@ -76,7 +77,7 @@ public static synchronized void exitWhenFinished() {
* {@link FileCleaningTracker} class while maintain compatibility with the
* deprecated {@link FileCleaner}.
*
- * @return the singleton instance
+ * @return the singleton instance.
*/
public static FileCleaningTracker getInstance() {
return INSTANCE;
@@ -86,7 +87,7 @@ public static FileCleaningTracker getInstance() {
* Gets the number of files currently being tracked, and therefore
* awaiting deletion.
*
- * @return the number of files being tracked
+ * @return the number of files being tracked.
* @deprecated Use {@link FileCleaningTracker#getTrackCount()}.
*/
@Deprecated
@@ -99,9 +100,9 @@ public static int getTrackCount() {
* when the marker instance is garbage collected.
* The {@link FileDeleteStrategy#NORMAL normal} deletion strategy will be used.
*
- * @param file the file to be tracked, not null
- * @param marker the marker object used to track the file, not null
- * @throws NullPointerException if the file is null
+ * @param file the file to be tracked, not null.
+ * @param marker the marker object used to track the file, not null.
+ * @throws NullPointerException if the file is null.
* @deprecated Use {@link FileCleaningTracker#track(File, Object)}.
*/
@Deprecated
@@ -114,10 +115,10 @@ public static void track(final File file, final Object marker) {
* when the marker instance is garbage collected.
* The specified deletion strategy is used.
*
- * @param file the file to be tracked, not null
- * @param marker the marker object used to track the file, not null
- * @param deleteStrategy the strategy to delete the file, null means normal
- * @throws NullPointerException if the file is null
+ * @param file the file to be tracked, not null.
+ * @param marker the marker object used to track the file, not null.
+ * @param deleteStrategy the strategy to delete the file, null means normal.
+ * @throws NullPointerException if the file is null.
* @deprecated Use {@link FileCleaningTracker#track(File, Object, FileDeleteStrategy)}.
*/
@Deprecated
@@ -130,9 +131,9 @@ public static void track(final File file, final Object marker, final FileDeleteS
* when the marker instance is garbage collected.
* The {@link FileDeleteStrategy#NORMAL normal} deletion strategy will be used.
*
- * @param path the full path to the file to be tracked, not null
- * @param marker the marker object used to track the file, not null
- * @throws NullPointerException if the path is null
+ * @param path the full path to the file to be tracked, not null.
+ * @param marker the marker object used to track the file, not null.
+ * @throws NullPointerException if the path is null.
* @deprecated Use {@link FileCleaningTracker#track(String, Object)}.
*/
@Deprecated
@@ -145,10 +146,10 @@ public static void track(final String path, final Object marker) {
* when the marker instance is garbage collected.
* The specified deletion strategy is used.
*
- * @param path the full path to the file to be tracked, not null
- * @param marker the marker object used to track the file, not null
- * @param deleteStrategy the strategy to delete the file, null means normal
- * @throws NullPointerException if the path is null
+ * @param path the full path to the file to be tracked, not null.
+ * @param marker the marker object used to track the file, not null.
+ * @param deleteStrategy the strategy to delete the file, null means normal.
+ * @throws NullPointerException if the path is null.
* @deprecated Use {@link FileCleaningTracker#track(String, Object, FileDeleteStrategy)}.
*/
@Deprecated
diff --git a/src/main/java/org/apache/commons/io/FileCleaningTracker.java b/src/main/java/org/apache/commons/io/FileCleaningTracker.java
index 98edebc518e..be2746b66be 100644
--- a/src/main/java/org/apache/commons/io/FileCleaningTracker.java
+++ b/src/main/java/org/apache/commons/io/FileCleaningTracker.java
@@ -21,14 +21,14 @@
import java.lang.ref.ReferenceQueue;
import java.nio.file.Path;
import java.util.ArrayList;
-import java.util.Collection;
import java.util.Collections;
import java.util.HashSet;
import java.util.List;
import java.util.Objects;
+import java.util.Set;
/**
- * Keeps track of files awaiting deletion, and deletes them when an associated
+ * Tracks files awaiting deletion, and deletes them when an associated
* marker object is reclaimed by the garbage collector.
*
* This utility creates a background thread to handle file deletion.
@@ -51,9 +51,10 @@ public class FileCleaningTracker {
* The reaper thread.
*/
private final class Reaper extends Thread {
+
/** Constructs a new Reaper */
Reaper() {
- super("File Reaper");
+ super("commons-io-FileCleaningTracker-Reaper");
setPriority(MAX_PRIORITY);
setDaemon(true);
}
@@ -65,16 +66,18 @@ private final class Reaper extends Thread {
@Override
public void run() {
// thread exits when exitWhenFinished is true and there are no more tracked objects
- while (!exitWhenFinished || !trackers.isEmpty()) {
+ while (!(exitWhenFinished && trackers.isEmpty())) {
try {
// Wait for a tracker to remove.
- final Tracker tracker = (Tracker) q.remove(); // cannot return null
+ final Tracker tracker = (Tracker) refQueue.remove(); // cannot return null
trackers.remove(tracker);
if (!tracker.delete()) {
deleteFailures.add(tracker.getPath());
}
tracker.clear();
} catch (final InterruptedException e) {
+ // interrupted removing from the queue.
+ interrupt();
continue;
}
}
@@ -99,15 +102,14 @@ private static final class Tracker extends PhantomReference
*
* For example, suppose that you have developed a web application, which
- * contains the commons-io jar file in your WEB-INF/lib directory. In other
+ * contains the Commons IO JAR file in your WEB-INF/lib directory. In other
* words, the FileCleaner class is loaded through the class loader of your
* web application. If the web application is terminated, but the servlet
* container is still running, then the file cleaner thread will still exist,
* posing a memory leak.
+ *
*
* This method allows the thread to be terminated. Simply call this method
* in the resource cleanup code, such as
* {@code javax.servlet.ServletContextListener.contextDestroyed(javax.servlet.ServletContextEvent)}.
* Once called, no new objects can be tracked by the file cleaner.
+ *
*/
public synchronized void exitWhenFinished() {
- // synchronized block protects reaper
+ // synchronized method guards reaper
exitWhenFinished = true;
if (reaper != null) {
synchronized (reaper) {
@@ -218,7 +223,7 @@ public synchronized void exitWhenFinished() {
/**
* Gets a copy of the file paths that failed to delete.
*
- * @return a copy of the file paths that failed to delete
+ * @return a copy of the file paths that failed to delete.
* @since 2.0
*/
public List getDeleteFailures() {
@@ -229,7 +234,7 @@ public List getDeleteFailures() {
* Gets the number of files currently being tracked, and therefore
* awaiting deletion.
*
- * @return the number of files being tracked
+ * @return the number of files being tracked.
*/
public int getTrackCount() {
return trackers.size();
@@ -240,9 +245,9 @@ public int getTrackCount() {
* when the marker instance is garbage collected.
* The {@link FileDeleteStrategy#NORMAL normal} deletion strategy will be used.
*
- * @param file the file to be tracked, not null
- * @param marker the marker object used to track the file, not null
- * @throws NullPointerException if the file is null
+ * @param file the file to be tracked, not null.
+ * @param marker the marker object used to track the file, not null.
+ * @throws NullPointerException if the file is null.
*/
public void track(final File file, final Object marker) {
track(file, marker, null);
@@ -253,10 +258,10 @@ public void track(final File file, final Object marker) {
* when the marker instance is garbage collected.
* The specified deletion strategy is used.
*
- * @param file the file to be tracked, not null
- * @param marker the marker object used to track the file, not null
- * @param deleteStrategy the strategy to delete the file, null means normal
- * @throws NullPointerException if the file is null
+ * @param file the file to be tracked, not null.
+ * @param marker the marker object used to track the file, not null.
+ * @param deleteStrategy the strategy to delete the file, null means normal.
+ * @throws NullPointerException if the file is null.
*/
public void track(final File file, final Object marker, final FileDeleteStrategy deleteStrategy) {
Objects.requireNonNull(file, "file");
@@ -268,9 +273,9 @@ public void track(final File file, final Object marker, final FileDeleteStrategy
* when the marker instance is garbage collected.
* The {@link FileDeleteStrategy#NORMAL normal} deletion strategy will be used.
*
- * @param file the file to be tracked, not null
- * @param marker the marker object used to track the file, not null
- * @throws NullPointerException if the file is null
+ * @param file the file to be tracked, not null.
+ * @param marker the marker object used to track the file, not null.
+ * @throws NullPointerException if the file is null.
* @since 2.14.0
*/
public void track(final Path file, final Object marker) {
@@ -282,10 +287,10 @@ public void track(final Path file, final Object marker) {
* when the marker instance is garbage collected.
* The specified deletion strategy is used.
*
- * @param file the file to be tracked, not null
- * @param marker the marker object used to track the file, not null
- * @param deleteStrategy the strategy to delete the file, null means normal
- * @throws NullPointerException if the file is null
+ * @param file the file to be tracked, not null.
+ * @param marker the marker object used to track the file, not null.
+ * @param deleteStrategy the strategy to delete the file, null means normal.
+ * @throws NullPointerException if the file is null.
* @since 2.14.0
*/
public void track(final Path file, final Object marker, final FileDeleteStrategy deleteStrategy) {
@@ -298,9 +303,9 @@ public void track(final Path file, final Object marker, final FileDeleteStrategy
* when the marker instance is garbage collected.
* The {@link FileDeleteStrategy#NORMAL normal} deletion strategy will be used.
*
- * @param path the full path to the file to be tracked, not null
- * @param marker the marker object used to track the file, not null
- * @throws NullPointerException if the path is null
+ * @param path the full path to the file to be tracked, not null.
+ * @param marker the marker object used to track the file, not null.
+ * @throws NullPointerException if the path is null.
*/
public void track(final String path, final Object marker) {
track(path, marker, null);
@@ -311,13 +316,12 @@ public void track(final String path, final Object marker) {
* when the marker instance is garbage collected.
* The specified deletion strategy is used.
*
- * @param path the full path to the file to be tracked, not null
- * @param marker the marker object used to track the file, not null
- * @param deleteStrategy the strategy to delete the file, null means normal
- * @throws NullPointerException if the path is null
+ * @param path the full path to the file to be tracked, not null.
+ * @param marker the marker object used to track the file, not null.
+ * @param deleteStrategy the strategy to delete the file, null means normal.
+ * @throws NullPointerException Thrown if the path is null.
*/
public void track(final String path, final Object marker, final FileDeleteStrategy deleteStrategy) {
- Objects.requireNonNull(path, "path");
addTracker(path, marker, deleteStrategy);
}
diff --git a/src/main/java/org/apache/commons/io/FileDeleteStrategy.java b/src/main/java/org/apache/commons/io/FileDeleteStrategy.java
index 62cf28c1631..a73ea719a75 100644
--- a/src/main/java/org/apache/commons/io/FileDeleteStrategy.java
+++ b/src/main/java/org/apache/commons/io/FileDeleteStrategy.java
@@ -37,7 +37,7 @@ public class FileDeleteStrategy {
/**
* Force file deletion strategy.
*/
- static class ForceFileDeleteStrategy extends FileDeleteStrategy {
+ static final class ForceFileDeleteStrategy extends FileDeleteStrategy {
/** Default Constructor */
ForceFileDeleteStrategy() {
@@ -51,10 +51,10 @@ static class ForceFileDeleteStrategy extends FileDeleteStrategy {
* if the file exists.
*
*
- * @param fileToDelete the file to delete, not null
+ * @param fileToDelete the file to delete, not null.
* @return Always returns {@code true}
- * @throws NullPointerException if the file is null
- * @throws IOException if an error occurs during file deletion
+ * @throws NullPointerException if the file is null.
+ * @throws IOException if an error occurs during file deletion.
*/
@Override
protected boolean doDelete(final File fileToDelete) throws IOException {
@@ -81,7 +81,7 @@ protected boolean doDelete(final File fileToDelete) throws IOException {
/**
* Restricted constructor.
*
- * @param name the name by which the strategy is known
+ * @param name the name by which the strategy is known.
*/
protected FileDeleteStrategy(final String name) {
this.name = name;
@@ -94,9 +94,9 @@ protected FileDeleteStrategy(final String name) {
* Subclass writers should override {@link #doDelete(File)}, not this method.
*
*
- * @param fileToDelete the file to delete, not null
- * @throws NullPointerException if the file is null
- * @throws IOException if an error occurs during file deletion
+ * @param fileToDelete the file to delete, not null.
+ * @throws NullPointerException if the file is null.
+ * @throws IOException if an error occurs during file deletion.
*/
public void delete(final File fileToDelete) throws IOException {
if (fileToDelete.exists() && !doDelete(fileToDelete)) {
@@ -112,8 +112,8 @@ public void delete(final File fileToDelete) throws IOException {
* Subclass writers should override {@link #doDelete(File)}, not this method.
*
*
- * @param fileToDelete the file to delete, null returns true
- * @return true if the file was deleted, or there was no such file
+ * @param fileToDelete the file to delete, null returns true.
+ * @return true if the file was deleted, or there was no such file.
*/
public boolean deleteQuietly(final File fileToDelete) {
if (fileToDelete == null || !fileToDelete.exists()) {
@@ -139,10 +139,10 @@ public boolean deleteQuietly(final File fileToDelete) {
* This implementation uses {@link FileUtils#delete(File)}.
*
*
- * @param file the file to delete, exists, not null
- * @return true if the file was deleted
- * @throws NullPointerException if the file is null
- * @throws IOException if an error occurs during file deletion
+ * @param file the file to delete, exists, not null.
+ * @return true if the file was deleted.
+ * @throws NullPointerException if the file is null.
+ * @throws IOException if an error occurs during file deletion.
*/
protected boolean doDelete(final File file) throws IOException {
FileUtils.delete(file);
@@ -152,7 +152,7 @@ protected boolean doDelete(final File file) throws IOException {
/**
* Gets a string describing the delete strategy.
*
- * @return a string describing the delete strategy
+ * @return a string describing the delete strategy.
*/
@Override
public String toString() {
diff --git a/src/main/java/org/apache/commons/io/FileExistsException.java b/src/main/java/org/apache/commons/io/FileExistsException.java
index 1f733cf11ae..2028ddc5ebd 100644
--- a/src/main/java/org/apache/commons/io/FileExistsException.java
+++ b/src/main/java/org/apache/commons/io/FileExistsException.java
@@ -40,7 +40,7 @@ public FileExistsException() {
/**
* Constructs an instance with the specified file.
*
- * @param file The file that exists
+ * @param file The file that exists.
*/
public FileExistsException(final File file) {
super("File " + file + " exists");
@@ -49,7 +49,7 @@ public FileExistsException(final File file) {
/**
* Constructs an instance with the specified message.
*
- * @param message The error message
+ * @param message The error message.
*/
public FileExistsException(final String message) {
super(message);
diff --git a/src/main/java/org/apache/commons/io/FileSystem.java b/src/main/java/org/apache/commons/io/FileSystem.java
index 4169e1a53b1..8fd3299d853 100644
--- a/src/main/java/org/apache/commons/io/FileSystem.java
+++ b/src/main/java/org/apache/commons/io/FileSystem.java
@@ -118,6 +118,7 @@ public enum FileSystem {
* Implementations measure length and can truncate to a specified limit.
*/
enum NameLengthStrategy {
+
/** Length measured as encoded bytes. */
BYTES {
@Override
@@ -266,7 +267,7 @@ final boolean isWithinLimit(final CharSequence value, final int limit, final Cha
/**
* Gets the current file system.
*
- * @return the current file system
+ * @return the current file system.
*/
private static FileSystem current() {
if (IS_OS_LINUX) {
@@ -284,7 +285,7 @@ private static FileSystem current() {
/**
* Gets the current file system.
*
- * @return the current file system
+ * @return the current file system.
*/
public static FileSystem getCurrent() {
return CURRENT;
@@ -294,8 +295,8 @@ public static FileSystem getCurrent() {
* Decides if the operating system matches.
*
* @param osNamePrefix
- * the prefix for the os name
- * @return true if matches, or false if not or can't determine
+ * the prefix for the operating system name.
+ * @return true if matches, or false if not or can't determine.
*/
private static boolean getOsMatchesName(final String osNamePrefix) {
return isOsNameMatch(getSystemProperty("os.name"), osNamePrefix);
@@ -309,8 +310,8 @@ private static boolean getOsMatchesName(final String osNamePrefix) {
*
*
* @param property
- * the system property name
- * @return the system property value or {@code null} if a security problem occurs
+ * the system property name.
+ * @return the system property value or {@code null} if a security problem occurs.
*/
private static String getSystemProperty(final String property) {
try {
@@ -345,10 +346,10 @@ private static int indexOfFirstDot(final CharSequence cs) {
*
*
* @param osName
- * the actual OS name
+ * the actual OS name.
* @param osNamePrefix
- * the prefix for the expected OS name
- * @return true if matches, or false if not or can't determine
+ * the prefix for the expected OS name.
+ * @return true if matches, or false if not or can't determine.
*/
private static boolean isOsNameMatch(final String osName, final String osNamePrefix) {
if (osName == null) {
diff --git a/src/main/java/org/apache/commons/io/FileSystemUtils.java b/src/main/java/org/apache/commons/io/FileSystemUtils.java
index 4c0af0d3671..7455dca8d09 100644
--- a/src/main/java/org/apache/commons/io/FileSystemUtils.java
+++ b/src/main/java/org/apache/commons/io/FileSystemUtils.java
@@ -53,12 +53,12 @@ public class FileSystemUtils {
* FileSystemUtils.freeSpace("/volume"); // *nix
*
*
- * @param path the path to get free space for, not null, not empty on Unix
- * @return the amount of free drive space on the drive or volume
+ * @param path the path to get free space for, not null, not empty on Unix.
+ * @return the amount of free drive space on the drive or volume.
* @throws IOException if an I/O error occurs.
* @throws IllegalArgumentException if the path is invalid.
* @since 1.1, enhanced OS support in 1.2 and 1.3
- * @deprecated Use freeSpaceKb(String) Deprecated from 1.3, may be removed in 2.0
+ * @deprecated Use freeSpaceKb(String) Deprecated from 1.3, may be removed in 2.0.
*/
@Deprecated
public static long freeSpace(final String path) throws IOException {
@@ -75,7 +75,7 @@ public static long freeSpace(final String path) throws IOException {
* freeSpaceKb(FileUtils.current().getAbsolutePath())
*
*
- * @return the amount of free drive space on the drive or volume in kilobytes
+ * @return the amount of free drive space on the drive or volume in kilobytes.
* @throws IOException if an I/O error occurs.
* @throws IllegalArgumentException if the path is invalid.
* @since 2.0
@@ -97,7 +97,7 @@ public static long freeSpaceKb() throws IOException {
*
*
* @param timeout ignored.
- * @return the amount of free drive space on the drive or volume in kilobytes
+ * @return the amount of free drive space on the drive or volume in kilobytes.
* @throws IOException if an I/O error occurs.
* @throws IllegalArgumentException if the path is invalid.
* @since 2.0
@@ -116,8 +116,8 @@ public static long freeSpaceKb(final long timeout) throws IOException {
* FileSystemUtils.freeSpaceKb("/volume"); // *nix
*
*
- * @param path the path to get free space for, not null, not empty on Unix
- * @return the amount of free drive space on the drive or volume in kilobytes
+ * @param path the path to get free space for, not null, not empty on Unix.
+ * @return the amount of free drive space on the drive or volume in kilobytes.
* @throws IOException if an I/O error occurs.
* @throws IllegalArgumentException if the path is invalid.
* @since 1.2, enhanced OS support in 1.3
@@ -136,9 +136,9 @@ public static long freeSpaceKb(final String path) throws IOException {
* FileSystemUtils.freeSpaceKb("/volume"); // *nix
*
*
- * @param path the path to get free space for, not null, not empty on Unix
+ * @param path the path to get free space for, not null, not empty on Unix.
* @param timeout ignored.
- * @return the amount of free drive space on the drive or volume in kilobytes
+ * @return the amount of free drive space on the drive or volume in kilobytes.
* @throws IOException if an I/O error occurs.
* @throws IllegalArgumentException if the path is invalid.
* @since 2.0
@@ -157,8 +157,8 @@ public static long freeSpaceKb(final String path, final long timeout) throws IOE
* FileSystemUtils.freeSpace("/volume"); // *nix
*
*
- * @param pathStr the path to get free space for, not null, not empty on Unix
- * @return the amount of free drive space on the drive or volume
+ * @param pathStr the path to get free space for, not null, not empty on Unix.
+ * @return the amount of free drive space on the drive or volume.
* @throws IOException if an I/O error occurs.
* @throws IllegalArgumentException if the path is invalid.
*/
diff --git a/src/main/java/org/apache/commons/io/FileUtils.java b/src/main/java/org/apache/commons/io/FileUtils.java
index 203fe84bfc5..c7c0d1ad19c 100644
--- a/src/main/java/org/apache/commons/io/FileUtils.java
+++ b/src/main/java/org/apache/commons/io/FileUtils.java
@@ -93,16 +93,16 @@
* Facilities are provided in the following areas:
*
* * Note that a specific charset should be specified whenever possible. Relying on the platform default means that the @@ -112,7 +112,7 @@ * {@link SecurityException} are not documented in the Javadoc. *
*- * Provenance: Excalibur, Alexandria, Commons-Utils + * Provenance: Excalibur, Alexandria, Commons-Utils. *
*/ public class FileUtils { @@ -230,8 +230,8 @@ public class FileUtils { * Similarly for the 1MB and 1KB boundaries. * * - * @param size the number of bytes - * @return a human-readable display value (includes units - QB, RB, YB, ZB, EB, PB, TB, GB, MB, KB or bytes) + * @param size the number of bytes. + * @return a human-readable display value (includes units - QB, RB, YB, ZB, EB, PB, TB, GB, MB, KB or bytes). * @throws NullPointerException if the given {@link BigInteger} is {@code null}. * @see IO-226 - should the rounding be changed? * @since 2.4 @@ -276,8 +276,8 @@ public static String byteCountToDisplaySize(final BigInteger size) { * Similarly for the 1MB and 1KB boundaries. * * - * @param size the number of bytes - * @return a human-readable display value (includes units - EB, PB, TB, GB, MB, KB or bytes) + * @param size the number of bytes. + * @return a human-readable display value (includes units - EB, PB, TB, GB, MB, KB or bytes). * @see IO-226 - should the rounding be changed? */ // See https://issues.apache.org/jira/browse/IO-226 - should the rounding be changed? @@ -295,8 +295,8 @@ public static String byteCountToDisplaySize(final long size) { * Similarly for the 1MB and 1KB boundaries. * * - * @param size the number of bytes - * @return a human-readable display value (includes units - EB, PB, TB, GB, MB, KB or bytes) + * @param size the number of bytes. + * @return a human-readable display value (includes units - EB, PB, TB, GB, MB, KB or bytes). * @see IO-226 - should the rounding be changed? * @since 2.12.0 */ @@ -357,11 +357,11 @@ private static File checkIsFile(final File file, final String name) { * * @param file the file to checksum, must not be {@code null} * @param checksum the checksum object to be used, must not be {@code null} - * @return the checksum specified, updated with the content of the file + * @return the checksum specified, updated with the content of the file. * @throws NullPointerException if the given {@link File} is {@code null}. * @throws NullPointerException if the given {@link Checksum} is {@code null}. * @throws IllegalArgumentException if the given {@link File} is not a file. - * @throws FileNotFoundException if the file does not exist + * @throws FileNotFoundException if the file does not exist. * @throws IOException if an IO error occurs reading the file. * @since 1.3 */ @@ -379,7 +379,7 @@ public static Checksum checksum(final File file, final Checksum checksum) throws * The value of the checksum is returned. * * @param file the file to checksum, must not be {@code null} - * @return the checksum value + * @return the checksum value. * @throws NullPointerException if the {@code file} is {@code null}. * @throws IllegalArgumentException if the {@code file} does not exist or is not a file. * @throws IOException if an IO error occurs reading the file. @@ -392,7 +392,7 @@ public static long checksumCRC32(final File file) throws IOException { /** * Cleans a directory without deleting it. * - * @param directory directory to clean + * @param directory directory to clean. * @throws NullPointerException if the given {@link File} is {@code null}. * @throws IllegalArgumentException if the {@code directory} does not exist or is not a directory. * @throws IOException if an I/O error occurs. @@ -422,9 +422,9 @@ private static void cleanDirectoryOnExit(final File directory) throws IOExceptio * resorting to byte-by-byte comparison of the contents. * * - * @param file1 the first file - * @param file2 the second file - * @return true if the content of the files are equal or they both don't exist, false otherwise + * @param file1 the first file. + * @param file2 the second file. + * @return true if the content of the files are equal or they both don't exist, false otherwise. * @throws IllegalArgumentException when an input is not a file. * @throws IOException If an I/O error occurs. * @see PathUtils#fileContentEquals(Path,Path) @@ -464,12 +464,12 @@ public static boolean contentEquals(final File file1, final File file2) throws I * before resorting to line-by-line comparison of the contents. * * - * @param file1 the first file - * @param file2 the second file + * @param file1 the first file. + * @param file2 the second file. * @param charsetName the name of the requested charset. - * May be null, in which case the platform default is used + * May be null, in which case the platform default is used. * @return true if the content of the files are equal or neither exists, - * false otherwise + * false otherwise. * @throws IllegalArgumentException when an input is not a file. * @throws IOException in case of an I/O error. * @throws UnsupportedCharsetException If the named charset is unavailable (unchecked exception). @@ -509,7 +509,7 @@ public static boolean contentEqualsIgnoreEOL(final File file1, final File file2, * representation. This is to account for the difference between * File.listFiles() and FileUtils.listFiles(). * - * @param files a Collection containing {@link File} instances + * @param files a Collection containing {@link File} instances. * @return an array of {@link File} */ public static File[] convertFileCollectionToFileArray(final Collection
* The output will be the same irrespective of the machine that the code is running on.
*
- * @param fileName the file name to find the last path separator in, null returns -1
+ * @param fileName the file name to find the last path separator in, null returns -1.
* @return the index of the last separator character, or -1 if there
- * is no such character
+ * is no such character.
*/
public static int indexOfLastSeparator(final String fileName) {
if (fileName == null) {
@@ -1032,17 +1012,16 @@ private static boolean isEmpty(final String string) {
* after the last period. There must be no directory separator after the period.
* The extension check is case-sensitive on all platforms.
*
- * @param fileName the file name, null returns false
- * @param extensions the extensions to check for, null checks for no extension
- * @return true if the file name is one of the extensions
- * @throws IllegalArgumentException if the file name contains the null character ({@code U+0000})
+ * @param fileName the file name, null returns false.
+ * @param extensions the extensions to check for, null checks for no extension.
+ * @return true if the file name is one of the extensions.
+ * @throws IllegalArgumentException if the file name contains the null character ({@code U+0000}).
*/
public static boolean isExtension(final String fileName, final Collection
* The output will be the same irrespective of the machine that the code is running on.
*
- * @param fileName the file name, null returns null
- * @return the file name minus the extension
- * @throws IllegalArgumentException if the file name contains the null character ({@code U+0000})
+ * @param fileName the file name, null returns null.
+ * @return the file name minus the extension.
+ * @throws IllegalArgumentException if the file name contains the null character ({@code U+0000}).
*/
public static String removeExtension(final String fileName) {
if (fileName == null) {
return null;
}
requireNonNullChars(fileName);
-
final int index = indexOfExtension(fileName);
if (index == NOT_FOUND) {
return fileName;
@@ -1477,9 +1447,9 @@ public static String removeExtension(final String fileName) {
*
* This may be used to defend against poison byte attacks.
*
- * @param path the path to check
- * @return The input
- * @throws IllegalArgumentException if path contains the null character ({@code U+0000})
+ * @param path the path to check.
+ * @return The input.
+ * @throws IllegalArgumentException if path contains the null character ({@code U+0000}).
*/
private static String requireNonNullChars(final String path) {
if (path.indexOf(0) >= 0) {
@@ -1524,17 +1494,15 @@ public static String separatorsToWindows(final String path) {
* The text is split by '?' and '*'.
* Where multiple '*' occur consecutively they are collapsed into a single '*'.
*
- * @param text the text to split
- * @return the array of tokens, never null
+ * @param text the text to split.
+ * @return the array of tokens, never null.
*/
static String[] splitOnTokens(final String text) {
// used by wildcardMatch
// package level so a unit test may run on this
-
if (text.indexOf('?') == NOT_FOUND && text.indexOf('*') == NOT_FOUND) {
return new String[] { text };
}
-
final char[] array = text.toCharArray();
final ArrayList
- * This method uses the virtual machine's {@link Charset#defaultCharset() default charset}. + * This method uses the virtual machine's {@linkplain Charset#defaultCharset() default charset}. *
* - * @param data the byte array to be dumped - * @param offset offset of the byte array within a larger entity + * @param data the byte array to be dumped. + * @param offset offset of the byte array within a larger entity. * @param stream the OutputStream to which the data is to be - * written - * @param index initial index into the byte array + * written. + * @param index initial index into the byte array. * @throws IOException is thrown if anything goes wrong writing - * the data to stream + * the data to stream. * @throws ArrayIndexOutOfBoundsException if the index is - * outside the data array's bounds - * @throws NullPointerException if the output stream is null + * outside the data array's bounds. + * @throws NullPointerException if the output stream is null. */ @SuppressWarnings("resource") // Caller closes stream public static void dump(final byte[] data, final long offset, @@ -197,8 +197,8 @@ public static void dump(final byte[] data, final long offset, /** * Dumps a byte value into a StringBuilder. * - * @param builder the StringBuilder to dump the value in - * @param value the byte value to be dumped + * @param builder the StringBuilder to dump the value in. + * @param value the byte value to be dumped. * @return StringBuilder containing the dumped value. */ private static StringBuilder dump(final StringBuilder builder, final byte value) { @@ -211,8 +211,8 @@ private static StringBuilder dump(final StringBuilder builder, final byte value) /** * Dumps a long value into a StringBuilder. * - * @param builder the StringBuilder to dump the value in - * @param value the long value to be dumped + * @param builder the StringBuilder to dump the value in. + * @param value the long value to be dumped. * @return StringBuilder containing the dumped value. */ private static StringBuilder dump(final StringBuilder builder, final long value) { diff --git a/src/main/java/org/apache/commons/io/IOCase.java b/src/main/java/org/apache/commons/io/IOCase.java index 7fee424f489..8afcdeafaf7 100644 --- a/src/main/java/org/apache/commons/io/IOCase.java +++ b/src/main/java/org/apache/commons/io/IOCase.java @@ -72,9 +72,9 @@ public enum IOCase { /** * Looks up an IOCase by name. * - * @param name the name to find - * @return the IOCase object - * @throws IllegalArgumentException if the name is invalid + * @param name the name to find. + * @return the IOCase object. + * @throws IllegalArgumentException if the name is invalid. */ public static IOCase forName(final String name) { return Stream.of(values()).filter(ioCase -> ioCase.getName().equals(name)).findFirst() @@ -236,7 +236,7 @@ public boolean checkStartsWith(final String str, final String start) { /** * Gets the name of the constant. * - * @return the name of the constant + * @return the name of the constant. */ public String getName() { return name; diff --git a/src/main/java/org/apache/commons/io/IOExceptionList.java b/src/main/java/org/apache/commons/io/IOExceptionList.java index 740bedb6789..256cebd1360 100644 --- a/src/main/java/org/apache/commons/io/IOExceptionList.java +++ b/src/main/java/org/apache/commons/io/IOExceptionList.java @@ -126,7 +126,7 @@ public- * 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. + * 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. *
*- * All the methods in this class that read a stream are buffered internally. - * This means that there is no cause to use a {@link BufferedInputStream} - * or {@link BufferedReader}. The default buffer size of 4K has been shown - * to be efficient in tests. + * All the methods in this class that read a stream are buffered internally. This means that there is no cause to use a {@link BufferedInputStream} or + * {@link BufferedReader}. The default buffer size of 4K has been shown to be efficient in tests. *
** The various copy methods all delegate the actual copying to one of the following methods: @@ -110,18 +105,14 @@ *
- * 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. + * 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. *
*- * Wherever possible, the methods in this class do not 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. + * Wherever possible, the methods in this class do not 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. *
** Provenance: Excalibur. @@ -132,6 +123,142 @@ public class IOUtils { // Writer. Each method should take at least one of these as a parameter, // or return one of them. + /** + * Holder for per-thread internal scratch buffer. + *
+ * Buffers are created lazily and reused within the same thread to reduce allocation overhead. In the rare case of reentrant access, a temporary buffer is + * allocated to avoid data corruption. + *
+ *+ * Typical usage: + *
+ * + *{@code
+ * try (ScratchBytes scratch = ScratchBytes.get()) {
+ * // use the buffer
+ * byte[] bytes = scratch.array();
+ * // ...
+ * }
+ * }
+ */
+ static final class ScratchBytes implements AutoCloseable {
+
+ /**
+ * Wraps an internal byte array. [0] boolean in use. [1] byte[] buffer.
+ */
+ private static final ThreadLocal+ * Buffers are created lazily and reused within the same thread to reduce allocation overhead. In the rare case of reentrant access, a temporary buffer is + * allocated to avoid data corruption. + *
+ *+ * Typical usage: + *
+ * + *{@code
+ * try (ScratchChars scratch = ScratchChars.get()) {
+ * // use the buffer
+ * char[] bytes = scratch.array();
+ * // ...
+ * }
+ * }
+ */
+ static final class ScratchChars implements AutoCloseable {
+
+ /**
+ * Wraps an internal char array. [0] boolean in use. [1] char[] buffer.
+ */
+ private static final ThreadLocal@@ -232,8 +340,7 @@ public class IOUtils { public static final int SOFT_MAX_ARRAY_LENGTH = Integer.MAX_VALUE - 8; /** - * 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). * @return the given InputStream or a new {@link BufferedInputStream} for the given InputStream. @@ -245,16 +352,14 @@ public static BufferedInputStream buffer(final InputStream inputStream) { // reject null early on rather than waiting for IO operation to fail // not checked by BufferedInputStream Objects.requireNonNull(inputStream, "inputStream"); - 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 size the buffer size, if a new BufferedInputStream is created. + * @param size the buffer size, if a new BufferedInputStream is created. * @return the given InputStream or a new {@link BufferedInputStream} for the given InputStream. * @throws NullPointerException if the input parameter is null. * @since 2.5 @@ -264,16 +369,14 @@ public static BufferedInputStream buffer(final InputStream inputStream, final in // reject null early on rather than waiting for IO operation to fail // not checked by BufferedInputStream Objects.requireNonNull(inputStream, "inputStream"); - return inputStream instanceof BufferedInputStream ? - (BufferedInputStream) inputStream : new BufferedInputStream(inputStream, size); + return inputStream instanceof BufferedInputStream ? (BufferedInputStream) inputStream : new BufferedInputStream(inputStream, 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). - * @return the given OutputStream or a new {@link BufferedOutputStream} for the given OutputStream + * @return the given OutputStream or a new {@link BufferedOutputStream} for the given OutputStream. * @throws NullPointerException if the input parameter is null. * @since 2.5 */ @@ -282,16 +385,14 @@ public static BufferedOutputStream buffer(final OutputStream outputStream) { // reject null early on rather than waiting for IO operation to fail // not checked by BufferedInputStream Objects.requireNonNull(outputStream, "outputStream"); - 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 size the buffer size, if a new BufferedOutputStream is created. + * @param size the buffer size, if a new BufferedOutputStream is created. * @return the given OutputStream or a new {@link BufferedOutputStream} for the given OutputStream. * @throws NullPointerException if the input parameter is null. * @since 2.5 @@ -301,13 +402,11 @@ public static BufferedOutputStream buffer(final OutputStream outputStream, final // reject null early on rather than waiting for IO operation to fail // not checked by BufferedInputStream Objects.requireNonNull(outputStream, "outputStream"); - return outputStream instanceof BufferedOutputStream ? - (BufferedOutputStream) outputStream : new BufferedOutputStream(outputStream, size); + return outputStream instanceof BufferedOutputStream ? (BufferedOutputStream) outputStream : new BufferedOutputStream(outputStream, 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). * @return the given reader or a new {@link BufferedReader} for the given reader. @@ -319,11 +418,10 @@ public static BufferedReader buffer(final Reader 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 size the buffer size, if a new BufferedReader is created. + * @param size the buffer size, if a new BufferedReader is created. * @return the given reader or a new {@link BufferedReader} for the given reader. * @throws NullPointerException if the input parameter is null. * @since 2.5 @@ -333,8 +431,7 @@ public static BufferedReader buffer(final Reader reader, final int 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). * @return the given Writer or a new {@link BufferedWriter} for the given Writer. @@ -346,11 +443,10 @@ public static BufferedWriter buffer(final Writer 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 size the buffer size, if a new BufferedWriter is created. + * @param size the buffer size, if a new BufferedWriter is created. * @return the given Writer or a new {@link BufferedWriter} for the given Writer. * @throws NullPointerException if the input parameter is null. * @since 2.5 @@ -370,9 +466,7 @@ public static byte[] byteArray() { } /** - * Returns a new byte array of the given size. - * - * TODO Consider guarding or warning against large allocations. + * Returns a new byte array of the given size. TODO Consider guarding or warning against large allocations. * * @param size array size. * @return a new byte array of the given size. @@ -394,9 +488,7 @@ private static char[] charArray() { } /** - * Returns a new char array of the given size. - * - * TODO Consider guarding or warning against large allocations. + * Returns a new char array of the given size. TODO Consider guarding or warning against large allocations. * * @param size array size. * @return a new char array of the given size. @@ -408,19 +500,23 @@ private static char[] charArray(final int size) { /** * Validates that the sub-range {@code [off, off + len)} is within the bounds of the given array. - * - *
The range is valid if all of the following hold:
+ *+ * The range is valid if all of the following hold: + *
*+ * If the range is invalid, throws {@link IndexOutOfBoundsException} with a descriptive message. + *
+ *+ * Typical usage in {@link InputStream#read(byte[], int, int)} and {@link OutputStream#write(byte[], int, int)} implementations: + *
* - *If the range is invalid, throws {@link IndexOutOfBoundsException} with a descriptive message.
- * - *Typical usage in {@link InputStream#read(byte[], int, int)} and {@link OutputStream#write(byte[], int, int)} implementations:
- * - *
+ *
+ *
* public int read(byte[] b, int off, int len) throws IOException {
* IOUtils.checkFromIndexSize(b, off, len);
* if (len == 0) {
@@ -438,13 +534,14 @@ private static char[] charArray(final int size) {
* ensureOpen();
* // perform write...
* }
- *
+ *
+ * The range is valid if all of the following hold:
+ *+ * The range is valid if all of the following hold: + *
*+ * If the range is invalid, throws {@link IndexOutOfBoundsException} with a descriptive message. + *
+ *+ * Typical usage in {@link Reader#read(char[], int, int)} and {@link Writer#write(char[], int, int)} implementations: + *
* - *If the range is invalid, throws {@link IndexOutOfBoundsException} with a descriptive message.
- * - *Typical usage in {@link Reader#read(char[], int, int)} and {@link Writer#write(char[], int, int)} implementations:
- * - *
+ *
+ *
* public int read(char[] cbuf, int off, int len) throws IOException {
* ensureOpen();
* IOUtils.checkFromIndexSize(cbuf, off, len);
@@ -485,13 +586,14 @@ public static void checkFromIndexSize(final byte[] array, final int off, final i
* }
* // perform write...
* }
- *
+ *
+ * + * The range is valid if all of the following hold: + *
*+ * If the range is invalid, throws {@link IndexOutOfBoundsException} with a descriptive message. + *
+ *+ * Typical usage in {@link Writer#write(String, int, int)} implementations: + *
* - *If the range is invalid, throws {@link IndexOutOfBoundsException} with a descriptive message.
- * - *Typical usage in {@link Writer#write(String, int, int)} implementations:
- * - *
+ *
+ *
* public void write(String str, int off, int len) throws IOException {
* IOUtils.checkFromIndexSize(str, off, len);
* if (len == 0) {
@@ -522,13 +634,14 @@ public static void checkFromIndexSize(final char[] array, final int off, final i
* }
* // perform write...
* }
- *
+ *
+ * + * The sub-sequence is valid if all of the following hold: + *
*+ * If {@code seq} is {@code null}, it is treated as the literal string {@code "null"} (length {@code 4}). + *
+ *+ * If the range is invalid, throws {@link IndexOutOfBoundsException} with a descriptive message. + *
+ *+ * Typical usage in {@link Appendable#append(CharSequence, int, int)} implementations: + *
* - *If {@code seq} is {@code null}, it is treated as the literal string {@code "null"} (length {@code 4}).
- * - *If the range is invalid, throws {@link IndexOutOfBoundsException} with a descriptive message.
- * - *Typical usage in {@link Appendable#append(CharSequence, int, int)} implementations:
- * - *
+ *
+ *
* public Appendable append(CharSequence csq, int start, int end) throws IOException {
* IOUtils.checkFromToIndex(csq, start, end);
* // perform append...
* return this;
* }
- *
+ *
+ * - * Equivalent to {@link Closeable#close()}, except any exceptions will be ignored. This is typically used in - * finally blocks. + * Equivalent to {@link Closeable#close()}, except any exceptions will be ignored. This is typically used in finally blocks. *
* Example code: *
+ * *
* Closeable closeable = null;
* try {
@@ -691,6 +802,7 @@ private static void closeQ(final Closeable closeable) {
*
* Closing all streams:
*
+ *
*
* try {
* return IOUtils.copy(inputStream, outputStream);
@@ -708,7 +820,7 @@ private static void closeQ(final Closeable closeable) {
* @see Throwable#addSuppressed(Throwable)
*/
public static void closeQuietly(final Closeable closeable) {
- closeQuietly(closeable, null);
+ closeQuietly(closeable, (Consumer) null);
}
/**
@@ -716,17 +828,17 @@ public static void closeQuietly(final Closeable closeable) {
*
* Equivalent to {@link Closeable#close()}, except any exceptions will be ignored.
*
- * 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.
- *
- * It should not be used to replace the close statement(s)
- * which should be present for the non-exceptional case.
- *
- * 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.
+ * 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.
+ *
+ *
+ * It should not be used to replace the close statement(s) which should be present for the non-exceptional case.
+ *
+ * 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.
*
* Example code:
*
+ *
*
* Closeable closeable = null;
* try {
@@ -741,7 +853,8 @@ public static void closeQuietly(final Closeable closeable) {
*
*
* Closing all streams:
- *
+ *
+ *
*
* try {
* return IOUtils.copy(inputStream, outputStream);
@@ -752,6 +865,7 @@ public static void closeQuietly(final Closeable closeable) {
*
* Also consider using a try-with-resources statement where appropriate.
*
+ *
* @param closeables the objects to close, may be null or already closed.
* @see #closeQuietly(Closeable)
* @since 2.5
@@ -767,7 +881,7 @@ public static void closeQuietly(final Closeable... closeables) {
* Closes the given {@link Closeable} as a null-safe operation while consuming IOException by the given {@code consumer}.
*
* @param closeable The resource to close, may be null.
- * @param consumer Consumes the Exception thrown by {@link Closeable#close()}.
+ * @param consumer Consumes the Exception thrown by {@link Closeable#close()}.
* @since 2.7
*/
public static void closeQuietly(final Closeable closeable, final Consumer consumer) {
@@ -785,24 +899,24 @@ public static void closeQuietly(final Closeable closeable, final Consumer
- * Equivalent to {@link InputStream#close()}, except any exceptions will be ignored.
- * This is typically used in finally blocks.
+ * Equivalent to {@link InputStream#close()}, except any exceptions will be ignored. This is typically used in finally blocks.
*
*
* Example code:
*
+ *
*
- * byte[] data = new byte[1024];
- * InputStream in = null;
- * try {
- * in = new FileInputStream("foo.txt");
- * in.read(data);
- * in.close(); //close errors are handled
- * } catch (Exception e) {
- * // error handling
- * } finally {
- * IOUtils.closeQuietly(in);
- * }
+ * byte[] data = new byte[1024];
+ * InputStream in = null;
+ * try {
+ * in = new FileInputStream("foo.txt");
+ * in.read(data);
+ * in.close(); // close errors are handled
+ * } catch (Exception e) {
+ * // error handling
+ * } finally {
+ * IOUtils.closeQuietly(in);
+ * }
*
*
* Also consider using a try-with-resources statement where appropriate.
@@ -834,20 +948,19 @@ public static void closeQuietly(final Iterable closeables) {
/**
* Closes an {@link OutputStream} unconditionally.
*
- * Equivalent to {@link OutputStream#close()}, except any exceptions will be ignored.
- * This is typically used in finally blocks.
+ * Equivalent to {@link OutputStream#close()}, except any exceptions will be ignored. This is typically used in finally blocks.
*
*
* Example code:
*
+ *
*
* byte[] data = "Hello, World".getBytes();
- *
* OutputStream out = null;
* try {
* out = new FileOutputStream("foo.txt");
* out.write(data);
- * out.close(); //close errors are handled
+ * out.close(); // close errors are handled
* } catch (IOException e) {
* // error handling
* } finally {
@@ -868,24 +981,24 @@ public static void closeQuietly(final OutputStream output) {
/**
* Closes an {@link Reader} unconditionally.
*
- * Equivalent to {@link Reader#close()}, except any exceptions will be ignored.
- * This is typically used in finally blocks.
+ * Equivalent to {@link Reader#close()}, except any exceptions will be ignored. This is typically used in finally blocks.
*
*
* Example code:
*
+ *
*
- * char[] data = new char[1024];
- * Reader in = null;
- * try {
- * in = new FileReader("foo.txt");
- * in.read(data);
- * in.close(); //close errors are handled
- * } catch (Exception e) {
- * // error handling
- * } finally {
- * IOUtils.closeQuietly(in);
- * }
+ * char[] data = new char[1024];
+ * Reader in = null;
+ * try {
+ * in = new FileReader("foo.txt");
+ * in.read(data);
+ * in.close(); // close errors are handled
+ * } catch (Exception e) {
+ * // error handling
+ * } finally {
+ * IOUtils.closeQuietly(in);
+ * }
*
*
* Also consider using a try-with-resources statement where appropriate.
@@ -901,23 +1014,22 @@ public static void closeQuietly(final Reader reader) {
/**
* Closes a {@link Selector} unconditionally.
*
- * Equivalent to {@link Selector#close()}, except any exceptions will be ignored.
- * This is typically used in finally blocks.
+ * Equivalent to {@link Selector#close()}, except any exceptions will be ignored. This is typically used in finally blocks.
*
*
* Example code:
*
+ *
*
- * Selector selector = null;
- * try {
- * selector = Selector.open();
- * // process socket
- *
- * } catch (Exception e) {
- * // error handling
- * } finally {
- * IOUtils.closeQuietly(selector);
- * }
+ * Selector selector = null;
+ * try {
+ * selector = Selector.open();
+ * // process socket
+ * } catch (Exception e) {
+ * // error handling
+ * } finally {
+ * IOUtils.closeQuietly(selector);
+ * }
*
*
* Also consider using a try-with-resources statement where appropriate.
@@ -934,23 +1046,23 @@ public static void closeQuietly(final Selector selector) {
/**
* Closes a {@link ServerSocket} unconditionally.
*
- * Equivalent to {@link ServerSocket#close()}, except any exceptions will be ignored.
- * This is typically used in finally blocks.
+ * Equivalent to {@link ServerSocket#close()}, except any exceptions will be ignored. This is typically used in finally blocks.
*
*
* Example code:
*
+ *
*
- * ServerSocket socket = null;
- * try {
- * socket = new ServerSocket();
- * // process socket
- * socket.close();
- * } catch (Exception e) {
- * // error handling
- * } finally {
- * IOUtils.closeQuietly(socket);
- * }
+ * ServerSocket socket = null;
+ * try {
+ * socket = new ServerSocket();
+ * // process socket
+ * socket.close();
+ * } catch (Exception e) {
+ * // error handling
+ * } finally {
+ * IOUtils.closeQuietly(socket);
+ * }
*
*
* Also consider using a try-with-resources statement where appropriate.
@@ -967,23 +1079,23 @@ public static void closeQuietly(final ServerSocket serverSocket) {
/**
* Closes a {@link Socket} unconditionally.
*
- * Equivalent to {@link Socket#close()}, except any exceptions will be ignored.
- * This is typically used in finally blocks.
+ * Equivalent to {@link Socket#close()}, except any exceptions will be ignored. This is typically used in finally blocks.
*
*
* Example code:
*
+ *
*
- * Socket socket = null;
- * try {
- * socket = new Socket("http://www.foo.com/", 80);
- * // process socket
- * socket.close();
- * } catch (Exception e) {
- * // error handling
- * } finally {
- * IOUtils.closeQuietly(socket);
- * }
+ * Socket socket = null;
+ * try {
+ * socket = new Socket("http://www.foo.com/", 80);
+ * // process socket
+ * socket.close();
+ * } catch (Exception e) {
+ * // error handling
+ * } finally {
+ * IOUtils.closeQuietly(socket);
+ * }
*
*
* Also consider using a try-with-resources statement where appropriate.
@@ -1016,23 +1128,23 @@ public static void closeQuietly(final Stream closeables) {
/**
* Closes an {@link Writer} unconditionally.
*
- * Equivalent to {@link Writer#close()}, except any exceptions will be ignored.
- * This is typically used in finally blocks.
+ * Equivalent to {@link Writer#close()}, except any exceptions will be ignored. This is typically used in finally blocks.
*
*
* Example code:
*
+ *
*
- * Writer out = null;
- * try {
- * out = new StringWriter();
- * out.write("Hello World");
- * out.close(); //close errors are handled
- * } catch (Exception e) {
- * // error handling
- * } finally {
- * IOUtils.closeQuietly(out);
- * }
+ * Writer out = null;
+ * try {
+ * out = new StringWriter();
+ * out.write("Hello World");
+ * out.close(); // close errors are handled
+ * } catch (Exception e) {
+ * // error handling
+ * } finally {
+ * IOUtils.closeQuietly(out);
+ * }
*
*
* Also consider using a try-with-resources statement where appropriate.
@@ -1045,6 +1157,37 @@ public static void closeQuietly(final Writer writer) {
closeQ(writer);
}
+ /**
+ * Closes a {@link Closeable} unconditionally and adds any exception thrown by the {@code close()} to the given Throwable.
+ *
+ * For example:
+ *
+ *
+ *
+ * Closeable closeable = ...;
+ * try {
+ * // process closeable.
+ * } catch (Exception e) {
+ * // Handle exception.
+ * throw IOUtils.closeQuietlySuppress(closeable, e);
+ * }
+ *
+ *
+ * Also consider using a try-with-resources statement where appropriate.
+ *
+ *
+ * @param The Throwable type.
+ * @param closeable The object to close, may be null or already closed.
+ * @param throwable Add the exception throw by the closeable to the given Throwable.
+ * @return The given Throwable.
+ * @since 2.22.0
+ * @see Throwable#addSuppressed(Throwable)
+ */
+ public static T closeQuietlySuppress(final Closeable closeable, final T throwable) {
+ closeQuietly(closeable, throwable::addSuppressed);
+ return throwable;
+ }
+
/**
* Consumes bytes from a {@link InputStream} and ignores them.
*
@@ -1054,7 +1197,7 @@ public static void closeQuietly(final Writer writer) {
* @param input the {@link InputStream} to read.
* @return the number of bytes copied. or {@code 0} if {@code input is null}.
* @throws NullPointerException if the InputStream is {@code null}.
- * @throws IOException if an I/O error occurs.
+ * @throws IOException if an I/O error occurs.
* @since 2.8.0
*/
public static long consume(final InputStream input) throws IOException {
@@ -1070,7 +1213,7 @@ public static long consume(final InputStream input) throws IOException {
* @param input the {@link Reader} to read.
* @return the number of bytes copied. or {@code 0} if {@code input is null}.
* @throws NullPointerException if the Reader is {@code null}.
- * @throws IOException if an I/O error occurs.
+ * @throws IOException if an I/O error occurs.
* @since 2.12.0
*/
public static long consume(final Reader input) throws IOException {
@@ -1078,18 +1221,15 @@ public static long consume(final Reader input) throws IOException {
}
/**
- * Compares the contents of two Streams to determine if they are equal or
- * not.
+ * Compares the contents of two Streams to determine if they are equal or not.
*
- * This method buffers the input internally using
- * {@link BufferedInputStream} if they are not already buffered.
+ * This method buffers the input internally using {@link BufferedInputStream} if they are not already buffered.
*
*
* @param input1 the first stream.
* @param input2 the second stream.
- * @return true if the content of the streams are equal or they both don't.
- * exist, false otherwise.
- * @throws IOException if an I/O error occurs.
+ * @return true if the content of the streams are equal or they both don't. exist, false otherwise.
+ * @throws IOException if an I/O error occurs.
*/
@SuppressWarnings("resource") // Caller closes input streams
public static boolean contentEquals(final InputStream input1, final InputStream input2) throws IOException {
@@ -1107,10 +1247,7 @@ public static boolean contentEquals(final InputStream input1, final InputStream
// TODO Consider making public
private static boolean contentEquals(final Iterator iterator1, final Iterator iterator2) {
while (iterator1.hasNext()) {
- if (!iterator2.hasNext()) {
- return false;
- }
- if (!Objects.equals(iterator1.next(), iterator2.next())) {
+ if (!iterator2.hasNext() || !Objects.equals(iterator1.next(), iterator2.next())) {
return false;
}
}
@@ -1127,7 +1264,7 @@ private static boolean contentEquals(final Iterator iterator1, final Iterator
* @param input2 the second reader.
* @return true if the content of the readers are equal or they both don't exist, false otherwise.
* @throws NullPointerException if either input is null.
- * @throws IOException if an I/O error occurs.
+ * @throws IOException if an I/O error occurs.
* @since 1.1
*/
public static boolean contentEquals(final Reader input1, final Reader input2) throws IOException {
@@ -1137,39 +1274,38 @@ public static boolean contentEquals(final Reader input1, final Reader input2) th
if (input1 == null || input2 == null) {
return false;
}
-
- // reuse one
- final char[] array1 = getScratchCharArray();
- // but allocate another
- final char[] array2 = charArray();
- int pos1;
- int pos2;
- int count1;
- int count2;
- while (true) {
- pos1 = 0;
- pos2 = 0;
- for (int index = 0; index < DEFAULT_BUFFER_SIZE; index++) {
- if (pos1 == index) {
- do {
- count1 = input1.read(array1, pos1, DEFAULT_BUFFER_SIZE - pos1);
- } while (count1 == 0);
- if (count1 == EOF) {
- return pos2 == index && input2.read() == EOF;
+ try (ScratchChars scratch = IOUtils.ScratchChars.get()) {
+ final char[] array1 = scratch.array();
+ final char[] array2 = charArray();
+ int pos1;
+ int pos2;
+ int count1;
+ int count2;
+ while (true) {
+ pos1 = 0;
+ pos2 = 0;
+ for (int index = 0; index < DEFAULT_BUFFER_SIZE; index++) {
+ if (pos1 == index) {
+ do {
+ count1 = input1.read(array1, pos1, DEFAULT_BUFFER_SIZE - pos1);
+ } while (count1 == 0);
+ if (count1 == EOF) {
+ return pos2 == index && input2.read() == EOF;
+ }
+ pos1 += count1;
}
- pos1 += count1;
- }
- if (pos2 == index) {
- do {
- count2 = input2.read(array2, pos2, DEFAULT_BUFFER_SIZE - pos2);
- } while (count2 == 0);
- if (count2 == EOF) {
- return pos1 == index && input1.read() == EOF;
+ if (pos2 == index) {
+ do {
+ count2 = input2.read(array2, pos2, DEFAULT_BUFFER_SIZE - pos2);
+ } while (count2 == 0);
+ if (count2 == EOF) {
+ return pos1 == index && input1.read() == EOF;
+ }
+ pos2 += count2;
+ }
+ if (array1[index] != array2[index]) {
+ return false;
}
- pos2 += count2;
- }
- if (array1[index] != array2[index]) {
- return false;
}
}
}
@@ -1198,16 +1334,14 @@ private static boolean contentEqualsIgnoreEOL(final BufferedReader reader1, fina
}
/**
- * Compares the contents of two Readers to determine if they are equal or
- * not, ignoring EOL characters.
+ * Compares the contents of two Readers to determine if they are equal or not, ignoring EOL characters.
*
- * This method buffers the input internally using
- * {@link BufferedReader} if they are not already buffered.
+ * This method buffers the input internally using {@link BufferedReader} if they are not already buffered.
*
*
* @param reader1 the first reader.
* @param reader2 the second reader.
- * @return true if the content of the readers are equal (ignoring EOL differences), false otherwise.
+ * @return true if the content of the readers are equal (ignoring EOL differences), false otherwise.
* @throws NullPointerException if either input is null.
* @throws UncheckedIOException if an I/O error occurs.
* @since 2.2
@@ -1229,17 +1363,16 @@ public static boolean contentEqualsIgnoreEOL(final Reader reader1, final Reader
* This method buffers the input internally, so there is no need to use a {@link BufferedInputStream}.
*
*
- * Large streams (over 2GB) will return a bytes copied value of {@code -1} after the copy has completed since
- * the correct number of bytes cannot be returned as an int. For large streams use the
- * {@link #copyLarge(InputStream, OutputStream)} method.
+ * Large streams (over 2GB) will return a bytes copied value of {@code -1} after the copy has completed since the correct number of bytes cannot be returned
+ * as an int. For large streams use the {@link #copyLarge(InputStream, OutputStream)} method.
*
*
- * @param inputStream the {@link InputStream} to read.
+ * @param inputStream the {@link InputStream} to read.
* @param outputStream the {@link OutputStream} to write.
* @return the number of bytes copied, or -1 if greater than {@link Integer#MAX_VALUE}.
* @throws NullPointerException if the InputStream is {@code null}.
* @throws NullPointerException if the OutputStream is {@code 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 inputStream, final OutputStream outputStream) throws IOException {
@@ -1248,19 +1381,18 @@ public static int copy(final InputStream inputStream, final OutputStream outputS
}
/**
- * Copies bytes from an {@link InputStream} to an {@link OutputStream} using an internal buffer of the
- * given size.
+ * Copies bytes from an {@link InputStream} to an {@link OutputStream} using an internal buffer of the given size.
*
* This method buffers the input internally, so there is no need to use a {@link BufferedInputStream}.
*
*
- * @param inputStream the {@link InputStream} to read.
+ * @param inputStream the {@link InputStream} to read.
* @param outputStream the {@link OutputStream} to write to.
- * @param bufferSize the bufferSize used to copy from the input to the output.
+ * @param bufferSize the bufferSize used to copy from the input to the output.
* @return the number of bytes copied.
* @throws NullPointerException if the InputStream is {@code null}.
* @throws NullPointerException if the OutputStream is {@code null}.
- * @throws IOException if an I/O error occurs.
+ * @throws IOException if an I/O error occurs.
* @since 2.5
*/
public static long copy(final InputStream inputStream, final OutputStream outputStream, final int bufferSize) throws IOException {
@@ -1268,17 +1400,15 @@ public static long copy(final InputStream inputStream, final OutputStream output
}
/**
- * Copies bytes from an {@link InputStream} to chars on a
- * {@link Writer} using the virtual machine's {@link Charset#defaultCharset() default charset}.
+ * Copies bytes from an {@link InputStream} to chars on a {@link Writer} using the virtual machine's {@linkplain Charset#defaultCharset() default charset}.
*
- * This method buffers the input internally, so there is no need to use a
- * {@link BufferedInputStream}.
+ * This method buffers the input internally, so there is no need to use a {@link BufferedInputStream}.
*
*
* This method uses {@link InputStreamReader}.
*
*
- * @param input the {@link InputStream} to read.
+ * @param input the {@link InputStream} to read.
* @param writer the {@link Writer} to write to.
* @throws NullPointerException if the input or output is null.
* @throws IOException if an I/O error occurs.
@@ -1291,18 +1421,16 @@ public static void copy(final InputStream input, final Writer writer) throws IOE
}
/**
- * Copies bytes from an {@link InputStream} to chars on a
- * {@link Writer} using the specified character encoding.
+ * Copies bytes from an {@link InputStream} to chars on a {@link Writer} using the specified character encoding.
*
- * This method buffers the input internally, so there is no need to use a
- * {@link BufferedInputStream}.
+ * This method buffers the input internally, so there is no need to use a {@link BufferedInputStream}.
*
*
* This method uses {@link InputStreamReader}.
*
*
- * @param input the {@link InputStream} to read.
- * @param writer the {@link Writer} to write to.
+ * @param input the {@link InputStream} to read.
+ * @param writer the {@link Writer} to write to.
* @param inputCharset the charset to use for the input stream, null means platform default.
* @throws NullPointerException if the input or output is null.
* @throws IOException if an I/O error occurs.
@@ -1313,22 +1441,19 @@ public static void copy(final InputStream input, final Writer writer, final Char
}
/**
- * Copies bytes from an {@link InputStream} to chars on a
- * {@link Writer} using the specified character encoding.
+ * Copies bytes from an {@link InputStream} to chars on a {@link Writer} using the specified character encoding.
*
- * This method buffers the input internally, so there is no need to use a
- * {@link BufferedInputStream}.
+ * This method buffers the input internally, so there is no need to use a {@link BufferedInputStream}.
*
*
- * Character encoding names can be found at
- * IANA.
+ * Character encoding names can be found at IANA.
*
*
* This method uses {@link InputStreamReader}.
*
*
- * @param input the {@link InputStream} to read
- * @param writer the {@link Writer} to write to
+ * @param input the {@link InputStream} to read.
+ * @param writer the {@link Writer} to write to.
* @param inputCharsetName the name of the requested charset for the InputStream, null means platform default.
* @throws NullPointerException if the input or output is null.
* @throws IOException if an I/O error occurs.
@@ -1342,8 +1467,7 @@ public static void copy(final InputStream input, final Writer writer, final Stri
/**
* Copies bytes from a {@link ByteArrayOutputStream} to a {@link QueueInputStream}.
*
- * Unlike using JDK {@link PipedInputStream} and {@link PipedOutputStream} for this, this
- * solution works safely in a single thread environment.
+ * Unlike using JDK {@link PipedInputStream} and {@link PipedOutputStream} for this, this solution works safely in a single thread environment.
*
*
* Example usage:
@@ -1352,14 +1476,13 @@ public static void copy(final InputStream input, final Writer writer, final Stri
*
* ByteArrayOutputStream outputStream = new ByteArrayOutputStream();
* outputStream.writeBytes("hello world".getBytes(StandardCharsets.UTF_8));
- *
* InputStream inputStream = IOUtils.copy(outputStream);
*
*
* @param outputStream the {@link ByteArrayOutputStream} to read.
* @return the {@link QueueInputStream} filled with the content of the outputStream.
* @throws NullPointerException if the {@link ByteArrayOutputStream} is {@code null}.
- * @throws IOException if an I/O error occurs.
+ * @throws IOException if an I/O error occurs.
* @since 2.12
*/
@SuppressWarnings("resource") // streams are closed by the caller.
@@ -1373,14 +1496,11 @@ public static QueueInputStream copy(final java.io.ByteArrayOutputStream outputSt
/**
* Copies chars from a {@link Reader} to a {@link Appendable}.
*
- * This method buffers the input internally, so there is no need to use a
- * {@link BufferedReader}.
+ * This method buffers the input internally, so there is no need to use a {@link BufferedReader}.
*
*
- * Large streams (over 2GB) will return a chars copied value of
- * {@code -1} after the copy has completed since the correct
- * number of chars cannot be returned as an int. For large streams
- * use the {@link #copyLarge(Reader, Writer)} method.
+ * Large streams (over 2GB) will return a chars copied value of {@code -1} after the copy has completed since the correct number of chars cannot be returned
+ * as an int. For large streams use the {@link #copyLarge(Reader, Writer)} method.
*
*
* @param reader the {@link Reader} to read.
@@ -1397,8 +1517,7 @@ public static long copy(final Reader reader, final Appendable output) throws IOE
/**
* Copies chars from a {@link Reader} to an {@link Appendable}.
*
- * This method uses the provided buffer, so there is no need to use a
- * {@link BufferedReader}.
+ * This method uses the provided buffer, so there is no need to use a {@link BufferedReader}.
*
*
* @param reader the {@link Reader} to read.
@@ -1421,7 +1540,7 @@ 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 the virtual machine's {@link Charset#defaultCharset() default charset},
+ * Copies chars from a {@link Reader} to bytes on an {@link OutputStream} using the virtual machine's {@linkplain Charset#defaultCharset() default charset},
* and calling flush.
*
* This method buffers the input internally, so there is no need to use a {@link BufferedReader}.
@@ -1438,7 +1557,7 @@ public static long copy(final Reader reader, final Appendable output, final Char
* @throws NullPointerException if the input or output is null.
* @throws IOException if an I/O error occurs.
* @since 1.1
- * @deprecated Use {@link #copy(Reader, OutputStream, Charset)} instead
+ * @deprecated Use {@link #copy(Reader, OutputStream, Charset)} instead.
*/
@Deprecated
public static void copy(final Reader reader, final OutputStream output) throws IOException {
@@ -1478,7 +1597,7 @@ public static void copy(final Reader reader, final OutputStream output, final Ch
* This method buffers the input internally, so there is no need to use a {@link BufferedReader}.
*
*
- * Character encoding names can be found at IANA.
+ * Character encoding names can be found at IANA.
*
*
* Due to the implementation of OutputStreamWriter, this method performs a flush.
@@ -1502,14 +1621,11 @@ public static void copy(final Reader reader, final OutputStream output, final St
/**
* Copies chars from a {@link Reader} to a {@link Writer}.
*
- * This method buffers the input internally, so there is no need to use a
- * {@link BufferedReader}.
+ * This method buffers the input internally, so there is no need to use a {@link BufferedReader}.
*
*
- * Large streams (over 2GB) will return a chars copied value of
- * {@code -1} after the copy has completed since the correct
- * number of chars cannot be returned as an int. For large streams
- * use the {@link #copyLarge(Reader, Writer)} method.
+ * Large streams (over 2GB) will return a chars copied value of {@code -1} after the copy has completed since the correct number of chars cannot be returned
+ * as an int. For large streams use the {@link #copyLarge(Reader, Writer)} method.
*
*
* @param reader the {@link Reader} to read.
@@ -1536,12 +1652,12 @@ public static int copy(final Reader reader, final Writer writer) throws IOExcept
* The buffer size is given by {@link #DEFAULT_BUFFER_SIZE}.
*
*
- * @param url the {@link URL} to read.
+ * @param url the {@link URL} to read.
* @param file the {@link OutputStream} to write.
* @return the number of bytes copied.
* @throws NullPointerException if the URL is {@code null}.
* @throws NullPointerException if the OutputStream is {@code null}.
- * @throws IOException if an I/O error occurs.
+ * @throws IOException if an I/O error occurs.
* @since 2.9.0
*/
public static long copy(final URL url, final File file) throws IOException {
@@ -1559,12 +1675,12 @@ public static long copy(final URL url, final File file) throws IOException {
* The buffer size is given by {@link #DEFAULT_BUFFER_SIZE}.
*
*
- * @param url the {@link URL} to read.
+ * @param url the {@link URL} to read.
* @param outputStream the {@link OutputStream} to write.
* @return the number of bytes copied.
* @throws NullPointerException if the URL is {@code null}.
* @throws NullPointerException if the OutputStream is {@code null}.
- * @throws IOException if an I/O error occurs.
+ * @throws IOException if an I/O error occurs.
* @since 2.9.0
*/
public static long copy(final URL url, final OutputStream outputStream) throws IOException {
@@ -1574,49 +1690,43 @@ public static long copy(final URL url, final OutputStream outputStream) throws I
}
/**
- * Copies bytes from a large (over 2GB) {@link InputStream} to an
- * {@link OutputStream}.
+ * Copies bytes from a large (over 2GB) {@link InputStream} to an {@link OutputStream}.
*
- * This method buffers the input internally, so there is no need to use a
- * {@link BufferedInputStream}.
+ * This method buffers the input internally, so there is no need to use a {@link BufferedInputStream}.
*
*
* The buffer size is given by {@link #DEFAULT_BUFFER_SIZE}.
*
*
- * @param inputStream the {@link InputStream} to read.
+ * @param inputStream the {@link InputStream} to read.
* @param outputStream the {@link OutputStream} to write.
* @return the number of bytes copied.
* @throws NullPointerException if the InputStream is {@code null}.
* @throws NullPointerException if the OutputStream is {@code null}.
- * @throws IOException if an I/O error occurs.
+ * @throws IOException if an I/O error occurs.
* @since 1.3
*/
- public static long copyLarge(final InputStream inputStream, final OutputStream outputStream)
- throws IOException {
+ public static long copyLarge(final InputStream inputStream, final OutputStream outputStream) throws IOException {
return copy(inputStream, outputStream, DEFAULT_BUFFER_SIZE);
}
/**
- * Copies bytes from a large (over 2GB) {@link InputStream} to an
- * {@link OutputStream}.
+ * Copies bytes from a large (over 2GB) {@link InputStream} to an {@link OutputStream}.
*
- * This method uses the provided buffer, so there is no need to use a
- * {@link BufferedInputStream}.
+ * This method uses the provided buffer, so there is no need to use a {@link BufferedInputStream}.
*
*
- * @param inputStream the {@link InputStream} to read.
+ * @param inputStream the {@link InputStream} to read.
* @param outputStream the {@link OutputStream} to write.
- * @param buffer the buffer to use for the copy
+ * @param buffer the buffer to use for the copy.
* @return the number of bytes copied.
* @throws NullPointerException if the InputStream is {@code null}.
* @throws NullPointerException if the OutputStream is {@code null}.
- * @throws IOException if an I/O error occurs.
+ * @throws IOException if an I/O error occurs.
* @since 2.2
*/
@SuppressWarnings("resource") // streams are closed by the caller.
- public static long copyLarge(final InputStream inputStream, final OutputStream outputStream, final byte[] buffer)
- throws IOException {
+ public static long copyLarge(final InputStream inputStream, final OutputStream outputStream, final byte[] buffer) throws IOException {
Objects.requireNonNull(inputStream, "inputStream");
Objects.requireNonNull(outputStream, "outputStream");
long count = 0;
@@ -1629,58 +1739,53 @@ public static long copyLarge(final InputStream inputStream, final OutputStream o
}
/**
- * Copies some or all bytes from a large (over 2GB) {@link InputStream} to an
- * {@link OutputStream}, optionally skipping input bytes.
+ * Copies some or all bytes from a large (over 2GB) {@link InputStream} to an {@link OutputStream}, optionally skipping input bytes.
*
- * This method buffers the input internally, so there is no need to use a
- * {@link BufferedInputStream}.
+ * This method buffers the input internally, so there is no need to use a {@link BufferedInputStream}.
*
*
- * Note that the implementation uses {@link #skip(InputStream, long)}.
- * This means that the method may be considerably less efficient than using the actual skip implementation,
- * this is done to guarantee that the correct number of characters are skipped.
+ * Note that the implementation uses {@link #skip(InputStream, long)}. This means that the method may be considerably less efficient than using the actual
+ * skip implementation, this is done to guarantee that the correct number of characters are skipped.
*
* The buffer size is given by {@link #DEFAULT_BUFFER_SIZE}.
*
- * @param input the {@link InputStream} to read.
- * @param output the {@link OutputStream} to write.
+ * @param input the {@link InputStream} to read.
+ * @param output the {@link OutputStream} to write.
* @param inputOffset number of bytes to skip from input before copying, these bytes are ignored.
- * @param length number of bytes to copy.
+ * @param length number of bytes to copy.
* @return the number of bytes copied.
* @throws NullPointerException if the input or output is null.
* @throws IOException if an I/O error occurs.
* @since 2.2
*/
- public static long copyLarge(final InputStream input, final OutputStream output, final long inputOffset,
- final long length) throws IOException {
- return copyLarge(input, output, inputOffset, length, getScratchByteArray());
+ public static long copyLarge(final InputStream input, final OutputStream output, final long inputOffset, final long length) throws IOException {
+ try (ScratchBytes scratch = ScratchBytes.get()) {
+ return copyLarge(input, output, inputOffset, length, scratch.array());
+ }
}
/**
- * Copies some or all bytes from a large (over 2GB) {@link InputStream} to an
- * {@link OutputStream}, optionally skipping input bytes.
+ * Copies some or all bytes from a large (over 2GB) {@link InputStream} to an {@link OutputStream}, optionally skipping input bytes.
*
- * This method uses the provided buffer, so there is no need to use a
- * {@link BufferedInputStream}.
+ * This method uses the provided buffer, so there is no need to use a {@link BufferedInputStream}.
*
*
- * Note that the implementation uses {@link #skip(InputStream, long)}.
- * This means that the method may be considerably less efficient than using the actual skip implementation,
- * this is done to guarantee that the correct number of characters are skipped.
+ * Note that the implementation uses {@link #skip(InputStream, long)}. This means that the method may be considerably less efficient than using the actual
+ * skip implementation, this is done to guarantee that the correct number of characters are skipped.
*
*
- * @param input the {@link InputStream} to read.
- * @param output the {@link OutputStream} to write.
+ * @param input the {@link InputStream} to read.
+ * @param output the {@link OutputStream} to write.
* @param inputOffset number of bytes to skip from input before copying, these bytes are ignored.
- * @param length number of bytes to copy.
- * @param buffer the buffer to use for the copy.
+ * @param length number of bytes to copy.
+ * @param buffer the buffer to use for the copy.
* @return the number of bytes copied.
* @throws NullPointerException if the input or output is null.
* @throws IOException if an I/O error occurs.
* @since 2.2
*/
- public static long copyLarge(final InputStream input, final OutputStream output,
- final long inputOffset, final long length, final byte[] buffer) throws IOException {
+ public static long copyLarge(final InputStream input, final OutputStream output, final long inputOffset, final long length, final byte[] buffer)
+ throws IOException {
if (inputOffset > 0) {
skipFully(input, inputOffset);
}
@@ -1708,8 +1813,7 @@ public static long copyLarge(final InputStream input, final OutputStream output,
/**
* Copies chars from a large (over 2GB) {@link Reader} to a {@link Writer}.
*
- * This method buffers the input internally, so there is no need to use a
- * {@link BufferedReader}.
+ * This method buffers the input internally, so there is no need to use a {@link BufferedReader}.
*
*
* The buffer size is given by {@link #DEFAULT_BUFFER_SIZE}.
@@ -1723,22 +1827,23 @@ public static long copyLarge(final InputStream input, final OutputStream output,
* @since 1.3
*/
public static long copyLarge(final Reader reader, final Writer writer) throws IOException {
- return copyLarge(reader, writer, getScratchCharArray());
+ try (ScratchChars scratch = IOUtils.ScratchChars.get()) {
+ return copyLarge(reader, writer, scratch.array());
+ }
}
/**
* Copies chars from a large (over 2GB) {@link Reader} to a {@link Writer}.
*
- * This method uses the provided buffer, so there is no need to use a
- * {@link BufferedReader}.
+ * This method uses the provided buffer, so there is no need to use a {@link BufferedReader}.
*
*
* @param reader the {@link Reader} to source.
* @param writer the {@link Writer} to target.
- * @param buffer the buffer to be used for the copy
- * @return the number of characters copied
- * @throws NullPointerException if the input or output is null
- * @throws IOException if an I/O error occurs
+ * @param buffer the buffer to be used for the copy.
+ * @return the number of characters copied.
+ * @throws NullPointerException if the input or output is null.
+ * @throws IOException if an I/O error occurs.
* @since 2.2
*/
public static long copyLarge(final Reader reader, final Writer writer, final char[] buffer) throws IOException {
@@ -1770,7 +1875,9 @@ public static long copyLarge(final Reader reader, final Writer writer, final cha
* @since 2.2
*/
public static long copyLarge(final Reader reader, final Writer writer, final long inputOffset, final long length) throws IOException {
- return copyLarge(reader, writer, inputOffset, length, getScratchCharArray());
+ try (ScratchChars scratch = IOUtils.ScratchChars.get()) {
+ return copyLarge(reader, writer, inputOffset, length, scratch.array());
+ }
}
/**
@@ -1817,84 +1924,18 @@ public static long copyLarge(final Reader reader, final Writer writer, final lon
* Copies up to {@code size} bytes from the given {@link InputStream} into a new {@link UnsynchronizedByteArrayOutputStream}.
*
* @param input The {@link InputStream} to read; must not be {@code null}.
- * @param limit The maximum number of bytes to read; must be {@code >= 0}.
- * The actual bytes read are validated to equal {@code size}.
+ * @param limit The maximum number of bytes to read; must be {@code >= 0}. The actual bytes read are validated to equal {@code size}.
* @param bufferSize The buffer size of the output stream; must be {@code > 0}.
* @return a ByteArrayOutputStream containing the read bytes.
*/
- static UnsynchronizedByteArrayOutputStream copyToOutputStream(
- final InputStream input, final long limit, final int bufferSize) throws IOException {
- try (UnsynchronizedByteArrayOutputStream output = UnsynchronizedByteArrayOutputStream.builder()
- .setBufferSize(bufferSize)
- .get();
- InputStream boundedInput = BoundedInputStream.builder()
- .setMaxCount(limit)
- .setPropagateClose(false)
- .setInputStream(input)
- .get()) {
+ static UnsynchronizedByteArrayOutputStream copyToOutputStream(final InputStream input, final long limit, final int bufferSize) throws IOException {
+ try (UnsynchronizedByteArrayOutputStream output = UnsynchronizedByteArrayOutputStream.builder().setBufferSize(bufferSize).get();
+ InputStream boundedInput = BoundedInputStream.builder().setMaxCount(limit).setPropagateClose(false).setInputStream(input).get()) {
output.write(boundedInput);
return output;
}
}
- /**
- * Fills the given array with 0s.
- *
- * @param arr The non-null array to fill.
- * @return The given array.
- */
- private static byte[] fill0(final byte[] arr) {
- Arrays.fill(arr, (byte) 0);
- return arr;
- }
-
- /**
- * Fills the given array with 0s.
- *
- * @param arr The non-null array to fill.
- * @return The given array.
- */
- private static char[] fill0(final char[] arr) {
- Arrays.fill(arr, (char) 0);
- return arr;
- }
-
- /**
- * Gets the internal byte array buffer, intended for both reading and writing.
- *
- * @return the internal byte array buffer, intended for both reading and writing.
- */
- static byte[] getScratchByteArray() {
- return fill0(SCRATCH_BYTE_BUFFER_RW.get());
- }
-
- /**
- * Gets the internal byte array intended for write only operations.
- *
- * @return the internal byte array intended for write only operations.
- */
- static byte[] getScratchByteArrayWriteOnly() {
- return fill0(SCRATCH_BYTE_BUFFER_WO);
- }
-
- /**
- * Gets the char byte array buffer, intended for both reading and writing.
- *
- * @return the char byte array buffer, intended for both reading and writing.
- */
- static char[] getScratchCharArray() {
- return fill0(SCRATCH_CHAR_BUFFER_RW.get());
- }
-
- /**
- * Gets the internal char array intended for write only operations.
- *
- * @return the internal char array intended for write only operations.
- */
- static char[] getScratchCharArrayWriteOnly() {
- return fill0(SCRATCH_CHAR_BUFFER_WO);
- }
-
/**
* Returns the length of the given array in a null-safe manner.
*
@@ -1940,31 +1981,29 @@ public static int length(final Object[] array) {
}
/**
- * Returns an Iterator for the lines in an {@link InputStream}, using
- * the character encoding specified (or default encoding if null).
+ * Returns an Iterator for the lines in an {@link InputStream}, using the character encoding specified (or default encoding if null).
*
- * {@link LineIterator} holds a reference to the open
- * {@link InputStream} specified here. When you have finished with
- * the iterator you should close the stream to free internal resources.
- * This can be done by using a try-with-resources block, closing the stream directly, or by calling
+ * {@link LineIterator} holds a reference to the open {@link InputStream} specified here. When you have finished with the iterator you should close the
+ * stream to free internal resources. This can be done by using a try-with-resources block, closing the stream directly, or by calling
* {@link LineIterator#close()}.
*
*
* The recommended usage pattern is:
*
+ *
*
* try {
- * LineIterator it = IOUtils.lineIterator(stream, charset);
- * while (it.hasNext()) {
- * String line = it.nextLine();
- * /// do something with line
- * }
+ * LineIterator it = IOUtils.lineIterator(stream, charset);
+ * while (it.hasNext()) {
+ * String line = it.nextLine();
+ * /// do something with line
+ * }
* } finally {
- * IOUtils.closeQuietly(stream);
+ * IOUtils.closeQuietly(stream);
* }
*
*
- * @param input the {@link InputStream} to read, not null.
+ * @param input the {@link InputStream} to read, not null.
* @param charset the charset to use, null means platform default.
* @return an Iterator of the lines in the reader, never null.
* @throws IllegalArgumentException if the input is null.
@@ -1975,31 +2014,29 @@ public static LineIterator lineIterator(final InputStream input, final Charset c
}
/**
- * Returns an Iterator for the lines in an {@link InputStream}, using
- * the character encoding specified (or default encoding if null).
+ * Returns an Iterator for the lines in an {@link InputStream}, using the character encoding specified (or default encoding if null).
*
- * {@link LineIterator} holds a reference to the open
- * {@link InputStream} specified here. When you have finished with
- * the iterator you should close the stream to free internal resources.
- * This can be done by using a try-with-resources block, closing the stream directly, or by calling
+ * {@link LineIterator} holds a reference to the open {@link InputStream} specified here. When you have finished with the iterator you should close the
+ * stream to free internal resources. This can be done by using a try-with-resources block, closing the stream directly, or by calling
* {@link LineIterator#close()}.
*
*
* The recommended usage pattern is:
*
+ *
*
* try {
- * LineIterator it = IOUtils.lineIterator(stream, StandardCharsets.UTF_8.name());
- * while (it.hasNext()) {
- * String line = it.nextLine();
- * /// do something with line
- * }
+ * LineIterator it = IOUtils.lineIterator(stream, StandardCharsets.UTF_8.name());
+ * while (it.hasNext()) {
+ * String line = it.nextLine();
+ * /// do something with line
+ * }
* } finally {
- * IOUtils.closeQuietly(stream);
+ * IOUtils.closeQuietly(stream);
* }
*
*
- * @param input the {@link InputStream} to read, not null.
+ * @param input the {@link InputStream} to read, not null.
* @param charsetName 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.
@@ -2013,24 +2050,22 @@ public static LineIterator lineIterator(final InputStream input, final String ch
/**
* Returns an Iterator for the lines in a {@link Reader}.
*
- * {@link LineIterator} holds a reference to the open
- * {@link Reader} specified here. When you have finished with the
- * iterator you should close the reader to free internal resources.
- * This can be done by using a try-with-resources block, closing the reader directly, or by calling
- * {@link LineIterator#close()}.
+ * {@link LineIterator} holds a reference to the open {@link Reader} specified here. When you have finished with the iterator you should close the reader to
+ * free internal resources. This can be done by using a try-with-resources block, closing the reader directly, or by calling {@link LineIterator#close()}.
*
*
* The recommended usage pattern is:
*
+ *
*
* try {
- * LineIterator it = IOUtils.lineIterator(reader);
- * while (it.hasNext()) {
- * String line = it.nextLine();
- * /// do something with line
- * }
+ * LineIterator it = IOUtils.lineIterator(reader);
+ * while (it.hasNext()) {
+ * String line = it.nextLine();
+ * /// do something with line
+ * }
* } finally {
- * IOUtils.closeQuietly(reader);
+ * IOUtils.closeQuietly(reader);
* }
*
*
@@ -2046,15 +2081,15 @@ public static LineIterator lineIterator(final Reader reader) {
/**
* Reads bytes from an input stream.
*
- * This implementation guarantees that it will read as many bytes
- * as possible before giving up; this may not always be the case for
- * subclasses of {@link InputStream}.
+ * This implementation guarantees that it will read as many bytes as possible before giving up; this may not always be the case for subclasses of
+ * {@link InputStream}.
*
*
- * @param input where to read input from.
+ * @param input where to read input from.
* @param buffer destination.
* @return actual length read; may be less than requested if EOF was reached.
- * @throws IOException if a read error occurs.
+ * @throws NullPointerException if {@code input} or {@code buffer} is null.
+ * @throws IOException if a read error occurs.
* @since 2.2
*/
public static int read(final InputStream input, final byte[] buffer) throws IOException {
@@ -2064,50 +2099,26 @@ public static int read(final InputStream input, final byte[] buffer) throws IOEx
/**
* Reads bytes from an input stream.
*
- * This implementation guarantees that it will read as many bytes
- * as possible before giving up; this may not always be the case for
- * subclasses of {@link InputStream}.
+ * This implementation guarantees that it will read as many bytes as possible before giving up; this may not always be the case for subclasses of
+ * {@link InputStream}.
*
*
- * @param input where to read input.
- * @param buffer destination.
- * @param offset initial offset into buffer.
- * @param length length to read, must be >= 0.
- * @return actual length read; may be less than requested if EOF was reached.
- * @throws IllegalArgumentException if length is negative.
- * @throws IOException if a read error occurs.
- * @since 2.2
- */
- public static int read(final InputStream input, final byte[] buffer, final int offset, final int length)
- throws IOException {
- if (length == 0) {
- return 0;
- }
- return read(input::read, buffer, offset, length);
- }
-
- /**
- * Reads bytes from an input. This implementation guarantees that it will read as many bytes as possible before giving up; this may not always be the case
- * for subclasses of {@link InputStream}.
- *
- * @param input How to read input.
+ * @param input where to read input.
* @param buffer destination.
* @param offset initial offset into buffer.
* @param length length to read, must be >= 0.
* @return actual length read; may be less than requested if EOF was reached.
- * @throws IllegalArgumentException if length is negative.
- * @throws IOException if a read error occurs.
+ * @throws NullPointerException if {@code input} or {@code buffer} is null.
+ * @throws IndexOutOfBoundsException if {@code offset} or {@code length} is negative, or if {@code offset + length} is greater than {@code buffer.length}.
+ * @throws IOException if a read error occurs.
* @since 2.2
*/
- static int read(final IOTriFunction input, final byte[] buffer, final int offset, final int length)
- throws IOException {
- if (length < 0) {
- throw new IllegalArgumentException("Length must not be negative: " + length);
- }
+ public static int read(final InputStream input, final byte[] buffer, final int offset, final int length) throws IOException {
+ checkFromIndexSize(buffer, offset, length);
int remaining = length;
while (remaining > 0) {
final int location = length - remaining;
- final int count = input.apply(buffer, offset + location, remaining);
+ final int count = input.read(buffer, offset + location, remaining);
if (EOF == count) {
break;
}
@@ -2119,12 +2130,11 @@ static int read(final IOTriFunction input, fi
/**
* Reads bytes from a ReadableByteChannel.
*
- * This implementation guarantees that it will read as many bytes
- * as possible before giving up; this may not always be the case for
- * subclasses of {@link ReadableByteChannel}.
+ * This implementation guarantees that it will read as many bytes as possible before giving up; this may not always be the case for subclasses of
+ * {@link ReadableByteChannel}.
*
*
- * @param input the byte channel to read.
+ * @param input the byte channel to read.
* @param buffer byte buffer destination.
* @return the actual length read; may be less than requested if EOF was reached.
* @throws IOException if a read error occurs.
@@ -2144,9 +2154,8 @@ public static int read(final ReadableByteChannel input, final ByteBuffer buffer)
/**
* Reads characters from an input character stream.
*
- * This implementation guarantees that it will read as many characters
- * as possible before giving up; this may not always be the case for
- * subclasses of {@link Reader}.
+ * This implementation guarantees that it will read as many characters as possible before giving up; this may not always be the case for subclasses of
+ * {@link Reader}.
*
*
* @param reader where to read input from.
@@ -2162,9 +2171,8 @@ public static int read(final Reader reader, final char[] buffer) throws IOExcept
/**
* Reads characters from an input character stream.
*
- * This implementation guarantees that it will read as many characters
- * as possible before giving up; this may not always be the case for
- * subclasses of {@link Reader}.
+ * This implementation guarantees that it will read as many characters as possible before giving up; this may not always be the case for subclasses of
+ * {@link Reader}.
*
*
* @param reader where to read input from.
@@ -2172,15 +2180,13 @@ public static int read(final Reader reader, final char[] buffer) throws IOExcept
* @param offset initial offset into buffer.
* @param length length to read, must be >= 0.
* @return actual length read; may be less than requested if EOF was reached.
- * @throws IllegalArgumentException if length is negative.
- * @throws IOException if a read error occurs.
+ * @throws NullPointerException if {@code reader} or {@code buffer} is null.
+ * @throws IndexOutOfBoundsException if {@code offset} or {@code length} is negative, or if {@code offset + length} is greater than {@code buffer.length}.
+ * @throws IOException if a read error occurs.
* @since 2.2
*/
- public static int read(final Reader reader, final char[] buffer, final int offset, final int length)
- throws IOException {
- if (length < 0) {
- throw new IllegalArgumentException("Length must not be negative: " + length);
- }
+ public static int read(final Reader reader, final char[] buffer, final int offset, final int length) throws IOException {
+ checkFromIndexSize(buffer, offset, length);
int remaining = length;
while (remaining > 0) {
final int location = length - remaining;
@@ -2196,15 +2202,15 @@ public static int read(final Reader reader, final char[] buffer, final int offse
/**
* Reads the requested number of bytes or fail if there are not enough left.
*
- * This allows for the possibility that {@link InputStream#read(byte[], int, int)} may
- * not read as many bytes as requested (most likely because of reaching EOF).
+ * This allows for the possibility that {@link InputStream#read(byte[], int, int)} may not read as many bytes as requested (most likely because of reaching
+ * EOF).
*
*
- * @param input where to read input from.
+ * @param input where to read input from.
* @param buffer destination.
- * @throws IOException if there is a problem reading the file.
- * @throws IllegalArgumentException if length is negative.
- * @throws EOFException if the number of bytes read was incorrect.
+ * @throws NullPointerException if {@code input} or {@code buffer} is null.
+ * @throws EOFException if the number of bytes read was incorrect.
+ * @throws IOException if there is a problem reading the file.
* @since 2.2
*/
public static void readFully(final InputStream input, final byte[] buffer) throws IOException {
@@ -2214,21 +2220,21 @@ public static void readFully(final InputStream input, final byte[] buffer) throw
/**
* Reads the requested number of bytes or fail if there are not enough left.
*
- * This allows for the possibility that {@link InputStream#read(byte[], int, int)} may
- * not read as many bytes as requested (most likely because of reaching EOF).
+ * This allows for the possibility that {@link InputStream#read(byte[], int, int)} may not read as many bytes as requested (most likely because of reaching
+ * EOF).
*
*
- * @param input where to read input from.
+ * @param input where to read input from.
* @param buffer destination.
* @param offset initial offset into buffer.
* @param length length to read, must be >= 0.
- * @throws IOException if there is a problem reading the file.
- * @throws IllegalArgumentException if length is negative.
- * @throws EOFException if the number of bytes read was incorrect.
+ * @throws NullPointerException if {@code input} or {@code buffer} is null.
+ * @throws IndexOutOfBoundsException if {@code offset} or {@code length} is negative, or if {@code offset + length} is greater than {@code buffer.length}.
+ * @throws EOFException if the number of bytes read was incorrect.
+ * @throws IOException if there is a problem reading the file.
* @since 2.2
*/
- public static void readFully(final InputStream input, final byte[] buffer, final int offset, final int length)
- throws IOException {
+ public static void readFully(final InputStream input, final byte[] buffer, final int offset, final int length) throws IOException {
final int actual = read(input, buffer, offset, length);
if (actual != length) {
throw new EOFException("Length to read: " + length + " actual: " + actual);
@@ -2238,11 +2244,11 @@ public static void readFully(final InputStream input, final byte[] buffer, final
/**
* Reads the requested number of bytes or fail if there are not enough left.
*
- * This allows for the possibility that {@link InputStream#read(byte[], int, int)} may
- * not read as many bytes as requested (most likely because of reaching EOF).
+ * This allows for the possibility that {@link InputStream#read(byte[], int, int)} may not read as many bytes as requested (most likely because of reaching
+ * EOF).
*
*
- * @param input where to read input from.
+ * @param input where to read input from.
* @param length length to read, must be >= 0.
* @return the bytes read from input.
* @throws IOException if there is a problem reading the file.
@@ -2259,11 +2265,11 @@ public static byte[] readFully(final InputStream input, final int length) throws
/**
* Reads the requested number of bytes or fail if there are not enough left.
*
- * This allows for the possibility that {@link ReadableByteChannel#read(ByteBuffer)} may
- * not read as many bytes as requested (most likely because of reaching EOF).
+ * This allows for the possibility that {@link ReadableByteChannel#read(ByteBuffer)} may not read as many bytes as requested (most likely because of
+ * reaching EOF).
*
*
- * @param input the byte channel to read.
+ * @param input the byte channel to read.
* @param buffer byte buffer destination.
* @throws IOException if there is a problem reading the file.
* @throws EOFException if the number of bytes read was incorrect.
@@ -2280,15 +2286,15 @@ public static void readFully(final ReadableByteChannel input, final ByteBuffer b
/**
* Reads the requested number of characters or fail if there are not enough left.
*
- * This allows for the possibility that {@link Reader#read(char[], int, int)} may
- * not read as many characters as requested (most likely because of reaching EOF).
+ * This allows for the possibility that {@link Reader#read(char[], int, int)} may not read as many characters as requested (most likely because of reaching
+ * EOF).
*
*
* @param reader where to read input from.
* @param buffer destination.
- * @throws IOException if there is a problem reading the file.
- * @throws IllegalArgumentException if length is negative.
- * @throws EOFException if the number of characters read was incorrect.
+ * @throws NullPointerException if {@code reader} or {@code buffer} is null.
+ * @throws EOFException if the number of characters read was incorrect.
+ * @throws IOException if there is a problem reading the file.
* @since 2.2
*/
public static void readFully(final Reader reader, final char[] buffer) throws IOException {
@@ -2298,21 +2304,21 @@ public static void readFully(final Reader reader, final char[] buffer) throws IO
/**
* Reads the requested number of characters or fail if there are not enough left.
*
- * This allows for the possibility that {@link Reader#read(char[], int, int)} may
- * not read as many characters as requested (most likely because of reaching EOF).
+ * This allows for the possibility that {@link Reader#read(char[], int, int)} may not read as many characters as requested (most likely because of reaching
+ * EOF).
*
*
* @param reader where to read input from.
* @param buffer destination.
* @param offset initial offset into buffer.
* @param length length to read, must be >= 0.
- * @throws IOException if there is a problem reading the file.
- * @throws IllegalArgumentException if length is negative.
- * @throws EOFException if the number of characters read was incorrect.
+ * @throws NullPointerException if {@code reader} or {@code buffer} is null.
+ * @throws IndexOutOfBoundsException if {@code offset} or {@code length} is negative, or if {@code offset + length} is greater than {@code buffer.length}.
+ * @throws EOFException if the number of characters read was incorrect.
+ * @throws IOException if there is a problem reading the file.
* @since 2.2
*/
- public static void readFully(final Reader reader, final char[] buffer, final int offset, final int length)
- throws IOException {
+ public static void readFully(final Reader reader, final char[] buffer, final int offset, final int length) throws IOException {
final int actual = read(reader, buffer, offset, length);
if (actual != length) {
throw new EOFException("Length to read: " + length + " actual: " + actual);
@@ -2334,11 +2340,10 @@ public static List readLines(final CharSequence csq) throws UncheckedIOE
}
/**
- * Gets the contents of an {@link InputStream} as a list of Strings,
- * one entry per line, using the virtual machine's {@link Charset#defaultCharset() default charset}.
+ * Gets the contents of an {@link InputStream} as a list of Strings, one entry per line, using the virtual machine's {@linkplain Charset#defaultCharset()
+ * default charset}.
*
- * This method buffers the input internally, so there is no need to use a
- * {@link BufferedInputStream}.
+ * This method buffers the input internally, so there is no need to use a {@link BufferedInputStream}.
*
*
* @param input the {@link InputStream} to read, not null.
@@ -2346,7 +2351,7 @@ public static List readLines(final CharSequence csq) throws UncheckedIOE
* @throws NullPointerException if the input is null.
* @throws UncheckedIOException if an I/O error occurs.
* @since 1.1
- * @deprecated Use {@link #readLines(InputStream, Charset)} instead
+ * @deprecated Use {@link #readLines(InputStream, Charset)} instead.
*/
@Deprecated
public static List readLines(final InputStream input) throws UncheckedIOException {
@@ -2354,14 +2359,12 @@ public static List readLines(final InputStream input) throws UncheckedIO
}
/**
- * Gets the contents of an {@link InputStream} as a list of Strings,
- * one entry per line, using the specified character encoding.
+ * Gets the contents of an {@link InputStream} as a list of Strings, one entry per line, using the specified character encoding.
*
- * This method buffers the input internally, so there is no need to use a
- * {@link BufferedInputStream}.
+ * This method buffers the input internally, so there is no need to use a {@link BufferedInputStream}.
*
*
- * @param input the {@link InputStream} to read, not null.
+ * @param input the {@link InputStream} to read, not null.
* @param charset the charset to use, null means platform default.
* @return the list of Strings, never null.
* @throws NullPointerException if the input is null.
@@ -2373,18 +2376,15 @@ public static List readLines(final InputStream input, final Charset char
}
/**
- * Gets the contents of an {@link InputStream} as a list of Strings,
- * one entry per line, using the specified character encoding.
+ * Gets the contents of an {@link InputStream} as a list of Strings, one entry per line, using the specified character encoding.
*
- * Character encoding names can be found at
- * IANA.
+ * Character encoding names can be found at IANA.
*
*
- * This method buffers the input internally, so there is no need to use a
- * {@link BufferedInputStream}.
+ * This method buffers the input internally, so there is no need to use a {@link BufferedInputStream}.
*
*
- * @param input the {@link InputStream} to read, not null.
+ * @param input the {@link InputStream} to read, not null.
* @param charsetName the name of the requested charset, null means platform default.
* @return the list of Strings, never null.
* @throws NullPointerException if the input is null.
@@ -2397,11 +2397,9 @@ public static List readLines(final InputStream input, final String chars
}
/**
- * Gets the contents of a {@link Reader} as a list of Strings,
- * one entry per line.
+ * Gets the contents of a {@link Reader} as a list of Strings, one entry per line.
*
- * This method buffers the input internally, so there is no need to use a
- * {@link BufferedReader}.
+ * This method buffers the input internally, so there is no need to use a {@link BufferedReader}.
*
*
* @param reader the {@link Reader} to read, not null.
@@ -2437,7 +2435,7 @@ public static byte[] resourceToByteArray(final String name) throws IOException {
* Delegates to {@link #resourceToURL(String, ClassLoader)}.
*
*
- * @param name The resource name.
+ * @param name The resource name.
* @param classLoader the class loader that the resolution of the resource is delegated to.
* @return the requested byte array.
* @throws IOException if an I/O error occurs or the resource is not found.
@@ -2454,7 +2452,7 @@ public static byte[] resourceToByteArray(final String name, final ClassLoader cl
* Delegates to {@link #resourceToString(String, Charset, ClassLoader) resourceToString(String, Charset, null)}.
*
*
- * @param name The resource name.
+ * @param name The resource name.
* @param charset the charset to use, null means platform default.
* @return the requested String.
* @throws IOException if an I/O error occurs or the resource is not found.
@@ -2471,8 +2469,8 @@ public static String resourceToString(final String name, final Charset charset)
* Delegates to {@link #resourceToURL(String, ClassLoader)}.
*
*
- * @param name The resource name.
- * @param charset the Charset to use, null means platform default.
+ * @param name The resource name.
+ * @param charset the Charset to use, null means platform default.
* @param classLoader the class loader that the resolution of the resource is delegated to.
* @return the requested String.
* @throws IOException if an I/O error occurs.
@@ -2501,11 +2499,11 @@ public static URL resourceToURL(final String name) throws IOException {
/**
* Gets a URL pointing to the given resource.
*
- * If the {@code classLoader} is not null, call {@link ClassLoader#getResource(String)}, otherwise call
- * {@link Class#getResource(String) IOUtils.class.getResource(name)}.
+ * If the {@code classLoader} is not null, call {@link ClassLoader#getResource(String)}, otherwise call {@link Class#getResource(String)
+ * IOUtils.class.getResource(name)}.
*
*
- * @param name The resource name.
+ * @param name The resource name.
* @param classLoader Delegate to this class loader if not null.
* @return A URL object for reading the resource.
* @throws IOException if the resource is not found.
@@ -2543,7 +2541,9 @@ public static URL resourceToURL(final String name, final ClassLoader classLoader
* @since 2.0
*/
public static long skip(final InputStream input, final long skip) throws IOException {
- return skip(input, skip, IOUtils::getScratchByteArrayWriteOnly);
+ try (ScratchBytes scratch = ScratchBytes.get()) {
+ return skip(input, skip, scratch::array);
+ }
}
/**
@@ -2563,7 +2563,7 @@ public static long skip(final InputStream input, final long skip) throws IOExcep
*
*
* @param input byte stream to skip.
- * @param skip number of bytes to skip.
+ * @param skip number of bytes to skip.
* @param skipBufferSupplier Supplies the buffer to use for reading.
* @return number of bytes actually skipped.
* @throws IOException if there is a problem reading the file.
@@ -2595,11 +2595,9 @@ public static long skip(final InputStream input, final long skip, final Supplier
}
/**
- * Skips bytes from a ReadableByteChannel.
- * This implementation guarantees that it will read as many bytes
- * as possible before giving up.
+ * Skips bytes from a ReadableByteChannel. This implementation guarantees that it will read as many bytes as possible before giving up.
*
- * @param input ReadableByteChannel to skip.
+ * @param input ReadableByteChannel to skip.
* @param toSkip number of bytes to skip.
* @return number of bytes actually skipped.
* @throws IOException if there is a problem reading the ReadableByteChannel.
@@ -2625,15 +2623,12 @@ public static long skip(final ReadableByteChannel input, final long toSkip) thro
}
/**
- * Skips characters from an input character stream.
- * This implementation guarantees that it will read as many characters
- * as possible before giving up; this may not always be the case for
- * skip() implementations in subclasses of {@link Reader}.
+ * Skips characters from an input character stream. This implementation guarantees that it will read as many characters as possible before giving up; this
+ * may not always be the case for skip() implementations in subclasses of {@link Reader}.
*
- * Note that the implementation uses {@link Reader#read(char[], int, int)} rather
- * than delegating to {@link Reader#skip(long)}.
- * This means that the method may be considerably less efficient than using the actual skip implementation,
- * this is done to guarantee that the correct number of characters are skipped.
+ * Note that the implementation uses {@link Reader#read(char[], int, int)} rather than delegating to {@link Reader#skip(long)}. This means that the method
+ * may be considerably less efficient than using the actual skip implementation, this is done to guarantee that the correct number of characters are
+ * skipped.
*
*
* @param reader character stream to skip.
@@ -2650,14 +2645,16 @@ public static long skip(final Reader reader, final long toSkip) throws IOExcepti
throw new IllegalArgumentException("Skip count must be non-negative, actual: " + toSkip);
}
long remain = toSkip;
- while (remain > 0) {
- // See https://issues.apache.org/jira/browse/IO-203 for why we use read() rather than delegating to skip()
- final char[] charArray = getScratchCharArrayWriteOnly();
- final long n = reader.read(charArray, 0, (int) Math.min(remain, charArray.length));
- if (n < 0) { // EOF
- break;
+ try (ScratchChars scratch = IOUtils.ScratchChars.get()) {
+ final char[] chars = scratch.array();
+ while (remain > 0) {
+ // See https://issues.apache.org/jira/browse/IO-203 for why we use read() rather than delegating to skip()
+ final long n = reader.read(chars, 0, (int) Math.min(remain, chars.length));
+ if (n < 0) { // EOF
+ break;
+ }
+ remain -= n;
}
- remain -= n;
}
return toSkip - remain;
}
@@ -2665,16 +2662,14 @@ public static long skip(final Reader reader, final long toSkip) throws IOExcepti
/**
* Skips the requested number of bytes or fail if there are not enough left.
*
- * This allows for the possibility that {@link InputStream#skip(long)} may
- * not skip as many bytes as requested (most likely because of reaching EOF).
+ * This allows for the possibility that {@link InputStream#skip(long)} may not skip as many bytes as requested (most likely because of reaching EOF).
*
*
- * Note that the implementation uses {@link #skip(InputStream, long)}.
- * This means that the method may be considerably less efficient than using the actual skip implementation,
- * this is done to guarantee that the correct number of characters are skipped.
+ * Note that the implementation uses {@link #skip(InputStream, long)}. This means that the method may be considerably less efficient than using the actual
+ * skip implementation, this is done to guarantee that the correct number of characters are skipped.
*
*
- * @param input stream to skip.
+ * @param input stream to skip.
* @param toSkip the number of bytes to skip.
* @throws IOException if there is a problem reading the file.
* @throws IllegalArgumentException if toSkip is negative.
@@ -2683,7 +2678,7 @@ public static long skip(final Reader reader, final long toSkip) throws IOExcepti
* @since 2.0
*/
public static void skipFully(final InputStream input, final long toSkip) throws IOException {
- final long skipped = skip(input, toSkip, IOUtils::getScratchByteArrayWriteOnly);
+ final long skipped = skip(input, toSkip);
if (skipped != toSkip) {
throw new EOFException("Bytes to skip: " + toSkip + " actual: " + skipped);
}
@@ -2725,7 +2720,7 @@ public static void skipFully(final InputStream input, final long toSkip, final S
/**
* Skips the requested number of bytes or fail if there are not enough left.
*
- * @param input ReadableByteChannel to skip.
+ * @param input ReadableByteChannel to skip.
* @param toSkip the number of bytes to skip.
* @throws IOException if there is a problem reading the ReadableByteChannel.
* @throws IllegalArgumentException if toSkip is negative.
@@ -2745,13 +2740,11 @@ public static void skipFully(final ReadableByteChannel input, final long toSkip)
/**
* Skips the requested number of characters or fail if there are not enough left.
*
- * This allows for the possibility that {@link Reader#skip(long)} may
- * not skip as many characters as requested (most likely because of reaching EOF).
+ * This allows for the possibility that {@link Reader#skip(long)} may not skip as many characters as requested (most likely because of reaching EOF).
*
*
- * Note that the implementation uses {@link #skip(Reader, long)}.
- * This means that the method may be considerably less efficient than using the actual skip implementation,
- * this is done to guarantee that the correct number of characters are skipped.
+ * Note that the implementation uses {@link #skip(Reader, long)}. This means that the method may be considerably less efficient than using the actual skip
+ * implementation, this is done to guarantee that the correct number of characters are skipped.
*
*
* @param reader stream to skip.
@@ -2780,7 +2773,9 @@ public static void skipFully(final Reader reader, final long toSkip) throws IOEx
* It has network timeout associated.
*
*
- * It can be used in favor of {@link #toByteArray(InputStream)}, since it avoids unnecessary allocation and copy of byte[].
+ * It can be used in favor of {@link #toByteArray(InputStream)}, since it avoids unnecessary allocation and copy of byte[].
+ *
+ *
* This method buffers the input internally, so there is no need to use a {@link BufferedInputStream}.
*
*
@@ -2804,7 +2799,9 @@ public static InputStream toBufferedInputStream(final InputStream input) throws
* It has network timeout associated.
*
*
- * It can be used in favor of {@link #toByteArray(InputStream)}, since it avoids unnecessary allocation and copy of byte[].
+ * It can be used in favor of {@link #toByteArray(InputStream)}, since it avoids unnecessary allocation and copy of byte[].
+ *
+ *
* This method buffers the input internally, so there is no need to use a {@link BufferedInputStream}.
*
*
@@ -2819,8 +2816,7 @@ public static InputStream toBufferedInputStream(final InputStream input, final i
}
/**
- * Returns the given reader if it is a {@link BufferedReader}, otherwise creates a BufferedReader from the given
- * reader.
+ * Returns the given reader if it is a {@link BufferedReader}, otherwise creates a BufferedReader from the given reader.
*
* @param reader the reader to wrap or return (not null).
* @return the given reader or a new {@link BufferedReader} for the given reader.
@@ -2833,11 +2829,10 @@ public static BufferedReader toBufferedReader(final Reader reader) {
}
/**
- * Returns the given reader if it is a {@link BufferedReader}, otherwise creates a BufferedReader from the given
- * reader.
+ * 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 size the buffer size, if a new BufferedReader is created.
+ * @param size the buffer size, if a new BufferedReader is created.
* @return the given reader or a new {@link BufferedReader} for the given reader.
* @throws NullPointerException if the input parameter is null.
* @see #buffer(Reader)
@@ -2849,16 +2844,15 @@ public static BufferedReader toBufferedReader(final Reader reader, final int siz
/**
* Reads all the bytes from an input stream in a byte array.
- *
- * The memory used by this method is proportional to the number
- * of bytes read, which is only limited by {@link Integer#MAX_VALUE}. Only streams
- * which fit into a single byte array with roughly 2 GiB limit can be processed
- * with this method.
+ *
+ * The memory used by this method is proportional to the number of bytes read, which is only limited by {@link Integer#MAX_VALUE}. Only
+ * streams which fit into a single byte array with roughly 2 GiB limit can be processed with this method.
+ *
*
* @param inputStream The {@link InputStream} to read; must not be {@code null}.
* @return A new byte array.
- * @throws IOException If an I/O error occurs while reading or if the maximum array size is exceeded.
- * @throws NullPointerException If {@code inputStream} is {@code null}.
+ * @throws IOException If an I/O error occurs while reading or if the maximum array size is exceeded.
+ * @throws NullPointerException If {@code inputStream} is {@code null}.
*/
public static byte[] toByteArray(final InputStream inputStream) throws IOException {
// Using SOFT_MAX_ARRAY_LENGTH guarantees that size() will not overflow
@@ -2871,10 +2865,10 @@ public static byte[] toByteArray(final InputStream inputStream) throws IOExcepti
/**
* Reads exactly {@code size} bytes from the given {@link InputStream} into a new {@code byte[]}.
- *
- * This variant always allocates the whole requested array size,
- * for a dynamic growing variant use {@link #toByteArray(InputStream, int, int)},
- * which enforces stricter memory usage constraints.
+ *
+ * This variant always allocates the whole requested array size, for a dynamic growing variant use {@link #toByteArray(InputStream, int, int)}, which
+ * enforces stricter memory usage constraints.
+ *
*
* @param input the {@link InputStream} to read; must not be {@code null}.
* @param size the exact number of bytes to read; must be {@code >= 0}.
@@ -2891,19 +2885,17 @@ public static byte[] toByteArray(final InputStream input, final int size) throws
/**
* Reads exactly {@code size} bytes from the given {@link InputStream} into a new {@code byte[]}.
+ *
+ * The memory used by this method is proportional to the number of bytes read and limited by the specified {@code size}. This makes it
+ * suitable for processing large input streams, provided that sufficient heap space is available.
+ *
+ *
+ * This method processes the input stream in successive chunks of up to {@code chunkSize} bytes.
+ *
*
- * The memory used by this method is proportional to the number
- * of bytes read and limited by the specified {@code size}. This makes it suitable for
- * processing large input streams, provided that sufficient heap space is
- * available.
- *
- * This method processes the input stream in successive chunks of up to
- * {@code chunkSize} bytes.
- *
- * @param input the {@link InputStream} to read; must not be {@code null}.
- * @param size the exact number of bytes to read; must be {@code >= 0}.
- * The actual bytes read are validated to equal {@code size}.
- * @param chunkSize The chunk size for incremental reading; must be {@code > 0}.
+ * @param input the {@link InputStream} to read; must not be {@code null}.
+ * @param size the exact number of bytes to read; must be {@code >= 0}. The actual bytes read are validated to equal {@code size}.
+ * @param chunkSize The chunk size for incremental reading; must be {@code > 0}.
* @return a new byte array of length {@code size}.
* @throws IllegalArgumentException if {@code size} is negative or {@code chunkSize <= 0}.
* @throws EOFException if the stream ends before {@code size} bytes are read.
@@ -2914,25 +2906,26 @@ public static byte[] toByteArray(final InputStream input, final int size) throws
public static byte[] toByteArray(final InputStream input, final int size, final int chunkSize) throws IOException {
Objects.requireNonNull(input, "input");
if (chunkSize <= 0) {
- throw new IllegalArgumentException("Chunk size must be greater than zero: " + chunkSize);
+ throw new IllegalArgumentException(String.format("chunkSize <= 0, chunkSize = %,d", chunkSize));
}
if (size <= chunkSize) {
// throws if size < 0
return toByteArray(input::read, size);
}
final UnsynchronizedByteArrayOutputStream output = copyToOutputStream(input, size, chunkSize);
- if (output.size() != size) {
- throw new EOFException("Unexpected read size, current: " + output.size() + ", expected: " + size);
+ final int outSize = output.size();
+ if (outSize != size) {
+ throw new EOFException(String.format("Expected read size: %,d, actual: %,d", size, outSize));
}
return output.toByteArray();
}
/**
* Reads exactly {@code size} bytes from the given {@link InputStream} into a new {@code byte[]}.
- *
- * This variant always allocates the whole requested array size,
- * for a dynamic growing variant use {@link #toByteArray(InputStream, int, int)},
- * which enforces stricter memory usage constraints.
+ *
+ * This variant always allocates the whole requested array size, for a dynamic growing variant use {@link #toByteArray(InputStream, int, int)}, which
+ * enforces stricter memory usage constraints.
+ *
*
* @param input the {@link InputStream} to read; must not be {@code null}.
* @param size the exact number of bytes to read; must be {@code >= 0} and {@code <= Integer.MAX_VALUE}.
@@ -2946,7 +2939,7 @@ public static byte[] toByteArray(final InputStream input, final int size, final
*/
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);
+ throw new IllegalArgumentException(String.format("size > Integer.MAX_VALUE, size = %,d", size));
}
return toByteArray(input, (int) size);
}
@@ -2955,14 +2948,15 @@ public static byte[] toByteArray(final InputStream input, final long size) throw
* Gets the contents of an input as a {@code byte[]}.
*
* @param input the input to read, not null.
- * @param size the size of the input to read, where 0 < {@code size} <= length of input.
+ * @param size the size of the input to read, where 0 < {@code size} <= length of input.
* @return byte [] of length {@code size}.
- * @throws IOException if an I/O error occurs or input length is smaller than parameter {@code size}.
+ * @throws EOFException if the end of the input is reached before reading {@code size} bytes.
+ * @throws IOException if an I/O error occurs or input length is smaller than parameter {@code size}.
* @throws IllegalArgumentException if {@code size} is less than zero.
*/
static byte[] toByteArray(final IOTriFunction input, final int size) throws IOException {
if (size < 0) {
- throw new IllegalArgumentException("Size must be equal or greater than zero: " + size);
+ throw new IllegalArgumentException(String.format("size < 0, size = %,d", size));
}
if (size == 0) {
return EMPTY_BYTE_ARRAY;
@@ -2974,17 +2968,15 @@ static byte[] toByteArray(final IOTriFunction
offset += read;
}
if (offset != size) {
- throw new IOException("Unexpected read size, current: " + offset + ", expected: " + size);
+ throw new EOFException(String.format("Expected read size: %,d, actual: %,d", size, offset));
}
return data;
}
/**
- * Gets the contents of a {@link Reader} as a {@code byte[]}
- * using the virtual machine's {@link Charset#defaultCharset() default charset}.
+ * Gets the contents of a {@link Reader} as a {@code byte[]} using the virtual machine's {@linkplain Charset#defaultCharset() default charset}.
*
- * This method buffers the input internally, so there is no need to use a
- * {@link BufferedReader}.
+ * This method buffers the input internally, so there is no need to use a {@link BufferedReader}.
*
*
* @param reader the {@link Reader} to read.
@@ -2999,14 +2991,12 @@ public static byte[] toByteArray(final Reader reader) throws IOException {
}
/**
- * Gets the contents of a {@link Reader} as a {@code byte[]}
- * using the specified character encoding.
+ * Gets the contents of a {@link Reader} as a {@code byte[]} using the specified character encoding.
*
- * This method buffers the input internally, so there is no need to use a
- * {@link BufferedReader}.
+ * This method buffers the input internally, so there is no need to use a {@link BufferedReader}.
*
*
- * @param reader the {@link Reader} to read.
+ * @param reader the {@link Reader} to read.
* @param charset the charset to use, null means platform default.
* @return the requested byte array.
* @throws NullPointerException if the input is null.
@@ -3021,18 +3011,15 @@ public static byte[] toByteArray(final Reader reader, final Charset charset) thr
}
/**
- * Gets the contents of a {@link Reader} as a {@code byte[]}
- * using the specified character encoding.
+ * Gets the contents of a {@link Reader} as a {@code byte[]} using the specified character encoding.
*
- * Character encoding names can be found at
- * IANA.
+ * Character encoding names can be found at IANA.
*
*
- * This method buffers the input internally, so there is no need to use a
- * {@link BufferedReader}.
+ * This method buffers the input internally, so there is no need to use a {@link BufferedReader}.
*
*
- * @param reader the {@link Reader} to read.
+ * @param reader the {@link Reader} to read.
* @param charsetName the name of the requested charset, null means platform default.
* @return the requested byte array.
* @throws NullPointerException if the input is null.
@@ -3045,8 +3032,7 @@ public static byte[] toByteArray(final Reader reader, final String charsetName)
}
/**
- * Gets the contents of a {@link String} as a {@code byte[]}
- * using the virtual machine's {@link Charset#defaultCharset() default charset}.
+ * Gets the contents of a {@link String} as a {@code byte[]} using the virtual machine's {@linkplain Charset#defaultCharset() default charset}.
*
* This is the same as {@link String#getBytes()}.
*
@@ -3096,7 +3082,7 @@ public static byte[] toByteArray(final URL url) throws IOException {
* @param urlConnection the {@link URLConnection} to read.
* @return the requested byte array.
* @throws NullPointerException if the urlConn is null.
- * @throws IOException if an I/O exception occurs.
+ * @throws IOException if an I/O exception occurs.
* @since 2.4
*/
public static byte[] toByteArray(final URLConnection urlConnection) throws IOException {
@@ -3106,11 +3092,9 @@ public static byte[] toByteArray(final URLConnection urlConnection) throws IOExc
}
/**
- * Gets the contents of an {@link InputStream} as a character array
- * using the virtual machine's {@link Charset#defaultCharset() default charset}.
+ * Gets the contents of an {@link InputStream} as a character array using the virtual machine's {@linkplain Charset#defaultCharset() default charset}.
*
- * This method buffers the input internally, so there is no need to use a
- * {@link BufferedInputStream}.
+ * This method buffers the input internally, so there is no need to use a {@link BufferedInputStream}.
*
*
* @param inputStream the {@link InputStream} to read.
@@ -3118,7 +3102,7 @@ public static byte[] toByteArray(final URLConnection urlConnection) throws IOExc
* @throws NullPointerException if the input is null.
* @throws IOException if an I/O error occurs.
* @since 1.1
- * @deprecated Use {@link #toCharArray(InputStream, Charset)} instead
+ * @deprecated Use {@link #toCharArray(InputStream, Charset)} instead.
*/
@Deprecated
public static char[] toCharArray(final InputStream inputStream) throws IOException {
@@ -3126,37 +3110,31 @@ public static char[] toCharArray(final InputStream inputStream) throws IOExcepti
}
/**
- * Gets the contents of an {@link InputStream} as a character array
- * using the specified character encoding.
+ * Gets the contents of an {@link InputStream} as a character array using the specified character encoding.
*
- * This method buffers the input internally, so there is no need to use a
- * {@link BufferedInputStream}.
+ * This method buffers the input internally, so there is no need to use a {@link BufferedInputStream}.
*
*
* @param inputStream the {@link InputStream} to read.
- * @param charset the charset to use, null means platform default.
+ * @param charset the charset 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.
* @since 2.3
*/
- public static char[] toCharArray(final InputStream inputStream, final Charset charset)
- throws IOException {
+ public static char[] toCharArray(final InputStream inputStream, final Charset charset) throws IOException {
final CharArrayWriter writer = new CharArrayWriter();
copy(inputStream, writer, charset);
return writer.toCharArray();
}
/**
- * Gets the contents of an {@link InputStream} as a character array
- * using the specified character encoding.
+ * Gets the contents of an {@link InputStream} as a character array using the specified character encoding.
*
- * Character encoding names can be found at
- * IANA.
+ * Character encoding names can be found at IANA.
*
*
- * This method buffers the input internally, so there is no need to use a
- * {@link BufferedInputStream}.
+ * This method buffers the input internally, so there is no need to use a {@link BufferedInputStream}.
*
*
* @param inputStream the {@link InputStream} to read.
@@ -3174,8 +3152,7 @@ public static char[] toCharArray(final InputStream inputStream, final String cha
/**
* Gets the contents of a {@link Reader} as a character array.
*
- * This method buffers the input internally, so there is no need to use a
- * {@link BufferedReader}.
+ * This method buffers the input internally, so there is no need to use a {@link BufferedReader}.
*
*
* @param reader the {@link Reader} to read.
@@ -3191,8 +3168,8 @@ public static char[] toCharArray(final Reader reader) throws IOException {
}
/**
- * Converts the specified CharSequence to an input stream, encoded as bytes
- * using the virtual machine's {@link Charset#defaultCharset() default charset}.
+ * Converts the specified CharSequence to an input stream, encoded as bytes using the virtual machine's {@linkplain Charset#defaultCharset() default
+ * charset}.
*
* @param input the CharSequence to convert.
* @return an input stream.
@@ -3205,10 +3182,9 @@ public static InputStream toInputStream(final CharSequence input) {
}
/**
- * Converts the specified CharSequence to an input stream, encoded as bytes
- * using the specified character encoding.
+ * Converts the specified CharSequence to an input stream, encoded as bytes using the specified character encoding.
*
- * @param input the CharSequence to convert.
+ * @param input the CharSequence to convert.
* @param charset the charset to use, null means platform default.
* @return an input stream.
* @since 2.3
@@ -3218,14 +3194,12 @@ public static InputStream toInputStream(final CharSequence input, final Charset
}
/**
- * Converts the specified CharSequence to an input stream, encoded as bytes
- * using the specified character encoding.
+ * Converts the specified CharSequence to an input stream, encoded as bytes using the specified character encoding.
*
- * Character encoding names can be found at
- * IANA.
+ * Character encoding names can be found at IANA.
*
*
- * @param input the CharSequence to convert.
+ * @param input the CharSequence to convert.
* @param charsetName the name of the requested charset, null means platform default.
* @return an input stream.
* @throws java.nio.charset.UnsupportedCharsetException if the encoding is not supported.
@@ -3236,8 +3210,7 @@ public static InputStream toInputStream(final CharSequence input, final String c
}
/**
- * Converts the specified string to an input stream, encoded as bytes
- * using the virtual machine's {@link Charset#defaultCharset() default charset}.
+ * Converts the specified string to an input stream, encoded as bytes using the virtual machine's {@linkplain Charset#defaultCharset() default charset}.
*
* @param input the string to convert.
* @return an input stream.
@@ -3250,10 +3223,9 @@ public static InputStream toInputStream(final String input) {
}
/**
- * Converts the specified string to an input stream, encoded as bytes
- * using the specified character encoding.
+ * Converts the specified string to an input stream, encoded as bytes using the specified character encoding.
*
- * @param input the string to convert.
+ * @param input the string to convert.
* @param charset the charset to use, null means platform default.
* @return an input stream.
* @since 2.3
@@ -3263,14 +3235,12 @@ public static InputStream toInputStream(final String input, final Charset charse
}
/**
- * Converts the specified string to an input stream, encoded as bytes
- * using the specified character encoding.
+ * Converts the specified string to an input stream, encoded as bytes using the specified character encoding.
*
- * Character encoding names can be found at
- * IANA.
+ * Character encoding names can be found at IANA.
*
*
- * @param input the string to convert.
+ * @param input the string to convert.
* @param charsetName the name of the requested charset, null means platform default.
* @return an input stream.
* @throws java.nio.charset.UnsupportedCharsetException if the encoding is not supported.
@@ -3281,8 +3251,7 @@ public static InputStream toInputStream(final String input, final String charset
}
/**
- * Gets the contents of a {@code byte[]} as a String
- * using the virtual machine's {@link Charset#defaultCharset() default charset}.
+ * Gets the contents of a {@code byte[]} as a String using the virtual machine's {@linkplain Charset#defaultCharset() default charset}.
*
* @param input the byte array to read.
* @return the requested String.
@@ -3296,14 +3265,12 @@ public static String toString(final byte[] input) {
}
/**
- * Gets the contents of a {@code byte[]} as a String
- * using the specified character encoding.
+ * Gets the contents of a {@code byte[]} as a String using the specified character encoding.
*
- * Character encoding names can be found at
- * IANA.
+ * Character encoding names can be found at IANA.
*
*
- * @param input the byte array to read.
+ * @param input the byte array to read.
* @param charsetName the name of the requested charset, null means platform default.
* @return the requested String.
* @throws NullPointerException if the input is null.
@@ -3313,11 +3280,9 @@ public static String toString(final byte[] input, final String charsetName) {
}
/**
- * Gets the contents of an {@link InputStream} as a String
- * using the virtual machine's {@link Charset#defaultCharset() default charset}.
+ * Gets the contents of an {@link InputStream} as a String using the virtual machine's {@linkplain Charset#defaultCharset() default charset}.
*
- * This method buffers the input internally, so there is no need to use a
- * {@link BufferedInputStream}.
+ * This method buffers the input internally, so there is no need to use a {@link BufferedInputStream}.
*
*
* @param input the {@link InputStream} to read.
@@ -3332,14 +3297,12 @@ public static String toString(final InputStream input) throws IOException {
}
/**
- * Gets the contents of an {@link InputStream} as a String
- * using the specified character encoding.
+ * Gets the contents of an {@link InputStream} as a String using the specified character encoding.
*
- * This method buffers the input internally, so there is no need to use a
- * {@link BufferedInputStream}.
+ * This method buffers the input internally, so there is no need to use a {@link BufferedInputStream}.
*
*
- * @param input the {@link InputStream} to read.
+ * @param input the {@link InputStream} to read.
* @param charset the charset to use, null means platform default.
* @return the requested String.
* @throws NullPointerException if the input is null.
@@ -3354,38 +3317,32 @@ public static String toString(final InputStream input, final Charset charset) th
}
/**
- * Gets the contents of an {@link InputStream} as a String
- * using the specified character encoding.
+ * Gets the contents of an {@link InputStream} as a String using the specified character encoding.
*
- * Character encoding names can be found at
- * IANA.
+ * Character encoding names can be found at IANA.
*
*
- * This method buffers the input internally, so there is no need to use a
- * {@link BufferedInputStream}.
+ * This method buffers the input internally, so there is no need to use a {@link BufferedInputStream}.
*
*
- * @param input the {@link InputStream} to read.
+ * @param input the {@link InputStream} to read.
* @param charsetName the name of the requested charset, null means platform default.
* @return the requested String.
* @throws NullPointerException if the input is null.
* @throws IOException if an I/O error occurs.
* @throws java.nio.charset.UnsupportedCharsetException if the encoding is not supported.
*/
- public static String toString(final InputStream input, final String charsetName)
- throws IOException {
+ public static String toString(final InputStream input, final String charsetName) throws IOException {
return toString(input, Charsets.toCharset(charsetName));
}
/**
- * Gets the contents of an {@link InputStream} from a supplier as a String
- * using the specified character encoding.
+ * Gets the contents of an {@link InputStream} from a supplier as a String using the specified character encoding.
*
- * This method buffers the input internally, so there is no need to use a
- * {@link BufferedInputStream}.
+ * This method buffers the input internally, so there is no need to use a {@link BufferedInputStream}.
*
*
- * @param input supplies the {@link InputStream} to read.
+ * @param input supplies the {@link InputStream} to read.
* @param charset the charset to use, null means platform default.
* @return the requested String.
* @throws NullPointerException if the input is null.
@@ -3399,15 +3356,13 @@ public static String toString(final IOSupplier input, final Charset
}
/**
- * Gets the contents of an {@link InputStream} from a supplier as a String
- * using the specified character encoding.
+ * Gets the contents of an {@link InputStream} from a supplier as a String using the specified character encoding.
*
- * This method buffers the input internally, so there is no need to use a
- * {@link BufferedInputStream}.
+ * This method buffers the input internally, so there is no need to use a {@link BufferedInputStream}.
*
*
- * @param input supplies the {@link InputStream} to read.
- * @param charset the charset to use, null means platform default.
+ * @param input supplies the {@link InputStream} to read.
+ * @param charset the charset to use, null means platform default.
* @param defaultString the default return value if the supplier or its value is null.
* @return the requested String.
* @throws NullPointerException if the input is null.
@@ -3426,8 +3381,7 @@ public static String toString(final IOSupplier input, final Charset
/**
* Gets the contents of a {@link Reader} as a String.
*
- * This method buffers the input internally, so there is no need to use a
- * {@link BufferedReader}.
+ * This method buffers the input internally, so there is no need to use a {@link BufferedReader}.
*
*
* @param reader the {@link Reader} to read.
@@ -3443,7 +3397,7 @@ public static String toString(final Reader reader) throws IOException {
}
/**
- * Gets the contents at the given URI using the virtual machine's {@link Charset#defaultCharset() default charset}.
+ * Gets the contents at the given URI using the virtual machine's {@linkplain Charset#defaultCharset() default charset}.
*
* @param uri The URI source.
* @return The contents of the URL as a String.
@@ -3459,7 +3413,7 @@ public static String toString(final URI uri) throws IOException {
/**
* Gets the contents at the given URI.
*
- * @param uri The URI source.
+ * @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.
@@ -3472,7 +3426,7 @@ public static String toString(final URI uri, final Charset encoding) throws IOEx
/**
* Gets the contents at the given URI.
*
- * @param uri The URI source.
+ * @param uri The URI source.
* @param charsetName The encoding name for the URL contents.
* @return The contents of the URL as a String.
* @throws IOException if an I/O exception occurs.
@@ -3484,7 +3438,7 @@ public static String toString(final URI uri, final String charsetName) throws IO
}
/**
- * Gets the contents at the given URL using the virtual machine's {@link Charset#defaultCharset() default charset}.
+ * Gets the contents at the given URL using the virtual machine's {@linkplain Charset#defaultCharset() default charset}.
*
* @param url The URL source.
* @return The contents of the URL as a String.
@@ -3500,7 +3454,7 @@ public static String toString(final URL url) throws IOException {
/**
* Gets the contents at the given URL.
*
- * @param url The URL source.
+ * @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.
@@ -3513,7 +3467,7 @@ public static String toString(final URL url, final Charset encoding) throws IOEx
/**
* Gets the contents at the given URL.
*
- * @param url The URL source.
+ * @param url The URL source.
* @param charsetName The encoding name for the URL contents.
* @return The contents of the URL as a String.
* @throws IOException if an I/O exception occurs.
@@ -3533,22 +3487,19 @@ public static String toString(final URL url, final String charsetName) throws IO
* @throws IOException if an I/O error occurs.
* @since 1.1
*/
- public static void write(final byte[] data, final OutputStream output)
- throws IOException {
+ public static void write(final byte[] data, final OutputStream output) throws IOException {
if (data != null) {
output.write(data);
}
}
/**
- * Writes bytes from a {@code byte[]} to chars on a {@link Writer}
- * using the virtual machine's {@link Charset#defaultCharset() default charset}.
+ * Writes bytes from a {@code byte[]} to chars on a {@link Writer} using the virtual machine's {@linkplain Charset#defaultCharset() default charset}.
*
* This method uses {@link String#String(byte[])}.
*
*
- * @param data the byte array to write, do not modify during output,
- * null ignored
+ * @param data the byte array to write, do not modify during output, null ignored.
* @param writer the {@link Writer} to write to.
* @throws NullPointerException if output is null.
* @throws IOException if an I/O error occurs.
@@ -3561,15 +3512,13 @@ public static void write(final byte[] data, final Writer writer) throws IOExcept
}
/**
- * Writes bytes from a {@code byte[]} to chars on a {@link Writer}
- * using the specified character encoding.
+ * Writes bytes from a {@code byte[]} to chars on a {@link Writer} using the specified character encoding.
*
* This method uses {@link String#String(byte[], String)}.
*
*
- * @param data the byte array to write, do not modify during output,
- * null ignored
- * @param writer the {@link Writer} to write to.
+ * @param data the byte array to write, do not modify during output, null ignored.
+ * @param writer the {@link Writer} to write to.
* @param charset the charset to use, null means platform default.
* @throws NullPointerException if output is null.
* @throws IOException if an I/O error occurs.
@@ -3584,7 +3533,7 @@ public static void write(final byte[] data, final Writer writer, final Charset c
/**
* Writes bytes from a {@code byte[]} to chars on a {@link Writer} using the specified character encoding.
*
- * Character encoding names can be found at IANA.
+ * Character encoding names can be found at IANA.
*
*
* This method uses {@link String#String(byte[], String)}.
@@ -3605,7 +3554,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}.
*
- * This method uses the virtual machine's {@link Charset#defaultCharset() default charset}.
+ * This method uses the virtual machine's {@linkplain Charset#defaultCharset() default charset}.
*
*
* @param data the char array to write, do not modify during output, null ignored.
@@ -3616,8 +3565,7 @@ public static void write(final byte[] data, final Writer writer, final String ch
* @deprecated Use {@link #write(char[], OutputStream, Charset)} instead.
*/
@Deprecated
- public static void write(final char[] data, final OutputStream output)
- throws IOException {
+ public static void write(final char[] data, final OutputStream output) throws IOException {
write(data, output, Charset.defaultCharset());
}
@@ -3643,7 +3591,7 @@ public static void write(final char[] data, final OutputStream output, final Cha
/**
* Writes chars from a {@code char[]} to bytes on an {@link OutputStream} using the specified character encoding.
*
- * Character encoding names can be found at IANA.
+ * Character encoding names can be found at IANA.
*
*
* This method uses {@link String#String(char[])} and {@link String#getBytes(String)}.
@@ -3657,8 +3605,7 @@ public static void write(final char[] data, final OutputStream output, final Cha
* @throws java.nio.charset.UnsupportedCharsetException if the encoding is not supported.
* @since 1.1
*/
- public static void write(final char[] data, final OutputStream output, final String charsetName)
- throws IOException {
+ public static void write(final char[] data, final OutputStream output, final String charsetName) throws IOException {
write(data, output, Charsets.toCharset(charsetName));
}
@@ -3692,8 +3639,7 @@ public static void write(final char[] data, final Writer writer) throws IOExcept
* @deprecated Use {@link #write(CharSequence, OutputStream, Charset)} instead.
*/
@Deprecated
- public static void write(final CharSequence data, final OutputStream output)
- throws IOException {
+ public static void write(final CharSequence data, final OutputStream output) throws IOException {
write(data, output, Charset.defaultCharset());
}
@@ -3710,8 +3656,7 @@ public static void write(final CharSequence data, final OutputStream output)
* @throws IOException if an I/O error occurs.
* @since 2.3
*/
- public static void write(final CharSequence data, final OutputStream output, final Charset charset)
- throws IOException {
+ public static void write(final CharSequence data, final OutputStream output, final Charset charset) throws IOException {
if (data != null) {
write(data.toString(), output, charset);
}
@@ -3720,7 +3665,7 @@ public static void write(final CharSequence data, final OutputStream output, fin
/**
* Writes chars from a {@link CharSequence} to bytes on an {@link OutputStream} using the specified character encoding.
*
- * Character encoding names can be found at IANA.
+ * Character encoding names can be found at IANA.
*
*
* This method uses {@link String#getBytes(String)}.
@@ -3734,15 +3679,14 @@ public static void write(final CharSequence data, final OutputStream output, fin
* @throws java.nio.charset.UnsupportedCharsetException if the encoding is not supported.
* @since 2.0
*/
- public static void write(final CharSequence data, final OutputStream output, final String charsetName)
- throws IOException {
+ public static void write(final CharSequence data, final OutputStream output, final String charsetName) throws IOException {
write(data, output, Charsets.toCharset(charsetName));
}
/**
* Writes chars from a {@link CharSequence} to a {@link Writer}.
*
- * @param data the {@link CharSequence} to write, null ignored.
+ * @param data the {@link CharSequence} to write, null ignored.
* @param writer the {@link Writer} to write to.
* @throws NullPointerException if output is null.
* @throws IOException if an I/O error occurs.
@@ -3755,34 +3699,31 @@ 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 virtual machine's {@link Charset#defaultCharset() default charset}.
+ * Writes chars from a {@link String} to bytes on an {@link OutputStream} using the virtual machine's {@linkplain Charset#defaultCharset() default charset}.
*
* This method uses {@link String#getBytes()}.
*
*
- * @param data the {@link String} to write, null ignored.
+ * @param data the {@link String} to write, null ignored.
* @param output the {@link OutputStream} to write to.
* @throws NullPointerException if output is null.
* @throws IOException if an I/O error occurs.
* @since 1.1
- * @deprecated Use {@link #write(String, OutputStream, Charset)} instead
+ * @deprecated Use {@link #write(String, OutputStream, Charset)} instead.
*/
@Deprecated
- public static void write(final String data, final OutputStream output)
- throws IOException {
+ public static void write(final String data, final OutputStream output) throws IOException {
write(data, output, Charset.defaultCharset());
}
/**
- * Writes chars from a {@link String} to bytes on an
- * {@link OutputStream} using the specified character encoding.
+ * Writes chars from a {@link String} to bytes on an {@link OutputStream} using the specified character encoding.
*
* This method uses {@link String#getBytes(String)}.
*
*
- * @param data the {@link String} to write, null ignored.
- * @param output the {@link OutputStream} to write to.
+ * @param data the {@link String} to write, null ignored.
+ * @param output the {@link OutputStream} to write to.
* @param charset the charset to use, null means platform default.
* @throws NullPointerException if output is null.
* @throws IOException if an I/O error occurs.
@@ -3799,33 +3740,30 @@ public static void write(final String data, final OutputStream output, final Cha
}
/**
- * Writes chars from a {@link String} to bytes on an
- * {@link OutputStream} using the specified character encoding.
+ * Writes chars from a {@link String} to bytes on an {@link OutputStream} using the specified character encoding.
*
- * Character encoding names can be found at
- * IANA.
+ * Character encoding names can be found at IANA.
*
*
* This method uses {@link String#getBytes(String)}.
*
*
- * @param data the {@link String} to write, null ignored.
- * @param output the {@link OutputStream} to write to.
+ * @param data the {@link String} to write, null ignored.
+ * @param output the {@link OutputStream} to write to.
* @param charsetName the name of the requested charset, null means platform default.
- * @throws NullPointerException if output is null.
- * @throws IOException if an I/O error occurs.
+ * @throws NullPointerException if output is null.
+ * @throws IOException if an I/O error occurs.
* @throws java.nio.charset.UnsupportedCharsetException if the encoding is not supported.
* @since 1.1
*/
- public static void write(final String data, final OutputStream output, final String charsetName)
- throws IOException {
+ public static void write(final String data, final OutputStream output, final String charsetName) throws IOException {
write(data, output, Charsets.toCharset(charsetName));
}
/**
* Writes chars from a {@link String} to a {@link Writer}.
*
- * @param data the {@link String} to write, null ignored.
+ * @param data the {@link String} to write, null ignored.
* @param writer the {@link Writer} to write to.
* @throws NullPointerException if output is null.
* @throws IOException if an I/O error occurs.
@@ -3838,49 +3776,45 @@ public static void write(final String data, final Writer writer) throws IOExcept
}
/**
- * Writes chars from a {@link StringBuffer} to bytes on an
- * {@link OutputStream} using the default character encoding of the
- * platform.
+ * Writes chars from a {@link StringBuffer} to bytes on an {@link OutputStream} using the default character encoding of the platform.
*
* This method uses {@link String#getBytes()}.
*
*
- * @param data the {@link StringBuffer} to write, null ignored.
+ * @param data the {@link StringBuffer} to write, null ignored.
* @param output the {@link OutputStream} 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 Use {@link #write(CharSequence, OutputStream)}.
*/
@Deprecated
- public static void write(final StringBuffer data, final OutputStream output) //NOSONAR
+ public static void write(final StringBuffer data, final OutputStream output) // NOSONAR
throws IOException {
write(data, output, (String) null);
}
/**
- * Writes chars from a {@link StringBuffer} to bytes on an
- * {@link OutputStream} using the specified character encoding.
+ * Writes chars from a {@link StringBuffer} to bytes on an {@link OutputStream} using the specified character encoding.
*
- * Character encoding names can be found at
- * IANA.
+ * Character encoding names can be found at IANA.
*
*
* This method uses {@link String#getBytes(String)}.
*
*
- * @param data the {@link StringBuffer} to write, null ignored.
- * @param output the {@link OutputStream} to write to.
+ * @param data the {@link StringBuffer} to write, null ignored.
+ * @param output the {@link OutputStream} to write to.
* @param charsetName the name of the requested charset, null means platform default.
- * @throws NullPointerException if output is null.
- * @throws IOException if an I/O error occurs.
+ * @throws NullPointerException if output is null.
+ * @throws IOException if an I/O error occurs.
* @throws java.nio.charset.UnsupportedCharsetException if the encoding is not supported.
* @since 1.1
* @deprecated Use {@link #write(CharSequence, OutputStream, String)}.
*/
@Deprecated
- public static void write(final StringBuffer data, final OutputStream output, final String charsetName) //NOSONAR
- throws IOException {
+ public static void write(final StringBuffer data, final OutputStream output, final String charsetName) // NOSONAR
+ throws IOException {
if (data != null) {
write(data.toString(), output, Charsets.toCharset(charsetName));
}
@@ -3889,7 +3823,7 @@ public static void write(final StringBuffer data, final OutputStream output, fin
/**
* Writes chars from a {@link StringBuffer} to a {@link Writer}.
*
- * @param data the {@link StringBuffer} to write, null ignored.
+ * @param data the {@link StringBuffer} to write, null ignored.
* @param writer the {@link Writer} to write to.
* @throws NullPointerException if output is null.
* @throws IOException if an I/O error occurs.
@@ -3897,7 +3831,7 @@ public static void write(final StringBuffer data, final OutputStream output, fin
* @deprecated Use {@link #write(CharSequence, Writer)}.
*/
@Deprecated
- public static void write(final StringBuffer data, final Writer writer) //NOSONAR
+ public static void write(final StringBuffer data, final Writer writer) // NOSONAR
throws IOException {
if (data != null) {
writer.write(data.toString());
@@ -3905,19 +3839,16 @@ public static void write(final StringBuffer data, final Writer writer) //NOSONAR
}
/**
- * Writes bytes from a {@code byte[]} to an {@link OutputStream} using chunked writes.
- * 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.
+ * Writes bytes from a {@code byte[]} to an {@link OutputStream} using chunked writes. 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,
- * null ignored.
+ * @param data the byte array to write, do not modify during output, null ignored.
* @param output the {@link OutputStream} to write to.
* @throws NullPointerException if output is null.
* @throws IOException if an I/O error occurs.
* @since 2.5
*/
- public static void writeChunked(final byte[] data, final OutputStream output)
- throws IOException {
+ public static void writeChunked(final byte[] data, final OutputStream output) throws IOException {
if (data != null) {
int bytes = data.length;
int offset = 0;
@@ -3955,7 +3886,7 @@ 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 virtual machine's
- * {@link Charset#defaultCharset() default charset} and the specified line ending.
+ * {@linkplain 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.
@@ -3963,7 +3894,7 @@ public static void writeChunked(final char[] data, final Writer writer) throws I
* @throws NullPointerException if the output is null.
* @throws IOException if an I/O error occurs.
* @since 1.1
- * @deprecated Use {@link #writeLines(Collection, String, OutputStream, Charset)} instead
+ * @deprecated Use {@link #writeLines(Collection, String, OutputStream, Charset)} instead.
*/
@Deprecated
public static void writeLines(final Collection lines, final String lineEnding, final OutputStream output) throws IOException {
@@ -4009,7 +3940,7 @@ public static void writeLines(final Collection lines, String lineEnding, fina
* Writes the {@link #toString()} value of each item in a collection to an {@link OutputStream} line by line, using the specified character encoding and the
* specified line ending.
*
- * Character encoding names can be found at IANA.
+ * Character encoding names can be found at IANA.
*
*
* @param lines the lines to write, null entries produce blank lines.
@@ -4051,11 +3982,10 @@ public static void writeLines(final Collection lines, String lineEnding, fina
}
/**
- * Returns the given Appendable if it is already a {@link Writer}, otherwise creates a Writer wrapper around the
- * given Appendable.
+ * Returns the given Appendable if it is already a {@link Writer}, otherwise creates a Writer wrapper around the given Appendable.
*
* @param appendable the Appendable to wrap or return (not null).
- * @return the given Appendable or a Writer wrapper around the given Appendable.
+ * @return the given Appendable or a Writer wrapper around the given Appendable.
* @throws NullPointerException if the input parameter is null.
* @since 2.7
*/
@@ -4076,8 +4006,7 @@ public static Writer writer(final Appendable appendable) {
* @deprecated TODO Make private in 3.0.
*/
@Deprecated
- public IOUtils() { //NOSONAR
+ public IOUtils() { // NOSONAR
// empty
}
-
}
diff --git a/src/main/java/org/apache/commons/io/LineIterator.java b/src/main/java/org/apache/commons/io/LineIterator.java
index 293847e7a72..fd07e9325c9 100644
--- a/src/main/java/org/apache/commons/io/LineIterator.java
+++ b/src/main/java/org/apache/commons/io/LineIterator.java
@@ -56,9 +56,9 @@ public class LineIterator implements Iterator, Closeable {
* Closes a {@link LineIterator} quietly.
*
* @param iterator The iterator to close, or {@code null}.
+ * @see Throwable#addSuppressed(Throwable)
* @deprecated As of 2.6 deprecated without replacement. Please use the try-with-resources statement or handle
* suppressed exceptions manually.
- * @see Throwable#addSuppressed(Throwable)
*/
@Deprecated
public static void closeQuietly(final LineIterator iterator) {
@@ -77,8 +77,8 @@ public static void closeQuietly(final LineIterator iterator) {
/**
* Constructs an iterator of the lines for a {@link Reader}.
*
- * @param reader the {@link Reader} to read from, not null
- * @throws NullPointerException if the reader is null
+ * @param reader the {@link Reader} to read from, not null.
+ * @throws NullPointerException if the reader is null.
*/
@SuppressWarnings("resource") // Caller closes Reader
public LineIterator(final Reader reader) {
@@ -111,8 +111,8 @@ public void close() throws IOException {
* If there is an {@link IOException} then {@link #close()} will
* be called on this instance.
*
- * @return {@code true} if the Reader has more lines
- * @throws IllegalStateException if an IO exception occurs
+ * @return {@code true} if the Reader has more lines.
+ * @throws IllegalStateException if an IO exception occurs.
*/
@Override
public boolean hasNext() {
@@ -135,16 +135,16 @@ public boolean hasNext() {
}
}
} catch (final IOException ioe) {
- IOUtils.closeQuietly(this, ioe::addSuppressed);
- throw new IllegalStateException(ioe);
+ throw new IllegalStateException(IOUtils.closeQuietlySuppress(this, ioe));
}
}
/**
* Overridable method to validate each line that is returned.
* This implementation always returns true.
- * @param line the line that is to be validated
- * @return true if valid, false to remove from the iterator
+ *
+ * @param line the line that is to be validated.
+ * @return true if valid, false to remove from the iterator.
*/
protected boolean isValidLine(final String line) {
return true;
@@ -153,8 +153,8 @@ protected boolean isValidLine(final String line) {
/**
* Returns the next line in the wrapped {@link Reader}.
*
- * @return the next line from the input
- * @throws NoSuchElementException if there is no line to return
+ * @return the next line from the input.
+ * @throws NoSuchElementException if there is no line to return.
*/
@Override
public String next() {
@@ -164,8 +164,8 @@ public String next() {
/**
* Returns the next line in the wrapped {@link Reader}.
*
- * @return the next line from the input
- * @throws NoSuchElementException if there is no line to return
+ * @return the next line from the input.
+ * @throws NoSuchElementException if there is no line to return.
* @deprecated Use {@link #next()}.
*/
@Deprecated
@@ -181,7 +181,7 @@ public String nextLine() {
/**
* Unsupported.
*
- * @throws UnsupportedOperationException always
+ * @throws UnsupportedOperationException always.
*/
@Override
public void remove() {
diff --git a/src/main/java/org/apache/commons/io/RandomAccessFileMode.java b/src/main/java/org/apache/commons/io/RandomAccessFileMode.java
index 88f499d120b..ea44bfa6cba 100644
--- a/src/main/java/org/apache/commons/io/RandomAccessFileMode.java
+++ b/src/main/java/org/apache/commons/io/RandomAccessFileMode.java
@@ -195,8 +195,8 @@ public T apply(final Path file, final IOFunction functi
* Prefer {@link #create(Path)} over this.
*
*
- * @param file the file object
- * @return a random access file
+ * @param file the file object.
+ * @return a random access file.
* @throws FileNotFoundException See {@link IORandomAccessFile#IORandomAccessFile(File, String)}.
*/
public RandomAccessFile create(final File file) throws FileNotFoundException {
@@ -206,8 +206,8 @@ public RandomAccessFile create(final File file) throws FileNotFoundException {
/**
* Constructs a random access file to read from, and optionally to write to, the file specified by the {@link File} argument.
*
- * @param file the file object
- * @return a random access file
+ * @param file the file object.
+ * @return a random access file.
* @throws FileNotFoundException See {@link IORandomAccessFile#IORandomAccessFile(File, String)}.
*/
public RandomAccessFile create(final Path file) throws FileNotFoundException {
@@ -220,8 +220,8 @@ public RandomAccessFile create(final Path file) throws FileNotFoundException {
* Prefer {@link #create(Path)} over this.
*
*
- * @param name the file object
- * @return a random access file
+ * @param name the file object.
+ * @return a random access file.
* @throws FileNotFoundException See {@link IORandomAccessFile#IORandomAccessFile(File, String)}.
*/
public RandomAccessFile create(final String name) throws FileNotFoundException {
@@ -282,8 +282,8 @@ public boolean implies(final RandomAccessFileMode other) {
/**
* Constructs a random access file to read from, and optionally to write to, the file specified by the {@link File} argument.
*
- * @param name the file object
- * @return a random access file
+ * @param name the file object.
+ * @return a random access file.
* @throws FileNotFoundException See {@link IORandomAccessFile#IORandomAccessFile(File, String)}.
* @since 2.18.0
*/
diff --git a/src/main/java/org/apache/commons/io/TaggedIOException.java b/src/main/java/org/apache/commons/io/TaggedIOException.java
index 5eb0b5df596..d997ecc0433 100644
--- a/src/main/java/org/apache/commons/io/TaggedIOException.java
+++ b/src/main/java/org/apache/commons/io/TaggedIOException.java
@@ -57,8 +57,8 @@ public class TaggedIOException extends IOExceptionWithCause {
* }
*
*
- * @param throwable The Throwable object to check
- * @param tag tag object
+ * @param throwable The Throwable object to check.
+ * @param tag tag object.
* @return {@code true} if the throwable has the specified tag,
* otherwise {@code false}
*/
@@ -86,9 +86,9 @@ public static boolean isTaggedWith(final Throwable throwable, final Object tag)
* }
*
*
- * @param throwable an exception
- * @param tag tag object
- * @throws IOException original exception from the tagged decorator, if any
+ * @param throwable an exception.
+ * @param tag tag object.
+ * @throws IOException original exception from the tagged decorator, if any.
*/
public static void throwCauseIfTaggedWith(final Throwable throwable, final Object tag)
throws IOException {
@@ -105,8 +105,8 @@ public static void throwCauseIfTaggedWith(final Throwable throwable, final Objec
/**
* Constructs a tagged wrapper for the given exception.
*
- * @param original the exception to be tagged
- * @param tag tag of this exception
+ * @param original the exception to be tagged.
+ * @param tag tag of this exception.
*/
public TaggedIOException(final IOException original, final Serializable tag) {
super(original.getMessage(), original);
@@ -117,7 +117,7 @@ public TaggedIOException(final IOException original, final Serializable tag) {
* Returns the wrapped exception. The only difference to the overridden
* {@link Throwable#getCause()} method is the narrower return type.
*
- * @return wrapped exception
+ * @return wrapped exception.
*/
@Override
public synchronized IOException getCause() {
@@ -127,7 +127,7 @@ public synchronized IOException getCause() {
/**
* Returns the serializable tag object.
*
- * @return tag object
+ * @return tag object.
*/
public Serializable getTag() {
return tag;
diff --git a/src/main/java/org/apache/commons/io/ThreadMonitor.java b/src/main/java/org/apache/commons/io/ThreadMonitor.java
index 4c2c37a2d3b..f9fe24957c5 100644
--- a/src/main/java/org/apache/commons/io/ThreadMonitor.java
+++ b/src/main/java/org/apache/commons/io/ThreadMonitor.java
@@ -52,7 +52,7 @@ static Thread start(final Duration timeout) {
/**
* Starts monitoring the specified thread.
*
- * @param thread The thread to monitor
+ * @param thread The thread to monitor.
* @param timeout The timeout amount. or no timeout if the value is zero or less.
* @return The monitor thread or {@code null} if the timeout amount is not greater than zero.
*/
@@ -60,7 +60,7 @@ static Thread start(final Thread thread, final Duration timeout) {
if (timeout.isZero() || timeout.isNegative()) {
return null;
}
- final Thread monitor = new Thread(new ThreadMonitor(thread, timeout), ThreadMonitor.class.getSimpleName());
+ final Thread monitor = new Thread(new ThreadMonitor(thread, timeout), "commons-io-ThreadMonitor");
monitor.setDaemon(true);
monitor.start();
return monitor;
@@ -104,6 +104,7 @@ public void run() {
thread.interrupt();
} catch (final InterruptedException ignored) {
// timeout not reached
+ Thread.currentThread().interrupt();
}
}
}
diff --git a/src/main/java/org/apache/commons/io/UncheckedIOExceptions.java b/src/main/java/org/apache/commons/io/UncheckedIOExceptions.java
index f31043769b7..6a5075c52ca 100644
--- a/src/main/java/org/apache/commons/io/UncheckedIOExceptions.java
+++ b/src/main/java/org/apache/commons/io/UncheckedIOExceptions.java
@@ -47,6 +47,7 @@ public static UncheckedIOException create(final Object message) {
*
* This method exists because there is no String constructor in {@link UncheckedIOException}.
*
+ *
* @param e cause the {@link IOException}.
* @param message the detail message.
* @return a new {@link UncheckedIOException}.
diff --git a/src/main/java/org/apache/commons/io/build/AbstractOrigin.java b/src/main/java/org/apache/commons/io/build/AbstractOrigin.java
index d84aefdb79a..341c442a657 100644
--- a/src/main/java/org/apache/commons/io/build/AbstractOrigin.java
+++ b/src/main/java/org/apache/commons/io/build/AbstractOrigin.java
@@ -366,6 +366,7 @@ public abstract static class AbstractRandomAccessFileOrigin
*
* @param origin The origin, not null.
+ * @throws NullPointerException if {@code origin} is {@code null}.
*/
public AbstractRandomAccessFileOrigin(final T origin) {
super(origin);
@@ -437,6 +438,7 @@ public static class ByteArrayOrigin extends AbstractOrigin
* Constructs a new instance for the given origin.
*
* @param origin The origin, not null.
+ * @throws NullPointerException if {@code origin} is {@code null}.
*/
public ChannelOrigin(final Channel origin) {
super(origin);
@@ -563,6 +566,7 @@ public static class CharSequenceOrigin extends AbstractOrigin {
* Constructs a new instance for the given origin.
*
* @param origin The origin, not null.
+ * @throws NullPointerException if {@code origin} is {@code null}.
*/
public FileOrigin(final File origin) {
super(origin);
@@ -689,6 +694,7 @@ public static class InputStreamOrigin extends AbstractOrigin {
* Constructs a new instance for the given origin.
*
* @param origin The origin, not null.
+ * @throws NullPointerException if {@code origin} is {@code null}.
*/
public PathOrigin(final Path origin) {
super(origin);
@@ -892,6 +900,7 @@ public static class ReaderOrigin extends AbstractOrigin {
* Constructs a new instance for the given origin.
*
* @param origin The origin, not null.
+ * @throws NullPointerException if {@code origin} is {@code null}.
*/
public ReaderOrigin(final Reader origin) {
super(origin);
@@ -959,6 +968,7 @@ public static class URIOrigin extends AbstractOrigin {
* Constructs a new instance for the given origin.
*
* @param origin The origin, not null.
+ * @throws NullPointerException if {@code origin} is {@code null}.
*/
public URIOrigin(final URI origin) {
super(origin);
@@ -1007,6 +1017,7 @@ public static class WriterOrigin extends AbstractOrigin {
* Constructs a new instance for the given origin.
*
* @param origin The origin, not null.
+ * @throws NullPointerException if {@code origin} is {@code null}.
*/
public WriterOrigin(final Writer origin) {
super(origin);
@@ -1057,15 +1068,16 @@ public Writer getWriter(final Charset charset, final OpenOption... options) thro
* Constructs a new instance for subclasses.
*
* @param origin The origin, not null.
+ * @throws NullPointerException if {@code origin} is {@code null}.
*/
protected AbstractOrigin(final T origin) {
this.origin = Objects.requireNonNull(origin, "origin");
}
/**
- * Gets the origin.
+ * Gets the origin, never null.
*
- * @return the origin.
+ * @return the origin, never null.
*/
@Override
public T get() {
@@ -1090,7 +1102,7 @@ public byte[] getByteArray() throws IOException {
* @param length How many bytes to copy.
* @return this origin as a byte array, if possible.
* @throws UnsupportedOperationException if the origin cannot be converted to a Path.
- * @throws ArithmeticException if the {@code position} overflows an int
+ * @throws ArithmeticException if the {@code position} overflows an int.
* @throws IOException if an I/O error occurs.
* @since 2.13.0
*/
@@ -1113,6 +1125,7 @@ public byte[] getByteArray(final long position, final int length) throws IOExcep
* @param The type of channel to return.
* @throws IOException If an I/O error occurs.
* @throws UnsupportedOperationException If this origin cannot be converted to a channel of the given type.
+ * @see #getChannel(OpenOption...)
* @since 2.21.0
*/
public final C getChannel(final Class channelType, final OpenOption... options) throws IOException {
@@ -1131,6 +1144,7 @@ public final C getChannel(final Class channelType, final
* @return A new Channel on the origin.
* @throws IOException If an I/O error occurs.
* @throws UnsupportedOperationException If this origin cannot be converted to a channel.
+ * @see #getChannel(Class, OpenOption...)
* @since 2.21.0
*/
protected Channel getChannel(final OpenOption... options) throws IOException {
@@ -1162,7 +1176,7 @@ public File getFile() {
/**
* Gets this origin as an InputStream, if possible.
*
- * @param options options specifying how the file is opened
+ * @param options options specifying how the file is opened.
* @return this origin as an InputStream, if possible.
* @throws IOException if an I/O error occurs.
* @throws UnsupportedOperationException if the origin cannot be converted to a Path.
@@ -1174,7 +1188,7 @@ public InputStream getInputStream(final OpenOption... options) throws IOExceptio
/**
* Gets this origin as an OutputStream, if possible.
*
- * @param options options specifying how the file is opened
+ * @param options options specifying how the file is opened.
* @return this origin as an OutputStream, if possible.
* @throws IOException if an I/O error occurs.
* @throws UnsupportedOperationException if the origin cannot be converted to a Path.
@@ -1217,6 +1231,11 @@ public Reader getReader(final Charset charset) throws IOException {
return Files.newBufferedReader(getPath(), Charsets.toCharset(charset));
}
+ /**
+ * Gets simple name of the underlying class.
+ *
+ * @return The simple name of the underlying class.
+ */
private String getSimpleClassName() {
return getClass().getSimpleName();
}
@@ -1224,8 +1243,8 @@ private String getSimpleClassName() {
/**
* Gets a new Writer on the origin, buffered by default.
*
- * @param charset the charset to use for encoding
- * @param options options specifying how the file is opened
+ * @param charset the charset to use for encoding.
+ * @param options options specifying how the file is opened.
* @return a new Writer on the origin.
* @throws IOException if an I/O error occurs opening or creating the file.
* @throws UnsupportedOperationException if the origin cannot be converted to a Path.
diff --git a/src/main/java/org/apache/commons/io/build/AbstractStreamBuilder.java b/src/main/java/org/apache/commons/io/build/AbstractStreamBuilder.java
index 541548c7295..50505d97716 100644
--- a/src/main/java/org/apache/commons/io/build/AbstractStreamBuilder.java
+++ b/src/main/java/org/apache/commons/io/build/AbstractStreamBuilder.java
@@ -142,7 +142,7 @@ public C getChannel(final Class channelType) throws IOExc
/**
* Gets a CharSequence from the origin with a Charset.
*
- * @return An input stream
+ * @return An input stream.
* @throws IllegalStateException if the {@code origin} is {@code null}.
* @throws UnsupportedOperationException if the origin cannot be converted to a CharSequence.
* @throws IOException if an I/O error occurs.
@@ -174,7 +174,7 @@ public Charset getCharsetDefault() {
/**
* Gets a File from the origin.
*
- * @return A File
+ * @return A File.
* @throws IllegalStateException if the {@code origin} is {@code null}.
* @throws UnsupportedOperationException if the origin cannot be converted to a {@link File}.
* @see AbstractOrigin#getPath()
@@ -187,7 +187,7 @@ public File getFile() {
/**
* Gets an InputStream from the origin with OpenOption[].
*
- * @return An input stream
+ * @return An input stream.
* @throws IllegalStateException if the {@code origin} is {@code null}.
* @throws UnsupportedOperationException if the origin cannot be converted to an {@link InputStream}.
* @throws IOException if an I/O error occurs.
@@ -211,7 +211,7 @@ public OpenOption[] getOpenOptions() {
/**
* Gets an OutputStream from the origin with OpenOption[].
*
- * @return An OutputStream
+ * @return An OutputStream.
* @throws IllegalStateException if the {@code origin} is {@code null}.
* @throws UnsupportedOperationException if the origin cannot be converted to an {@link OutputStream}.
* @throws IOException if an I/O error occurs.
@@ -226,7 +226,7 @@ public OutputStream getOutputStream() throws IOException {
/**
* Gets a Path from the origin.
*
- * @return A Path
+ * @return A Path.
* @throws IllegalStateException if the {@code origin} is {@code null}.
* @throws UnsupportedOperationException if the origin cannot be converted to a {@link Path}.
* @see AbstractOrigin#getPath()
@@ -239,7 +239,7 @@ public Path getPath() {
/**
* Gets a RandomAccessFile from the origin.
*
- * @return A RandomAccessFile
+ * @return A RandomAccessFile.
* @throws IllegalStateException if the {@code origin} is {@code null}.
* @throws UnsupportedOperationException if the origin cannot be converted to a {@link RandomAccessFile}.
* @throws IOException if an I/O error occurs.
@@ -252,7 +252,7 @@ public RandomAccessFile getRandomAccessFile() throws IOException {
/**
* Gets a Reader from the origin with a Charset.
*
- * @return A Reader
+ * @return A Reader.
* @throws IllegalStateException if the {@code origin} is {@code null}.
* @throws UnsupportedOperationException if the origin cannot be converted to a {@link Reader}.
* @throws IOException if an I/O error occurs.
diff --git a/src/main/java/org/apache/commons/io/build/package-info.java b/src/main/java/org/apache/commons/io/build/package-info.java
index bda177c354c..5eed609d544 100644
--- a/src/main/java/org/apache/commons/io/build/package-info.java
+++ b/src/main/java/org/apache/commons/io/build/package-info.java
@@ -14,6 +14,7 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
+
/**
* Provides classes to implement the builder pattern for IO classes.
*
@@ -49,5 +50,4 @@
*
* @since 2.12.0
*/
-
package org.apache.commons.io.build;
diff --git a/src/main/java/org/apache/commons/io/channels/ByteArraySeekableByteChannel.java b/src/main/java/org/apache/commons/io/channels/ByteArraySeekableByteChannel.java
index 4135a815e83..83cf9dea193 100644
--- a/src/main/java/org/apache/commons/io/channels/ByteArraySeekableByteChannel.java
+++ b/src/main/java/org/apache/commons/io/channels/ByteArraySeekableByteChannel.java
@@ -56,7 +56,7 @@ public class ByteArraySeekableByteChannel implements SeekableByteChannel {
* automatically allocate a larger backing array and copy the existing contents.
*
* @param bytes The byte array to wrap, must not be {@code null}
- * @return A new channel that uses the given array as its initial backing store
+ * @return A new channel that uses the given array as its initial backing store.
* @throws NullPointerException If {@code bytes} is {@code null}
* @see #array()
* @see ByteArrayInputStream#ByteArrayInputStream(byte[])
@@ -68,7 +68,7 @@ public static ByteArraySeekableByteChannel wrap(final byte[] bytes) {
private byte[] data;
private volatile boolean closed;
- private int position;
+ private long position;
private int size;
private final ReentrantLock lock = new ReentrantLock();
@@ -126,11 +126,10 @@ private void checkOpen() throws ClosedChannelException {
}
}
- private int checkRange(final long newSize, final String method) {
- if (newSize < 0L || newSize > IOUtils.SOFT_MAX_ARRAY_LENGTH) {
- throw new IllegalArgumentException(String.format("%s must be in range [0..%,d]: %,d", method, IOUtils.SOFT_MAX_ARRAY_LENGTH, newSize));
+ private void checkRange(final long newSize, final String method) {
+ if (newSize < 0L) {
+ throw new IllegalArgumentException(String.format("%s must be positive: %,d", method, newSize));
}
- return (int) newSize;
}
@Override
@@ -166,10 +165,10 @@ public long position() throws ClosedChannelException {
@Override
public SeekableByteChannel position(final long newPosition) throws IOException {
checkOpen();
- final int intPos = checkRange(newPosition, "position()");
+ checkRange(newPosition, "position()");
lock.lock();
try {
- position = intPos;
+ position = newPosition;
} finally {
lock.unlock();
}
@@ -181,15 +180,18 @@ public int read(final ByteBuffer buf) throws IOException {
checkOpen();
lock.lock();
try {
+ if (position > Integer.MAX_VALUE) {
+ return IOUtils.EOF;
+ }
int wanted = buf.remaining();
- final int possible = size - position;
+ final int possible = size - (int) position;
if (possible <= 0) {
return IOUtils.EOF;
}
if (wanted > possible) {
wanted = possible;
}
- buf.put(data, position, wanted);
+ buf.put(data, (int) position, wanted);
position += wanted;
return wanted;
} finally {
@@ -238,14 +240,14 @@ public byte[] toByteArray() {
@Override
public SeekableByteChannel truncate(final long newSize) throws ClosedChannelException {
checkOpen();
- final int intSize = checkRange(newSize, "truncate()");
+ checkRange(newSize, "truncate()");
lock.lock();
try {
- if (size > intSize) {
- size = intSize;
+ if (size > newSize) {
+ size = (int) newSize;
}
- if (position > intSize) {
- position = intSize;
+ if (position > newSize) {
+ position = newSize;
}
} finally {
lock.unlock();
@@ -256,21 +258,28 @@ public SeekableByteChannel truncate(final long newSize) throws ClosedChannelExce
@Override
public int write(final ByteBuffer b) throws IOException {
checkOpen();
+ if (position > Integer.MAX_VALUE) {
+ throw new IOException("position > Integer.MAX_VALUE");
+ }
lock.lock();
try {
final int wanted = b.remaining();
- final int possibleWithoutResize = Math.max(0, size - position);
- if (wanted > possibleWithoutResize) {
- final int newSize = position + wanted;
- if (newSize < 0 || newSize > IOUtils.SOFT_MAX_ARRAY_LENGTH) { // overflow
- throw new OutOfMemoryError("required array size " + Integer.toUnsignedString(newSize) + " too large");
- }
- resize(newSize);
+ // intPos <= Integer.MAX_VALUE
+ final int intPos = (int) position;
+ final long newPosition = position + wanted;
+ if (newPosition > IOUtils.SOFT_MAX_ARRAY_LENGTH) {
+ throw new IOException(String.format("Requested array size %,d is too large.", newPosition));
}
- b.get(data, position, wanted);
- position += wanted;
- if (size < position) {
- size = position;
+ if (newPosition > size) {
+ final int newPositionInt = (int) newPosition;
+ // Ensure that newPositionInt ≤ data.length
+ resize(newPositionInt);
+ size = newPositionInt;
+ }
+ b.get(data, intPos, wanted);
+ position = newPosition;
+ if (size < intPos) {
+ size = intPos;
}
return wanted;
} finally {
diff --git a/src/main/java/org/apache/commons/io/channels/CloseShieldChannel.java b/src/main/java/org/apache/commons/io/channels/CloseShieldChannel.java
index a9a462da73b..ba890d8a6a7 100644
--- a/src/main/java/org/apache/commons/io/channels/CloseShieldChannel.java
+++ b/src/main/java/org/apache/commons/io/channels/CloseShieldChannel.java
@@ -19,7 +19,16 @@
import java.io.Closeable;
import java.lang.reflect.Proxy;
+import java.nio.channels.AsynchronousChannel;
+import java.nio.channels.ByteChannel;
import java.nio.channels.Channel;
+import java.nio.channels.GatheringByteChannel;
+import java.nio.channels.InterruptibleChannel;
+import java.nio.channels.NetworkChannel;
+import java.nio.channels.ReadableByteChannel;
+import java.nio.channels.ScatteringByteChannel;
+import java.nio.channels.SeekableByteChannel;
+import java.nio.channels.WritableByteChannel;
import java.util.LinkedHashSet;
import java.util.Objects;
import java.util.Set;
@@ -27,9 +36,23 @@
/**
* Creates a close-shielding proxy for a {@link Channel}.
*
- *
- * The returned proxy will implement all {@link Channel} sub-interfaces that the delegate implements.
- *
+ * The returned proxy implements all {@link Channel} sub-interfaces that are both supported by this implementation and actually implemented by the given
+ * delegate.
+ *
+ * The following interfaces are supported:
+ *
+ *
+ * - {@link AsynchronousChannel}
+ * - {@link ByteChannel}
+ * - {@link Channel}
+ * - {@link GatheringByteChannel}
+ * - {@link InterruptibleChannel}
+ * - {@link NetworkChannel}
+ * - {@link ReadableByteChannel}
+ * - {@link ScatteringByteChannel}
+ * - {@link SeekableByteChannel}
+ * - {@link WritableByteChannel}
+ *
*
* @see Channel
* @see Closeable
@@ -40,11 +63,15 @@ public final class CloseShieldChannel {
private static final Class[] EMPTY = {};
private static Set> collectChannelInterfaces(final Class type, final Set> out) {
+ Class currentType = type;
// Visit interfaces
- for (final Class iface : type.getInterfaces()) {
- if (Channel.class.isAssignableFrom(iface) && out.add(iface)) {
- collectChannelInterfaces(iface, out);
+ while (currentType != null) {
+ for (final Class iface : currentType.getInterfaces()) {
+ if (CloseShieldChannelHandler.isSupported(iface) && out.add(iface)) {
+ collectChannelInterfaces(iface, out);
+ }
}
+ currentType = currentType.getSuperclass();
}
return out;
}
@@ -53,8 +80,10 @@ private static Set> collectChannelInterfaces(final Class type, final
* Wraps a channel to shield it from being closed.
*
* @param channel The underlying channel to shield, not {@code null}.
- * @param Any Channel type (interface or class).
+ * @param A supported channel type.
* @return A proxy that shields {@code close()} and enforces closed semantics on other calls.
+ * @throws ClassCastException if {@code T} is not a supported channel type.
+ * @throws NullPointerException if {@code channel} is {@code null}.
*/
@SuppressWarnings({ "unchecked", "resource" }) // caller closes
public static T wrap(final T channel) {
diff --git a/src/main/java/org/apache/commons/io/channels/CloseShieldChannelHandler.java b/src/main/java/org/apache/commons/io/channels/CloseShieldChannelHandler.java
index f13b101c197..fdafd544f07 100644
--- a/src/main/java/org/apache/commons/io/channels/CloseShieldChannelHandler.java
+++ b/src/main/java/org/apache/commons/io/channels/CloseShieldChannelHandler.java
@@ -21,14 +21,41 @@
import java.lang.reflect.InvocationTargetException;
import java.lang.reflect.Method;
import java.lang.reflect.Proxy;
+import java.nio.channels.AsynchronousChannel;
+import java.nio.channels.ByteChannel;
import java.nio.channels.Channel;
import java.nio.channels.ClosedChannelException;
+import java.nio.channels.GatheringByteChannel;
+import java.nio.channels.InterruptibleChannel;
import java.nio.channels.NetworkChannel;
+import java.nio.channels.ReadableByteChannel;
+import java.nio.channels.ScatteringByteChannel;
import java.nio.channels.SeekableByteChannel;
+import java.nio.channels.WritableByteChannel;
+import java.util.Collections;
+import java.util.HashSet;
import java.util.Objects;
+import java.util.Set;
final class CloseShieldChannelHandler implements InvocationHandler {
+ private static final Set> SUPPORTED_INTERFACES;
+
+ static {
+ final Set> interfaces = new HashSet<>();
+ interfaces.add(AsynchronousChannel.class);
+ interfaces.add(ByteChannel.class);
+ interfaces.add(Channel.class);
+ interfaces.add(GatheringByteChannel.class);
+ interfaces.add(InterruptibleChannel.class);
+ interfaces.add(NetworkChannel.class);
+ interfaces.add(ReadableByteChannel.class);
+ interfaces.add(ScatteringByteChannel.class);
+ interfaces.add(SeekableByteChannel.class);
+ interfaces.add(WritableByteChannel.class);
+ SUPPORTED_INTERFACES = Collections.unmodifiableSet(interfaces);
+ }
+
/**
* Tests whether the given method is allowed to be called after the shield is closed.
*
@@ -42,6 +69,10 @@ private static boolean isAllowedAfterClose(final Class declaringClass, final
return parameterCount == 0 && name.equals("supportedOptions") && NetworkChannel.class.equals(declaringClass);
}
+ static boolean isSupported(final Class interfaceClass) {
+ return SUPPORTED_INTERFACES.contains(interfaceClass);
+ }
+
/**
* Tests whether the given method returns 'this' (the channel) as per JDK spec.
*
diff --git a/src/main/java/org/apache/commons/io/channels/FileChannels.java b/src/main/java/org/apache/commons/io/channels/FileChannels.java
index 30a80e8ab6b..6629ead4931 100644
--- a/src/main/java/org/apache/commons/io/channels/FileChannels.java
+++ b/src/main/java/org/apache/commons/io/channels/FileChannels.java
@@ -91,10 +91,7 @@ public static boolean contentEquals(final ReadableByteChannel channel1, final Re
Thread.yield();
continue;
}
- if (c1NumRead != c2NumRead) {
- return false;
- }
- if (!c1Buffer.equals(c2Buffer)) {
+ if (c1NumRead != c2NumRead || !c1Buffer.equals(c2Buffer)) {
return false;
}
}
@@ -135,7 +132,7 @@ public static boolean contentEquals(final SeekableByteChannel channel1, final Se
*
* @param channel The source channel.
* @param dst The buffer into which bytes are to be transferred.
- * @return The number of bytes read, never zero, or {@code -1} if the channel has reached end-of-stream
+ * @return The number of bytes read, never zero, or {@code -1} if the channel has reached end-of-stream.
* @throws IOException If some other I/O error occurs.
* @throws IllegalArgumentException If there is room in the given buffer.
*/
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 8595be79e8a..a8aa9a3d50b 100644
--- a/src/main/java/org/apache/commons/io/charset/CharsetDecoders.java
+++ b/src/main/java/org/apache/commons/io/charset/CharsetDecoders.java
@@ -30,7 +30,7 @@ public final class CharsetDecoders {
/**
* Returns the given non-null CharsetDecoder or a new default CharsetDecoder.
*
- * Null input maps to the virtual machine's {@link Charset#defaultCharset() default charset} decoder.
+ * Null input maps to the virtual machine's {@linkplain Charset#defaultCharset() default charset} decoder.
*
*
* @param charsetDecoder The CharsetDecoder to test.
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 d0f9cd04be1..a1fff5cf1f3 100644
--- a/src/main/java/org/apache/commons/io/charset/CharsetEncoders.java
+++ b/src/main/java/org/apache/commons/io/charset/CharsetEncoders.java
@@ -31,7 +31,7 @@ public final class CharsetEncoders {
/**
* Returns the given non-null CharsetEncoder or a new default CharsetEncoder.
*
- * Null input maps to the virtual machine's {@link Charset#defaultCharset() default charset} decoder.
+ * Null input maps to the virtual machine's {@linkplain Charset#defaultCharset() default charset} decoder.
*
*
* @param charsetEncoder The CharsetEncoder to test.
diff --git a/src/main/java/org/apache/commons/io/comparator/CompositeFileComparator.java b/src/main/java/org/apache/commons/io/comparator/CompositeFileComparator.java
index 0934f895f7a..dcc2d20428e 100644
--- a/src/main/java/org/apache/commons/io/comparator/CompositeFileComparator.java
+++ b/src/main/java/org/apache/commons/io/comparator/CompositeFileComparator.java
@@ -58,7 +58,7 @@ public class CompositeFileComparator extends AbstractFileComparator implements S
/**
* Constructs a composite comparator for the set of delegate comparators.
*
- * @param delegates The delegate file comparators
+ * @param delegates The delegate file comparators.
*/
public CompositeFileComparator(@SuppressWarnings("unchecked") final Comparator... delegates) {
this.delegates = delegates == null ? emptyArray() : delegates.clone();
@@ -67,7 +67,7 @@ public CompositeFileComparator(@SuppressWarnings("unchecked") final Comparator> delegates) {
this.delegates = delegates == null ? emptyArray()
@@ -77,8 +77,8 @@ public CompositeFileComparator(final Iterable> delegates) {
/**
* Compares the two files using delegate comparators.
*
- * @param file1 The first file to compare
- * @param file2 The second file to compare
+ * @param file1 The first file to compare.
+ * @param file2 The second file to compare.
* @return the first non-zero result returned from the delegate comparators or zero.
*/
@Override
@@ -94,7 +94,7 @@ private Comparator[] emptyArray() {
/**
* String representation of this file comparator.
*
- * @return String representation of this file comparator
+ * @return String representation of this file comparator.
*/
@Override
public String toString() {
diff --git a/src/main/java/org/apache/commons/io/comparator/DefaultFileComparator.java b/src/main/java/org/apache/commons/io/comparator/DefaultFileComparator.java
index c447f085198..db580a1a2e1 100644
--- a/src/main/java/org/apache/commons/io/comparator/DefaultFileComparator.java
+++ b/src/main/java/org/apache/commons/io/comparator/DefaultFileComparator.java
@@ -69,8 +69,8 @@ public DefaultFileComparator() {
/**
* Compares the two files using the {@link File#compareTo(File)} method.
*
- * @param file1 The first file to compare
- * @param file2 The second file to compare
+ * @param file1 The first file to compare.
+ * @param file2 The second file to compare.
* @return the result of calling file1's
* {@link File#compareTo(File)} with file2 as the parameter.
*/
diff --git a/src/main/java/org/apache/commons/io/comparator/ExtensionFileComparator.java b/src/main/java/org/apache/commons/io/comparator/ExtensionFileComparator.java
index 3b4e1e2e115..1d57ec8164f 100644
--- a/src/main/java/org/apache/commons/io/comparator/ExtensionFileComparator.java
+++ b/src/main/java/org/apache/commons/io/comparator/ExtensionFileComparator.java
@@ -93,7 +93,7 @@ public ExtensionFileComparator() {
/**
* Constructs a file extension comparator instance with the specified case-sensitivity.
*
- * @param ioCase how to handle case sensitivity, null means case-sensitive
+ * @param ioCase how to handle case sensitivity, null means case-sensitive.
*/
public ExtensionFileComparator(final IOCase ioCase) {
this.ioCase = IOCase.value(ioCase, IOCase.SENSITIVE);
@@ -102,8 +102,8 @@ public ExtensionFileComparator(final IOCase ioCase) {
/**
* Compares the extensions of two files the specified case sensitivity.
*
- * @param file1 The first file to compare
- * @param file2 The second file to compare
+ * @param file1 The first file to compare.
+ * @param file2 The second file to compare.
* @return a negative value if the first file's extension
* is less than the second, zero if the extensions are the
* same and a positive value if the first files extension
@@ -119,7 +119,7 @@ public int compare(final File file1, final File file2) {
/**
* String representation of this file comparator.
*
- * @return String representation of this file comparator
+ * @return String representation of this file comparator.
*/
@Override
public String toString() {
diff --git a/src/main/java/org/apache/commons/io/comparator/NameFileComparator.java b/src/main/java/org/apache/commons/io/comparator/NameFileComparator.java
index 41590fa6636..7e92a7fcb74 100644
--- a/src/main/java/org/apache/commons/io/comparator/NameFileComparator.java
+++ b/src/main/java/org/apache/commons/io/comparator/NameFileComparator.java
@@ -89,7 +89,7 @@ public NameFileComparator() {
/**
* Constructs a file name comparator instance with the specified case-sensitivity.
*
- * @param ioCase how to handle case sensitivity, null means case-sensitive
+ * @param ioCase how to handle case sensitivity, null means case-sensitive.
*/
public NameFileComparator(final IOCase ioCase) {
this.ioCase = IOCase.value(ioCase, IOCase.SENSITIVE);
@@ -98,8 +98,8 @@ public NameFileComparator(final IOCase ioCase) {
/**
* Compares the names of two files with the specified case sensitivity.
*
- * @param file1 The first file to compare
- * @param file2 The second file to compare
+ * @param file1 The first file to compare.
+ * @param file2 The second file to compare.
* @return a negative value if the first file's name
* is less than the second, zero if the names are the
* same and a positive value if the first files name
@@ -113,7 +113,7 @@ public int compare(final File file1, final File file2) {
/**
* String representation of this file comparator.
*
- * @return String representation of this file comparator
+ * @return String representation of this file comparator.
*/
@Override
public String toString() {
diff --git a/src/main/java/org/apache/commons/io/comparator/PathFileComparator.java b/src/main/java/org/apache/commons/io/comparator/PathFileComparator.java
index 1f41eb74185..4ae379add58 100644
--- a/src/main/java/org/apache/commons/io/comparator/PathFileComparator.java
+++ b/src/main/java/org/apache/commons/io/comparator/PathFileComparator.java
@@ -51,6 +51,7 @@
*
* Serialization is deprecated and will be removed in 3.0.
*
+ *
* @since 1.4
*/
public class PathFileComparator extends AbstractFileComparator implements Serializable {
@@ -88,7 +89,7 @@ public PathFileComparator() {
/**
* Constructs a file path comparator instance with the specified case-sensitivity.
*
- * @param ioCase how to handle case sensitivity, null means case-sensitive
+ * @param ioCase how to handle case sensitivity, null means case-sensitive.
*/
public PathFileComparator(final IOCase ioCase) {
this.ioCase = IOCase.value(ioCase, IOCase.SENSITIVE);
@@ -97,8 +98,8 @@ public PathFileComparator(final IOCase ioCase) {
/**
* Compares the paths of two files the specified case sensitivity.
*
- * @param file1 The first file to compare
- * @param file2 The second file to compare
+ * @param file1 The first file to compare.
+ * @param file2 The second file to compare.
* @return a negative value if the first file's path
* is less than the second, zero if the paths are the
* same and a positive value if the first files path
@@ -112,7 +113,7 @@ public int compare(final File file1, final File file2) {
/**
* String representation of this file comparator.
*
- * @return String representation of this file comparator
+ * @return String representation of this file comparator.
*/
@Override
public String toString() {
diff --git a/src/main/java/org/apache/commons/io/comparator/SizeFileComparator.java b/src/main/java/org/apache/commons/io/comparator/SizeFileComparator.java
index 5154d9b3256..a5ff78c0e59 100644
--- a/src/main/java/org/apache/commons/io/comparator/SizeFileComparator.java
+++ b/src/main/java/org/apache/commons/io/comparator/SizeFileComparator.java
@@ -107,8 +107,8 @@ public SizeFileComparator(final boolean sumDirectoryContents) {
/**
* Compares the length of two files.
*
- * @param file1 The first file to compare
- * @param file2 The second file to compare
+ * @param file1 The first file to compare.
+ * @param file2 The second file to compare.
* @return a negative value if the first file's length
* is less than the second, zero if the lengths are the
* same and a positive value if the first files length
@@ -141,7 +141,7 @@ public int compare(final File file1, final File file2) {
/**
* String representation of this file comparator.
*
- * @return String representation of this file comparator
+ * @return String representation of this file comparator.
*/
@Override
public String toString() {
diff --git a/src/main/java/org/apache/commons/io/doc-files/leaf.svg b/src/main/java/org/apache/commons/io/doc-files/leaf.svg
new file mode 100644
index 00000000000..71de588c648
--- /dev/null
+++ b/src/main/java/org/apache/commons/io/doc-files/leaf.svg
@@ -0,0 +1,45 @@
+
+
+
\ No newline at end of file
diff --git a/src/main/java/org/apache/commons/io/doc-files/logo.png b/src/main/java/org/apache/commons/io/doc-files/logo.png
new file mode 100644
index 00000000000..02a758f0ed8
Binary files /dev/null and b/src/main/java/org/apache/commons/io/doc-files/logo.png differ
diff --git a/src/main/java/org/apache/commons/io/file/AccumulatorPathVisitor.java b/src/main/java/org/apache/commons/io/file/AccumulatorPathVisitor.java
index 1551231cfaf..3be7a325315 100644
--- a/src/main/java/org/apache/commons/io/file/AccumulatorPathVisitor.java
+++ b/src/main/java/org/apache/commons/io/file/AccumulatorPathVisitor.java
@@ -195,7 +195,6 @@ public AccumulatorPathVisitor(final PathCounters pathCounter, final PathFilter f
* @since 2.12.0
* @deprecated Use {@link #builder()}.
*/
- @SuppressWarnings("deprecation")
@Deprecated
public AccumulatorPathVisitor(final PathCounters pathCounter, final PathFilter fileFilter, final PathFilter dirFilter,
final IOBiFunction visitFileFailed) {
@@ -251,10 +250,10 @@ public int hashCode() {
* Relativizes each directory path with {@link Path#relativize(Path)} against the given {@code parent}, optionally
* sorting the result.
*
- * @param parent A parent path
- * @param sort Whether to sort
+ * @param parent A parent path.
+ * @param sort Whether to sort.
* @param comparator How to sort, null uses default sorting.
- * @return A new list
+ * @return A new list.
*/
public List relativizeDirectories(final Path parent, final boolean sort,
final Comparator comparator) {
@@ -265,10 +264,10 @@ public List relativizeDirectories(final Path parent, final boolean sort,
* Relativizes each file path with {@link Path#relativize(Path)} against the given {@code parent}, optionally
* sorting the result.
*
- * @param parent A parent path
- * @param sort Whether to sort
+ * @param parent A parent path.
+ * @param sort Whether to sort.
* @param comparator How to sort, null uses default sorting.
- * @return A new list
+ * @return A new list.
*/
public List relativizeFiles(final Path parent, final boolean sort,
final Comparator comparator) {
diff --git a/src/main/java/org/apache/commons/io/file/CopyDirectoryVisitor.java b/src/main/java/org/apache/commons/io/file/CopyDirectoryVisitor.java
index 7172b2d0671..45b761c971c 100644
--- a/src/main/java/org/apache/commons/io/file/CopyDirectoryVisitor.java
+++ b/src/main/java/org/apache/commons/io/file/CopyDirectoryVisitor.java
@@ -48,8 +48,8 @@ private static CopyOption[] toCopyOption(final CopyOption... copyOptions) {
* Constructs an instance that copies all files.
*
* @param pathCounter How to count visits.
- * @param sourceDirectory The source directory
- * @param targetDirectory The target directory
+ * @param sourceDirectory The source directory.
+ * @param targetDirectory The target directory.
* @param copyOptions Specifies how the copying should be done.
*/
public CopyDirectoryVisitor(final PathCounters pathCounter, final Path sourceDirectory, final Path targetDirectory, final CopyOption... copyOptions) {
@@ -65,8 +65,8 @@ public CopyDirectoryVisitor(final PathCounters pathCounter, final Path sourceDir
* @param pathCounter How to count visits.
* @param fileFilter How to filter file paths.
* @param dirFilter How to filter directory paths.
- * @param sourceDirectory The source directory
- * @param targetDirectory The target directory
+ * @param sourceDirectory The source directory.
+ * @param targetDirectory The target directory.
* @param copyOptions Specifies how the copying should be done.
* @since 2.9.0
*/
diff --git a/src/main/java/org/apache/commons/io/file/Counters.java b/src/main/java/org/apache/commons/io/file/Counters.java
index b1abd721d9c..10e05dc48f7 100644
--- a/src/main/java/org/apache/commons/io/file/Counters.java
+++ b/src/main/java/org/apache/commons/io/file/Counters.java
@@ -455,7 +455,7 @@ public static PathCounters noopPathCounters() {
/**
* Construct a new instance.
*
- * @deprecated Will be private in 4.0
+ * @deprecated Will be private in 3.0.
*/
@Deprecated
public Counters() {
diff --git a/src/main/java/org/apache/commons/io/file/PathFilter.java b/src/main/java/org/apache/commons/io/file/PathFilter.java
index dbeef906261..ee54de29deb 100644
--- a/src/main/java/org/apache/commons/io/file/PathFilter.java
+++ b/src/main/java/org/apache/commons/io/file/PathFilter.java
@@ -34,7 +34,7 @@ public interface PathFilter {
*
* @param path The Path to test.
* @param attributes the path's basic attributes (may be null).
- * @return a FileVisitResult
+ * @return a FileVisitResult.
*/
FileVisitResult accept(Path path, BasicFileAttributes attributes);
}
diff --git a/src/main/java/org/apache/commons/io/file/PathUtils.java b/src/main/java/org/apache/commons/io/file/PathUtils.java
index 055bbe06a0b..6a9718c4c07 100644
--- a/src/main/java/org/apache/commons/io/file/PathUtils.java
+++ b/src/main/java/org/apache/commons/io/file/PathUtils.java
@@ -200,32 +200,38 @@ private RelativeSortedPaths(final Path dir1, final Path dir2, final int maxDepth
private static final OpenOption[] OPEN_OPTIONS_TRUNCATE = { StandardOpenOption.CREATE, StandardOpenOption.TRUNCATE_EXISTING };
private static final OpenOption[] OPEN_OPTIONS_APPEND = { StandardOpenOption.CREATE, StandardOpenOption.APPEND };
+
/**
* Empty {@link CopyOption} array.
*
* @since 2.8.0
*/
public static final CopyOption[] EMPTY_COPY_OPTIONS = {};
+
/**
* Empty {@link DeleteOption} array.
*
* @since 2.8.0
*/
public static final DeleteOption[] EMPTY_DELETE_OPTION_ARRAY = {};
+
/**
* Empty {@link FileAttribute} array.
*
* @since 2.13.0
*/
public static final FileAttribute[] EMPTY_FILE_ATTRIBUTE_ARRAY = {};
+
/**
* Empty {@link FileVisitOption} array.
*/
public static final FileVisitOption[] EMPTY_FILE_VISIT_OPTION_ARRAY = {};
+
/**
* Empty {@link LinkOption} array.
*/
public static final LinkOption[] EMPTY_LINK_OPTION_ARRAY = {};
+
/**
* {@link LinkOption} array for {@link LinkOption#NOFOLLOW_LINKS}.
*
@@ -234,16 +240,19 @@ private RelativeSortedPaths(final Path dir1, final Path dir2, final int maxDepth
*/
@Deprecated
public static final LinkOption[] NOFOLLOW_LINK_OPTION_ARRAY = { LinkOption.NOFOLLOW_LINKS };
+
/**
* A LinkOption used to follow link in this class, the inverse of {@link LinkOption#NOFOLLOW_LINKS}.
*
* @since 2.12.0
*/
static final LinkOption NULL_LINK_OPTION = null;
+
/**
* Empty {@link OpenOption} array.
*/
public static final OpenOption[] EMPTY_OPEN_OPTION_ARRAY = {};
+
/**
* Empty {@link Path} array.
*
@@ -378,7 +387,7 @@ public static PathCounters copyDirectory(final Path sourceDirectory, final Path
* @param sourceFile The source URL.
* @param targetFile The target file.
* @param copyOptions Specifies how the copying should be done.
- * @return The target file
+ * @return The target file.
* @throws IOException if an I/O error occurs.
* @see Files#copy(InputStream, Path, CopyOption...)
*/
@@ -393,7 +402,7 @@ public static Path copyFile(final URL sourceFile, final Path targetFile, final C
* @param sourceFile The source file.
* @param targetDirectory The target directory.
* @param copyOptions Specifies how the copying should be done.
- * @return The target file
+ * @return The target file.
* @throws IOException if an I/O error occurs.
* @see Files#copy(Path, Path, CopyOption...)
*/
@@ -410,7 +419,7 @@ public static Path copyFileToDirectory(final Path sourceFile, final Path targetD
* @param sourceFile The source URL.
* @param targetDirectory The target directory.
* @param copyOptions Specifies how the copying should be done.
- * @return The target file
+ * @return The target file.
* @throws IOException if an I/O error occurs.
* @see Files#copy(InputStream, Path, CopyOption...)
*/
@@ -499,7 +508,7 @@ public static Path current() {
*
*
* - A directory to delete does not have to be empty.
- * - You get exceptions when a file or directory cannot be deleted; {@link File#delete()} returns a boolean.
+ *
- You get exceptions when a file or directory cannot be deleted; {@link File#delete()} returns a boolean.
*
*
* @param path file or directory to delete, must not be {@code null}
@@ -518,7 +527,7 @@ public static PathCounters delete(final Path path) throws IOException {
*
*
* - A directory to delete does not have to be empty.
- * - You get exceptions when a file or directory cannot be deleted; {@link File#delete()} returns a boolean.
+ *
- You get exceptions when a file or directory cannot be deleted; {@link File#delete()} returns a boolean.
*
*
* @param path file or directory to delete, must not be {@code null}
@@ -540,7 +549,7 @@ public static PathCounters delete(final Path path, final DeleteOption... deleteO
*
*
* - A directory to delete does not have to be empty.
- * - You get exceptions when a file or directory cannot be deleted; {@link File#delete()} returns a boolean.
+ *
- You get exceptions when a file or directory cannot be deleted; {@link File#delete()} returns a boolean.
*
*
* @param path file or directory to delete, must not be {@code null}
@@ -603,7 +612,7 @@ public static PathCounters deleteDirectory(final Path directory, final LinkOptio
* @param file The file to delete.
* @return A visitor with path counts set to 1 file, 0 directories, and the size of the deleted file.
* @throws IOException if an I/O error occurs.
- * @throws NoSuchFileException if the file is a directory
+ * @throws NoSuchFileException if the file is a directory.
*/
public static PathCounters deleteFile(final Path file) throws IOException {
return deleteFile(file, EMPTY_DELETE_OPTION_ARRAY);
@@ -771,7 +780,7 @@ public static boolean directoryContentEquals(final Path path1, final Path path2)
* @param path2 The second directory.
* @param maxDepth See {@link Files#walkFileTree(Path,Set,int,FileVisitor)}.
* @param linkOptions options to follow links.
- * @param fileVisitOptions options to configure the traversal
+ * @param fileVisitOptions options to configure the traversal.
* @return Whether the two directories contain the same files without considering file contents.
* @throws IOException if an I/O error is thrown by a visitor method.
*/
@@ -944,7 +953,7 @@ public static AclFileAttributeView getAclFileAttributeView(final Path path, fina
* Will return the file name itself if it doesn't contain any periods. All leading directories of the {@code file name} parameter are skipped.
*
*
- * @return the base name of file name
+ * @return the base name of file name.
* @param path the path of the file to obtain the base name of.
* @since 2.16.0
*/
@@ -1136,7 +1145,7 @@ public static Path getTempDirectory() {
* {@code Files.isDirectory(Path path, LinkOption... options)}.
*
* @param path the path to the file.
- * @param options options indicating how to handle symbolic links
+ * @param options options indicating how to handle symbolic links.
* @return {@code true} if the file is a directory; {@code false} if the path is null, the file does not exist, is not a directory, or it cannot be
* determined if the file is a directory or not.
* @throws SecurityException In the case of the default provider, and a security manager is installed, the {@link SecurityManager#checkRead(String)
@@ -1240,7 +1249,7 @@ public static boolean isNewer(final Path file, final Instant instant, final Link
* Tests if the given {@link Path} is newer than the given time reference.
*
* @param file the {@link Path} to test.
- * @param timeMillis the time reference measured in milliseconds since the epoch (00:00:00 GMT, January 1, 1970)
+ * @param timeMillis the time reference measured in milliseconds since the epoch (00:00:00 GMT, January 1, 1970).
* @param options options indicating how to handle symbolic links.
* @return true if the {@link Path} exists and has been modified after the given time reference.
* @throws IOException if an I/O error occurs.
@@ -1301,7 +1310,7 @@ public static boolean isOlder(final Path file, final Instant instant, final Link
* Tests if the given {@link Path} is older than the given time reference.
*
* @param file the {@link Path} to test.
- * @param timeMillis the time reference measured in milliseconds since the epoch (00:00:00 GMT, January 1, 1970)
+ * @param timeMillis the time reference measured in milliseconds since the epoch (00:00:00 GMT, January 1, 1970).
* @param options options indicating how to handle symbolic links.
* @return true if the {@link Path} exists and has been modified before the given time reference.
* @throws IOException if an I/O error occurs.
@@ -1412,7 +1421,7 @@ private static boolean notExists(final Path path, final LinkOption... options) {
/**
* Returns true if the given options contain {@link StandardDeleteOption#OVERRIDE_READ_ONLY}.
*
- * @param deleteOptions the array to test
+ * @param deleteOptions the array to test.
* @return true if the given options contain {@link StandardDeleteOption#OVERRIDE_READ_ONLY}.
*/
private static boolean overrideReadOnly(final DeleteOption... deleteOptions) {
@@ -1425,7 +1434,7 @@ private static boolean overrideReadOnly(final DeleteOption... deleteOptions) {
/**
* Reads the BasicFileAttributes from the given path. Returns null if the attributes can't be read.
*
- * @param The {@link BasicFileAttributes} type
+ * @param The {@link BasicFileAttributes} type.
* @param path The Path to test.
* @param type the {@link Class} of the file attributes required to read.
* @param options options indicating how to handle symbolic links.
@@ -1827,7 +1836,7 @@ private static List toSortedList(final Iterable rootDirectories) {
* @param file the file to touch.
* @return The given file.
* @throws NullPointerException if the parameter is {@code null}.
- * @throws IOException if setting the last-modified time failed or an I/O problem occurs.\
+ * @throws IOException if setting the last-modified time failed or an I/O problem occurs.
* @since 2.12.0
*/
public static Path touch(final Path file) throws IOException {
@@ -1957,8 +1966,8 @@ public static boolean waitFor(final Path file, final Duration timeout, final Lin
* closed stream causes a {@link IllegalStateException}.
*
*
- * @param start the start path
- * @param pathFilter the path filter
+ * @param start the start path.
+ * @param pathFilter the path filter.
* @param maxDepth the maximum depth of directories to walk.
* @param readAttributes whether to call the filters with file attributes (false passes null).
* @param options the options to configure the walk.
diff --git a/src/main/java/org/apache/commons/io/file/StandardDeleteOption.java b/src/main/java/org/apache/commons/io/file/StandardDeleteOption.java
index e66dff6473e..b4cc6cb1d5e 100644
--- a/src/main/java/org/apache/commons/io/file/StandardDeleteOption.java
+++ b/src/main/java/org/apache/commons/io/file/StandardDeleteOption.java
@@ -38,7 +38,7 @@ public enum StandardDeleteOption implements DeleteOption {
*
* For now, assume the array is not sorted.
*
- * @param options the array to test
+ * @param options the array to test.
* @return true if the given options contain {@link StandardDeleteOption#OVERRIDE_READ_ONLY}.
*/
public static boolean overrideReadOnly(final DeleteOption[] options) {
diff --git a/src/main/java/org/apache/commons/io/file/attribute/FileTimes.java b/src/main/java/org/apache/commons/io/file/attribute/FileTimes.java
index 35725357f9c..2878d8752d7 100644
--- a/src/main/java/org/apache/commons/io/file/attribute/FileTimes.java
+++ b/src/main/java/org/apache/commons/io/file/attribute/FileTimes.java
@@ -308,7 +308,7 @@ static long toNtfsTime(final Instant instant) {
* An NTFS file time is a 64-bit value for the number of 100-nanosecond intervals since 12:00 A.M. January 1, 1601 Coordinated Universal Time (UTC).
*
*
- * @param javaTime the Java time
+ * @param javaTime the Java time.
* @return the NTFS time, 100-nanosecond units since 1 January 1601.
* @since 2.16.0
*/
diff --git a/src/main/java/org/apache/commons/io/file/spi/FileSystemProviders.java b/src/main/java/org/apache/commons/io/file/spi/FileSystemProviders.java
index 2483cef0a20..4e83ffe1e8c 100644
--- a/src/main/java/org/apache/commons/io/file/spi/FileSystemProviders.java
+++ b/src/main/java/org/apache/commons/io/file/spi/FileSystemProviders.java
@@ -39,7 +39,7 @@ public class FileSystemProviders { // NOPMD Class will be final in 3.0.
/**
* Gets the {@link FileSystemProvider} for the given Path.
*
- * @param path The Path to query
+ * @param path The Path to query.
* @return the {@link FileSystemProvider} for the given Path.
*/
@SuppressWarnings("resource") // FileSystem is not allocated here.
@@ -86,7 +86,7 @@ public FileSystemProvider getFileSystemProvider(final String scheme) {
/**
* Gets the {@link FileSystemProvider} for the given URI.
*
- * @param uri The URI to query
+ * @param uri The URI to query.
* @return the {@link FileSystemProvider} for the given URI or null.
*/
public FileSystemProvider getFileSystemProvider(final URI uri) {
@@ -96,7 +96,7 @@ public FileSystemProvider getFileSystemProvider(final URI uri) {
/**
* Gets the {@link FileSystemProvider} for the given URL.
*
- * @param url The URL to query
+ * @param url The URL to query.
* @return the {@link FileSystemProvider} for the given URI or null.
*/
public FileSystemProvider getFileSystemProvider(final URL url) {
diff --git a/src/main/java/org/apache/commons/io/filefilter/AbstractFileFilter.java b/src/main/java/org/apache/commons/io/filefilter/AbstractFileFilter.java
index c71867d14da..b16e86eaf14 100644
--- a/src/main/java/org/apache/commons/io/filefilter/AbstractFileFilter.java
+++ b/src/main/java/org/apache/commons/io/filefilter/AbstractFileFilter.java
@@ -77,8 +77,8 @@ protected AbstractFileFilter(final FileVisitResult onAccept, final FileVisitResu
/**
* Tests to see if the File should be accepted by this filter.
*
- * @param file the File to check
- * @return true if this file matches the test
+ * @param file the File to check.
+ * @return true if this file matches the test.
*/
@Override
public boolean accept(final File file) {
@@ -89,9 +89,9 @@ public boolean accept(final File file) {
/**
* Tests to see if the File should be accepted by this filter.
*
- * @param dir the directory File to check
- * @param name the file name within the directory to check
- * @return true if this file matches the test
+ * @param dir the directory File to check.
+ * @param name the file name within the directory to check.
+ * @return true if this file matches the test.
*/
@Override
public boolean accept(final File dir, final String name) {
@@ -167,7 +167,7 @@ FileVisitResult toFileVisitResult(final boolean accept) {
/**
* Provides a String representation of this file filter.
*
- * @return a String representation
+ * @return a String representation.
*/
@Override
public String toString() {
diff --git a/src/main/java/org/apache/commons/io/filefilter/AgeFileFilter.java b/src/main/java/org/apache/commons/io/filefilter/AgeFileFilter.java
index 35542cfd486..9d95794ce28 100644
--- a/src/main/java/org/apache/commons/io/filefilter/AgeFileFilter.java
+++ b/src/main/java/org/apache/commons/io/filefilter/AgeFileFilter.java
@@ -89,7 +89,7 @@ public class AgeFileFilter extends AbstractFileFilter implements Serializable {
/**
* Constructs a new age file filter for files older than (at or before) a certain cutoff date.
*
- * @param cutoffDate the threshold age of the files
+ * @param cutoffDate the threshold age of the files.
*/
public AgeFileFilter(final Date cutoffDate) {
this(cutoffDate, true);
@@ -98,7 +98,7 @@ public AgeFileFilter(final Date cutoffDate) {
/**
* Constructs a new age file filter for files on any one side of a certain cutoff date.
*
- * @param cutoffDate the threshold age of the files
+ * @param cutoffDate the threshold age of the files.
* @param acceptOlder if true, older files (at or before the cutoff) are accepted, else newer ones (after the
* cutoff).
*/
@@ -110,7 +110,7 @@ public AgeFileFilter(final Date cutoffDate, final boolean acceptOlder) {
* Constructs a new age file filter for files older than (at or before) a certain File (whose last modification time
* will be used as reference).
*
- * @param cutoffReference the file whose last modification time is used as the threshold age of the files
+ * @param cutoffReference the file whose last modification time is used as the threshold age of the files.
*/
public AgeFileFilter(final File cutoffReference) {
this(cutoffReference, true);
@@ -120,7 +120,7 @@ public AgeFileFilter(final File cutoffReference) {
* Constructs a new age file filter for files on any one side of a certain File (whose last modification time will
* be used as reference).
*
- * @param cutoffReference the file whose last modification time is used as the threshold age of the files
+ * @param cutoffReference the file whose last modification time is used as the threshold age of the files.
* @param acceptOlder if true, older files (at or before the cutoff) are accepted, else newer ones (after the
* cutoff).
*/
@@ -179,8 +179,8 @@ public AgeFileFilter(final long cutoffMillis, final boolean acceptOlder) {
* modification time equals cutoff and older files are required, file IS selected.
*
*
- * @param file the File to check
- * @return true if the file name matches
+ * @param file the File to check.
+ * @return true if the file name matches.
*/
@Override
public boolean accept(final File file) {
@@ -194,9 +194,9 @@ public boolean accept(final File file) {
* modification time equals cutoff and older files are required, file IS selected.
*
*
- * @param file the File to check
+ * @param file the File to check.
* @param attributes the path's basic attributes (may be null).
- * @return true if the file name matches
+ * @return true if the file name matches.
* @since 2.9.0
*/
@Override
@@ -207,7 +207,7 @@ public FileVisitResult accept(final Path file, final BasicFileAttributes attribu
/**
* Provide a String representation of this file filter.
*
- * @return a String representation
+ * @return a String representation.
*/
@Override
public String toString() {
diff --git a/src/main/java/org/apache/commons/io/filefilter/AndFileFilter.java b/src/main/java/org/apache/commons/io/filefilter/AndFileFilter.java
index f8da16bcb0e..5b9a142f70c 100644
--- a/src/main/java/org/apache/commons/io/filefilter/AndFileFilter.java
+++ b/src/main/java/org/apache/commons/io/filefilter/AndFileFilter.java
@@ -17,7 +17,6 @@
package org.apache.commons.io.filefilter;
import java.io.File;
-import java.io.FileFilter;
import java.io.Serializable;
import java.nio.file.FileVisitResult;
import java.nio.file.Path;
@@ -29,7 +28,7 @@
import java.util.stream.Stream;
/**
- * A {@link FileFilter} providing conditional AND logic across a list of
+ * A {@link ConditionalFileFilter} providing conditional AND logic across a list of
* file filters. This filter returns {@code true} if all filters in the
* list return {@code true}. Otherwise, it returns {@code false}.
* Checking of the file filter list stops when the first filter returns
@@ -90,9 +89,9 @@ public AndFileFilter(final IOFileFilter... fileFilters) {
/**
* Constructs a new file filter that ANDs the result of other filters.
*
- * @param filter1 the first filter, must second be null
- * @param filter2 the first filter, must not be null
- * @throws IllegalArgumentException if either filter is null
+ * @param filter1 the first filter, must second be null.
+ * @param filter2 the first filter, must not be null.
+ * @throws IllegalArgumentException if either filter is null.
*/
public AndFileFilter(final IOFileFilter filter1, final IOFileFilter filter2) {
this(2);
@@ -129,6 +128,7 @@ public boolean accept(final File file, final String name) {
/**
* {@inheritDoc}
+ *
* @since 2.9.0
*/
@Override
@@ -187,7 +187,7 @@ public void setFileFilters(final List fileFilters) {
/**
* Builds a String representation of this file filter.
*
- * @return a String representation
+ * @return a String representation.
*/
@Override
public String toString() {
diff --git a/src/main/java/org/apache/commons/io/filefilter/CanExecuteFileFilter.java b/src/main/java/org/apache/commons/io/filefilter/CanExecuteFileFilter.java
index 3941a9d74a8..8f262806119 100644
--- a/src/main/java/org/apache/commons/io/filefilter/CanExecuteFileFilter.java
+++ b/src/main/java/org/apache/commons/io/filefilter/CanExecuteFileFilter.java
@@ -24,7 +24,7 @@
import java.nio.file.attribute.BasicFileAttributes;
/**
- * This filter accepts {@link File}s that can be executed.
+ * This filter accepts {@link File}s that are executable.
*
* Example, showing how to print out a list of the
* current directory's executable files:
diff --git a/src/main/java/org/apache/commons/io/filefilter/CanReadFileFilter.java b/src/main/java/org/apache/commons/io/filefilter/CanReadFileFilter.java
index da376e0f4f5..58d2ad7a50c 100644
--- a/src/main/java/org/apache/commons/io/filefilter/CanReadFileFilter.java
+++ b/src/main/java/org/apache/commons/io/filefilter/CanReadFileFilter.java
@@ -24,7 +24,7 @@
import java.nio.file.attribute.BasicFileAttributes;
/**
- * This filter accepts {@link File}s that can be read.
+ * This filter accepts {@link File}s that are readable.
*
* Example, showing how to print out a list of the current directory's readable files:
*
diff --git a/src/main/java/org/apache/commons/io/filefilter/CanWriteFileFilter.java b/src/main/java/org/apache/commons/io/filefilter/CanWriteFileFilter.java
index 899481c6465..db209b4a50e 100644
--- a/src/main/java/org/apache/commons/io/filefilter/CanWriteFileFilter.java
+++ b/src/main/java/org/apache/commons/io/filefilter/CanWriteFileFilter.java
@@ -24,7 +24,7 @@
import java.nio.file.attribute.BasicFileAttributes;
/**
- * This filter accepts {@link File}s that can be written to.
+ * This filter accepts {@link File}s that are writable.
*
* Example, showing how to print out a list of the current directory's writable files:
*
@@ -54,6 +54,7 @@
* Serialization is deprecated and will be removed in 3.0.
*
*
+ * @see Files#isWritable(Path)
* @since 1.3
*/
public class CanWriteFileFilter extends AbstractFileFilter implements Serializable {
@@ -75,7 +76,7 @@ protected CanWriteFileFilter() {
/**
* Tests to see if the file can be written to.
*
- * @param file the File to check
+ * @param file the File to check.
* @return {@code true} if the file can be written to, otherwise {@code false}.
*/
@Override
@@ -86,7 +87,7 @@ public boolean accept(final File file) {
/**
* Tests to see if the file can be written to.
*
- * @param file the File to check
+ * @param file the File to check.
* @param attributes the path's basic attributes (may be null).
* @return {@code true} if the file can be written to, otherwise {@code false}.
* @since 2.9.0
diff --git a/src/main/java/org/apache/commons/io/filefilter/ConditionalFileFilter.java b/src/main/java/org/apache/commons/io/filefilter/ConditionalFileFilter.java
index d59996a0461..96ff4947b5c 100644
--- a/src/main/java/org/apache/commons/io/filefilter/ConditionalFileFilter.java
+++ b/src/main/java/org/apache/commons/io/filefilter/ConditionalFileFilter.java
@@ -29,7 +29,7 @@ public interface ConditionalFileFilter {
* Adds the specified file filter to the list of file filters at the end of
* the list.
*
- * @param ioFileFilter the filter to be added
+ * @param ioFileFilter the filter to be added.
* @since 1.1
*/
void addFileFilter(IOFileFilter ioFileFilter);
@@ -37,7 +37,7 @@ public interface ConditionalFileFilter {
/**
* Gets this conditional file filter's list of file filters.
*
- * @return the file filter list
+ * @return the file filter list.
* @since 1.1
*/
List getFileFilters();
@@ -45,9 +45,9 @@ public interface ConditionalFileFilter {
/**
* Removes the specified file filter.
*
- * @param ioFileFilter filter to be removed
+ * @param ioFileFilter filter to be removed.
* @return {@code true} if the filter was found in the list,
- * {@code false} otherwise
+ * {@code false} otherwise.
* @since 1.1
*/
boolean removeFileFilter(IOFileFilter ioFileFilter);
@@ -56,7 +56,7 @@ public interface ConditionalFileFilter {
* Sets the list of file filters, replacing any previously configured
* file filters on this filter.
*
- * @param fileFilters the list of filters
+ * @param fileFilters the list of filters.
* @since 1.1
*/
void setFileFilters(List fileFilters);
diff --git a/src/main/java/org/apache/commons/io/filefilter/DelegateFileFilter.java b/src/main/java/org/apache/commons/io/filefilter/DelegateFileFilter.java
index 4137644ca1d..dd8674f3916 100644
--- a/src/main/java/org/apache/commons/io/filefilter/DelegateFileFilter.java
+++ b/src/main/java/org/apache/commons/io/filefilter/DelegateFileFilter.java
@@ -39,13 +39,14 @@ public class DelegateFileFilter extends AbstractFileFilter implements Serializab
/** The File filter */
private final transient FileFilter fileFilter;
+
/** The Filename filter */
private final transient FilenameFilter fileNameFilter;
/**
* Constructs a delegate file filter around an existing FileFilter.
*
- * @param fileFilter the filter to decorate
+ * @param fileFilter the filter to decorate.
*/
public DelegateFileFilter(final FileFilter fileFilter) {
Objects.requireNonNull(fileFilter, "filter");
@@ -56,7 +57,7 @@ public DelegateFileFilter(final FileFilter fileFilter) {
/**
* Constructs a delegate file filter around an existing FilenameFilter.
*
- * @param fileNameFilter the filter to decorate
+ * @param fileNameFilter the filter to decorate.
*/
public DelegateFileFilter(final FilenameFilter fileNameFilter) {
Objects.requireNonNull(fileNameFilter, "filter");
@@ -67,8 +68,8 @@ public DelegateFileFilter(final FilenameFilter fileNameFilter) {
/**
* Tests the filter.
*
- * @param file the file to check
- * @return true if the filter matches
+ * @param file the file to check.
+ * @return true if the filter matches.
*/
@Override
public boolean accept(final File file) {
@@ -81,9 +82,9 @@ public boolean accept(final File file) {
/**
* Tests the filter.
*
- * @param dir the directory
- * @param name the file name in the directory
- * @return true if the filter matches
+ * @param dir the directory.
+ * @param name the file name in the directory.
+ * @return true if the filter matches.
*/
@Override
public boolean accept(final File dir, final String name) {
@@ -96,7 +97,7 @@ public boolean accept(final File dir, final String name) {
/**
* Provide a String representation of this file filter.
*
- * @return a String representation
+ * @return a String representation.
*/
@Override
public String toString() {
diff --git a/src/main/java/org/apache/commons/io/filefilter/DirectoryFileFilter.java b/src/main/java/org/apache/commons/io/filefilter/DirectoryFileFilter.java
index bb3d615bd43..b0c54b42ec4 100644
--- a/src/main/java/org/apache/commons/io/filefilter/DirectoryFileFilter.java
+++ b/src/main/java/org/apache/commons/io/filefilter/DirectoryFileFilter.java
@@ -92,8 +92,8 @@ protected DirectoryFileFilter() {
/**
* Tests to see if the file is a directory.
*
- * @param file the File to check
- * @return true if the file is a directory
+ * @param file the File to check.
+ * @return true if the file is a directory.
*/
@Override
public boolean accept(final File file) {
@@ -103,9 +103,9 @@ public boolean accept(final File file) {
/**
* Tests to see if the file is a directory.
*
- * @param file the File to check
+ * @param file the File to check.
* @param attributes the path's basic attributes (may be null).
- * @return true if the file is a directory
+ * @return true if the file is a directory.
* @since 2.9.0
*/
@Override
diff --git a/src/main/java/org/apache/commons/io/filefilter/EmptyFileFilter.java b/src/main/java/org/apache/commons/io/filefilter/EmptyFileFilter.java
index a5cdd676bb1..392d2cf0f12 100644
--- a/src/main/java/org/apache/commons/io/filefilter/EmptyFileFilter.java
+++ b/src/main/java/org/apache/commons/io/filefilter/EmptyFileFilter.java
@@ -99,7 +99,7 @@ protected EmptyFileFilter() {
/**
* Tests to see if the file is empty.
*
- * @param file the file or directory to check
+ * @param file the file or directory to check.
* @return {@code true} if the file or directory is empty, otherwise {@code false}.
*/
@Override
@@ -117,7 +117,7 @@ public boolean accept(final File file) {
/**
* Tests to see if the file is empty.
*
- * @param file the file or directory to check
+ * @param file the file or directory to check.
* @param attributes the path's basic attributes (may be null).
* @return {@code true} if the file or directory is empty, otherwise {@code false}.
* @since 2.9.0
diff --git a/src/main/java/org/apache/commons/io/filefilter/FalseFileFilter.java b/src/main/java/org/apache/commons/io/filefilter/FalseFileFilter.java
index ebaa77b2007..7054a7c68f2 100644
--- a/src/main/java/org/apache/commons/io/filefilter/FalseFileFilter.java
+++ b/src/main/java/org/apache/commons/io/filefilter/FalseFileFilter.java
@@ -60,8 +60,8 @@ protected FalseFileFilter() {
/**
* Returns false.
*
- * @param file the file to check (ignored)
- * @return false
+ * @param file the file to check (ignored).
+ * @return false.
*/
@Override
public boolean accept(final File file) {
@@ -71,9 +71,9 @@ public boolean accept(final File file) {
/**
* Returns false.
*
- * @param dir the directory to check (ignored)
- * @param name the file name (ignored)
- * @return false
+ * @param dir the directory to check (ignored).
+ * @param name the file name (ignored).
+ * @return false.
*/
@Override
public boolean accept(final File dir, final String name) {
@@ -83,9 +83,9 @@ public boolean accept(final File dir, final String name) {
/**
* Returns false.
*
- * @param file the file to check (ignored)
+ * @param file the file to check (ignored).
* @param attributes the path's basic attributes (may be null).
- * @return false
+ * @return {@link FileVisitResult#TERMINATE}.
* @since 2.9.0
*/
@Override
diff --git a/src/main/java/org/apache/commons/io/filefilter/FileFileFilter.java b/src/main/java/org/apache/commons/io/filefilter/FileFileFilter.java
index 801d39f07b4..4bab6adf49e 100644
--- a/src/main/java/org/apache/commons/io/filefilter/FileFileFilter.java
+++ b/src/main/java/org/apache/commons/io/filefilter/FileFileFilter.java
@@ -92,8 +92,8 @@ protected FileFileFilter() {
/**
* Tests to see if the file is a file.
*
- * @param file the File to check
- * @return true if the file is a file
+ * @param file the File to check.
+ * @return true if the file is a file.
*/
@Override
public boolean accept(final File file) {
@@ -103,9 +103,9 @@ public boolean accept(final File file) {
/**
* Tests to see if the file is a file.
*
- * @param file the File to check
+ * @param file the File to check.
* @param attributes the path's basic attributes (may be null).
- * @return true if the file is a file
+ * @return true if the file is a file.
* @since 2.9.0
*/
@Override
diff --git a/src/main/java/org/apache/commons/io/filefilter/FileFilterUtils.java b/src/main/java/org/apache/commons/io/filefilter/FileFilterUtils.java
index 5e37676ac9c..74715ef6158 100644
--- a/src/main/java/org/apache/commons/io/filefilter/FileFilterUtils.java
+++ b/src/main/java/org/apache/commons/io/filefilter/FileFilterUtils.java
@@ -55,8 +55,8 @@ public class FileFilterUtils {
* Returns a filter that returns true if the file was last modified before
* or at the specified cutoff date.
*
- * @param cutoffDate the time threshold
- * @return an appropriately configured age file filter
+ * @param cutoffDate the time threshold.
+ * @return an appropriately configured age file filter.
* @see AgeFileFilter
* @since 1.2
*/
@@ -67,9 +67,9 @@ public static IOFileFilter ageFileFilter(final Date cutoffDate) {
/**
* Returns a filter that filters files based on a cutoff date.
*
- * @param cutoffDate the time threshold
- * @param acceptOlder if true, older files get accepted, if false, newer
- * @return an appropriately configured age file filter
+ * @param cutoffDate the time threshold.
+ * @param acceptOlder if true, older files get accepted, if false, newer.
+ * @return an appropriately configured age file filter.
* @see AgeFileFilter
* @since 1.2
*/
@@ -82,8 +82,8 @@ public static IOFileFilter ageFileFilter(final Date cutoffDate, final boolean ac
* or at the same time as the specified reference file.
*
* @param cutoffReference the file whose last modification
- * time is used as the threshold age of the files
- * @return an appropriately configured age file filter
+ * time is used as the threshold age of the files.
+ * @return an appropriately configured age file filter.
* @see AgeFileFilter
* @since 1.2
*/
@@ -95,9 +95,9 @@ public static IOFileFilter ageFileFilter(final File cutoffReference) {
* Returns a filter that filters files based on a cutoff reference file.
*
* @param cutoffReference the file whose last modification
- * time is used as the threshold age of the files
- * @param acceptOlder if true, older files get accepted, if false, newer
- * @return an appropriately configured age file filter
+ * time is used as the threshold age of the files.
+ * @param acceptOlder if true, older files get accepted, if false, newer.
+ * @return an appropriately configured age file filter.
* @see AgeFileFilter
* @since 1.2
*/
@@ -109,8 +109,8 @@ public static IOFileFilter ageFileFilter(final File cutoffReference, final boole
* Returns a filter that returns true if the file was last modified before
* or at the specified cutoff time.
*
- * @param cutoffMillis the time threshold
- * @return an appropriately configured age file filter
+ * @param cutoffMillis the time threshold.
+ * @return an appropriately configured age file filter.
* @see AgeFileFilter
* @since 1.2
*/
@@ -121,9 +121,9 @@ public static IOFileFilter ageFileFilter(final long cutoffMillis) {
/**
* Returns a filter that filters files based on a cutoff time.
*
- * @param cutoffMillis the time threshold
- * @param acceptOlder if true, older files get accepted, if false, newer
- * @return an appropriately configured age file filter
+ * @param cutoffMillis the time threshold.
+ * @param acceptOlder if true, older files get accepted, if false, newer.
+ * @return an appropriately configured age file filter.
* @see AgeFileFilter
* @since 1.2
*/
@@ -135,7 +135,7 @@ public static IOFileFilter ageFileFilter(final long cutoffMillis, final boolean
* Returns a filter that ANDs the specified filters.
*
* @param filters the IOFileFilters that will be ANDed together.
- * @return a filter that ANDs the specified filters
+ * @return a filter that ANDs the specified filters.
* @throws IllegalArgumentException if the filters are null or contain a
* null value.
* @see AndFileFilter
@@ -148,12 +148,12 @@ public static IOFileFilter and(final IOFileFilter... filters) {
/**
* Returns a filter that ANDs the two specified filters.
*
- * @param filter1 the first filter
- * @param filter2 the second filter
- * @return a filter that ANDs the two specified filters
+ * @param filter1 the first filter.
+ * @param filter2 the second filter.
+ * @return a filter that ANDs the two specified filters.
* @see #and(IOFileFilter...)
* @see AndFileFilter
- * @deprecated use {@link #and(IOFileFilter...)}
+ * @deprecated Use {@link #and(IOFileFilter...)}
*/
@Deprecated
public static IOFileFilter andFileFilter(final IOFileFilter filter1, final IOFileFilter filter2) {
@@ -164,8 +164,8 @@ public static IOFileFilter andFileFilter(final IOFileFilter filter1, final IOFil
* Returns an {@link IOFileFilter} that wraps the
* {@link FileFilter} instance.
*
- * @param filter the filter to be wrapped
- * @return a new filter that implements IOFileFilter
+ * @param filter the filter to be wrapped.
+ * @return a new filter that implements IOFileFilter.
* @see DelegateFileFilter
*/
public static IOFileFilter asFileFilter(final FileFilter filter) {
@@ -176,8 +176,8 @@ public static IOFileFilter asFileFilter(final FileFilter filter) {
* Returns an {@link IOFileFilter} that wraps the
* {@link FilenameFilter} instance.
*
- * @param filter the filter to be wrapped
- * @return a new filter that implements IOFileFilter
+ * @param filter the filter to be wrapped.
+ * @return a new filter that implements IOFileFilter.
* @see DelegateFileFilter
*/
public static IOFileFilter asFileFilter(final FilenameFilter filter) {
@@ -187,7 +187,7 @@ public static IOFileFilter asFileFilter(final FilenameFilter filter) {
/**
* Returns a filter that checks if the file is a directory.
*
- * @return file filter that accepts only directories and not files
+ * @return file filter that accepts only directories and not files.
* @see DirectoryFileFilter#DIRECTORY
*/
public static IOFileFilter directoryFileFilter() {
@@ -197,7 +197,7 @@ public static IOFileFilter directoryFileFilter() {
/**
* Returns a filter that always returns false.
*
- * @return a false filter
+ * @return a false filter.
* @see FalseFileFilter#FALSE
*/
public static IOFileFilter falseFileFilter() {
@@ -207,7 +207,7 @@ public static IOFileFilter falseFileFilter() {
/**
* Returns a filter that checks if the file is a file (and not a directory).
*
- * @return file filter that accepts only files and not directories
+ * @return file filter that accepts only files and not directories.
* @see FileFileFilter#INSTANCE
*/
public static IOFileFilter fileFileFilter() {
@@ -226,13 +226,13 @@ public static IOFileFilter fileFileFilter() {
* Set<File> javaFiles = FileFilterUtils.filterSet(allFiles,
* FileFilterUtils.suffixFileFilter(".java"));
*
+ *
* @param filter the filter to apply to the set of files.
* @param files the array of files to apply the filter to.
* @return a subset of {@code files} that is accepted by the
* file filter.
* @throws NullPointerException if the filter is {@code null}
* or {@code files} contains a {@code null} value.
- *
* @since 2.0
*/
public static File[] filter(final IOFileFilter filter, final File... files) {
@@ -259,13 +259,13 @@ public static File[] filter(final IOFileFilter filter, final File... files) {
* Set<File> javaFiles = FileFilterUtils.filterSet(allFiles,
* FileFilterUtils.suffixFileFilter(".java"));
*
+ *
* @param filter the filter to apply to the set of files.
* @param files the array of files to apply the filter to.
* @return a subset of {@code files} that is accepted by the
* file filter.
* @throws IllegalArgumentException if the filter is {@code null}
* or {@code files} contains a {@code null} value.
- *
* @since 2.0
*/
public static File[] filter(final IOFileFilter filter, final Iterable- * This method uses the virtual machine's {@link Charset#defaultCharset() default charset}. + * This method uses the virtual machine's {@linkplain Charset#defaultCharset() default charset}. *
* * @param magicNumber the magic number to look for in the file. @@ -270,6 +270,7 @@ public boolean accept(final File file) { * be rejected. * * + * * @param file the file to accept or reject. * @param attributes the path's basic attributes (may be null). * @return {@code true} if the file contains the filter's magic number diff --git a/src/main/java/org/apache/commons/io/filefilter/NameFileFilter.java b/src/main/java/org/apache/commons/io/filefilter/NameFileFilter.java index 7eda934d906..5aa3c38a21b 100644 --- a/src/main/java/org/apache/commons/io/filefilter/NameFileFilter.java +++ b/src/main/java/org/apache/commons/io/filefilter/NameFileFilter.java @@ -83,9 +83,9 @@ public class NameFileFilter extends AbstractFileFilter implements Serializable { /** * Constructs a new case-sensitive name file filter for a list of names. * - * @param names the names to allow, must not be null - * @throws IllegalArgumentException if the name list is null - * @throws ClassCastException if the list does not contain Strings + * @param names the names to allow, must not be null. + * @throws IllegalArgumentException if the name list is null. + * @throws ClassCastException if the list does not contain Strings. */ public NameFileFilter(final List* Implementations may not have anything to unwrap and that behavior is undefined for now. *
+ * * @return the underlying Iterable. */ Iterable* Implementations may not have anything to unwrap and that behavior is undefined for now. *
+ * * @return the underlying Iterator. */ Iterator+ * The cause of the returned InterruptedIOException is set to the original. + *
+ * + * @param e The InterruptedException to convert. + * @return The converted InterruptedIOException. + * @see InterruptedIOException + * @see Throwable#initCause(Throwable) + * @see Throwable#getCause() + */ + static InterruptedIOException toInterruptedIOException(final InterruptedException e) { + final InterruptedIOException iio = new InterruptedIOException(e.getMessage()); + iio.initCause(e); + return iio; + } } diff --git a/src/main/java/org/apache/commons/io/input/MarkShieldInputStream.java b/src/main/java/org/apache/commons/io/input/MarkShieldInputStream.java index 44fb12ff56e..0ed0b0bfda6 100644 --- a/src/main/java/org/apache/commons/io/input/MarkShieldInputStream.java +++ b/src/main/java/org/apache/commons/io/input/MarkShieldInputStream.java @@ -40,7 +40,7 @@ public class MarkShieldInputStream extends ProxyInputStream { * Constructs a proxy that shields the given input stream from being * marked or rest. * - * @param in underlying input stream + * @param in underlying input stream. */ public MarkShieldInputStream(final InputStream in) { super(in); diff --git a/src/main/java/org/apache/commons/io/input/MessageDigestCalculatingInputStream.java b/src/main/java/org/apache/commons/io/input/MessageDigestCalculatingInputStream.java index 5f2fb452ef0..7188c564502 100644 --- a/src/main/java/org/apache/commons/io/input/MessageDigestCalculatingInputStream.java +++ b/src/main/java/org/apache/commons/io/input/MessageDigestCalculatingInputStream.java @@ -148,7 +148,7 @@ public static class MessageDigestMaintainingObserver extends Observer { /** * Constructs an MessageDigestMaintainingObserver for the given MessageDigest. * - * @param messageDigest the message digest to use + * @param messageDigest the message digest to use. * @throws NullPointerException if messageDigest is null. */ public MessageDigestMaintainingObserver(final MessageDigest messageDigest) { @@ -211,7 +211,7 @@ private MessageDigestCalculatingInputStream(final Builder builder) throws IOExce * The MD5 algorithm is weak and should not be used. * * - * @param inputStream the stream to calculate the message digest for + * @param inputStream the stream to calculate the message digest for. * @throws NoSuchAlgorithmException if no Provider supports a MessageDigestSpi implementation for the specified algorithm. * @deprecated Use {@link #builder()}, {@link Builder}, and {@link Builder#get()}. */ @@ -226,8 +226,8 @@ public MessageDigestCalculatingInputStream(final InputStream inputStream) throws * The MD5 cryptographic algorithm is weak and should not be used. * * - * @param inputStream the stream to calculate the message digest for - * @param messageDigest the message digest to use + * @param inputStream the stream to calculate the message digest for. + * @param messageDigest the message digest to use. * @throws NullPointerException if messageDigest is null. * @deprecated Use {@link #builder()}, {@link Builder}, and {@link Builder#get()}. */ @@ -243,7 +243,7 @@ public MessageDigestCalculatingInputStream(final InputStream inputStream, final * The MD5 cryptographic algorithm is weak and should not be used. * * - * @param inputStream the stream to calculate the message digest for + * @param inputStream the stream to calculate the message digest for. * @param algorithm the name of the algorithm requested. See the MessageDigest section in the * Java Cryptography * Architecture Standard Algorithm Name Documentation for information about standard algorithm names. @@ -262,7 +262,7 @@ public MessageDigestCalculatingInputStream(final InputStream inputStream, final * data has been read, if that is what you want. The easiest way to do so is by invoking {@link #consume()}. * * - * @return the message digest used + * @return the message digest used. */ public MessageDigest getMessageDigest() { return messageDigest; diff --git a/src/main/java/org/apache/commons/io/input/MessageDigestInputStream.java b/src/main/java/org/apache/commons/io/input/MessageDigestInputStream.java index dac3f2afb5e..c8c3af88347 100644 --- a/src/main/java/org/apache/commons/io/input/MessageDigestInputStream.java +++ b/src/main/java/org/apache/commons/io/input/MessageDigestInputStream.java @@ -152,7 +152,7 @@ public static class MessageDigestMaintainingObserver extends Observer { /** * Constructs an MessageDigestMaintainingObserver for the given MessageDigest. * - * @param messageDigest the message digest to use + * @param messageDigest the message digest to use. * @throws NullPointerException if messageDigest is null. */ public MessageDigestMaintainingObserver(final MessageDigest messageDigest) { @@ -190,7 +190,7 @@ public static Builder builder() { * The MD5 cryptographic algorithm is weak and should not be used. * * - * @param builder A builder use to get the stream to calculate the message digest and the message digest to use + * @param builder A builder use to get the stream to calculate the message digest and the message digest to use. * @throws NullPointerException if messageDigest is null. */ private MessageDigestInputStream(final Builder builder) throws IOException { diff --git a/src/main/java/org/apache/commons/io/input/NullInputStream.java b/src/main/java/org/apache/commons/io/input/NullInputStream.java index 5fa9b817b5c..1f05410f636 100644 --- a/src/main/java/org/apache/commons/io/input/NullInputStream.java +++ b/src/main/java/org/apache/commons/io/input/NullInputStream.java @@ -272,7 +272,7 @@ public int read() throws IOException { /** * Reads some bytes into the specified array. * - * @param bytes The byte array to read into + * @param bytes The byte array to read into. * @return The number of bytes read or {@code -1} if the end of file has been reached and {@code throwEofException} is set to {@code false}. * @throws NullPointerException if the byte array is {@code null}. * @throws EOFException if the end of file is reached and {@code throwEofException} is set to {@code true}. diff --git a/src/main/java/org/apache/commons/io/input/NullReader.java b/src/main/java/org/apache/commons/io/input/NullReader.java index 28f3d37eb21..0405f3943d0 100644 --- a/src/main/java/org/apache/commons/io/input/NullReader.java +++ b/src/main/java/org/apache/commons/io/input/NullReader.java @@ -217,7 +217,7 @@ protected int processChar() { * This implementation leaves the character array unchanged. * * - * @param chars The character array + * @param chars The character array. * @param offset The offset to start at. * @param length The number of characters. */ @@ -250,7 +250,7 @@ public int read() throws IOException { /** * Reads some characters into the specified array. * - * @param chars The character array to read into + * @param chars The character array to read into. * @return The number of characters read or {@code -1} * if the end of file has been reached and * {@code throwEofException} is set to {@code false}. diff --git a/src/main/java/org/apache/commons/io/input/ObservableInputStream.java b/src/main/java/org/apache/commons/io/input/ObservableInputStream.java index a1287b857f7..1909f859a65 100644 --- a/src/main/java/org/apache/commons/io/input/ObservableInputStream.java +++ b/src/main/java/org/apache/commons/io/input/ObservableInputStream.java @@ -144,7 +144,7 @@ public void data(final int value) throws IOException { /** * Called to indicate that an error occurred on the underlying stream. * - * @param exception the exception to throw + * @param exception the exception to throw. * @throws IOException if an I/O error occurs. */ public void error(final IOException exception) throws IOException { @@ -361,7 +361,7 @@ public int read(final byte[] buffer, final int offset, final int length) throws /** * Removes an Observer. * - * @param observer the observer to remove + * @param observer the observer to remove. */ public void remove(final Observer observer) { observers.remove(observer); diff --git a/src/main/java/org/apache/commons/io/input/ProxyInputStream.java b/src/main/java/org/apache/commons/io/input/ProxyInputStream.java index b2e04c334b5..7530e3399c2 100644 --- a/src/main/java/org/apache/commons/io/input/ProxyInputStream.java +++ b/src/main/java/org/apache/commons/io/input/ProxyInputStream.java @@ -298,7 +298,7 @@ public int read() throws IOException { * @return the number of bytes read or {@link IOUtils#EOF EOF} if we reached the end of stream. * @throws IOException ** This method provides a point to implement custom exception * handling. The default behavior is to re-throw the exception. - * @param e The IOException thrown + *
+ * + * @param e The IOException thrown. * @throws IOException if an I/O error occurs. * @since 2.0 */ @@ -120,7 +123,8 @@ protected void handleIOException(final IOException e) throws IOException { /** * Invokes the delegate's {@code mark(int)} method. - * @param readAheadLimit read ahead limit + * + * @param readAheadLimit read ahead limit. * @throws IOException if an I/O error occurs. */ @Override @@ -134,7 +138,8 @@ public synchronized void mark(final int readAheadLimit) throws IOException { /** * Invokes the delegate's {@code markSupported()} method. - * @return true if mark is supported, otherwise false + * + * @return true if mark is supported, otherwise false. */ @Override public boolean markSupported() { @@ -143,7 +148,8 @@ public boolean markSupported() { /** * Invokes the delegate's {@code read()} method. - * @return the character read or -1 if the end of stream + * + * @return the character read or -1 if the end of stream. * @throws IOException if an I/O error occurs. */ @Override @@ -161,8 +167,9 @@ public int read() throws IOException { /** * Invokes the delegate's {@code read(char[])} method. - * @param chr the buffer to read the characters into - * @return the number of characters read or -1 if the end of stream + * + * @param chr the buffer to read the characters into. + * @return the number of characters read or -1 if the end of stream. * @throws IOException if an I/O error occurs. */ @Override @@ -180,10 +187,11 @@ public int read(final char[] chr) throws IOException { /** * Invokes the delegate's {@code read(char[], int, int)} method. - * @param chr the buffer to read the characters into - * @param st The start offset - * @param len The number of bytes to read - * @return the number of characters read or -1 if the end of stream + * + * @param chr the buffer to read the characters into. + * @param st The start offset. + * @param len The number of bytes to read. + * @return the number of characters read or -1 if the end of stream. * @throws IOException if an I/O error occurs. */ @Override @@ -201,8 +209,9 @@ public int read(final char[] chr, final int st, final int len) throws IOExceptio /** * Invokes the delegate's {@code read(CharBuffer)} method. - * @param target the char buffer to read the characters into - * @return the number of characters read or -1 if the end of stream + * + * @param target the char buffer to read the characters into. + * @return the number of characters read or -1 if the end of stream. * @throws IOException if an I/O error occurs. * @since 2.0 */ @@ -221,7 +230,8 @@ public int read(final CharBuffer target) throws IOException { /** * Invokes the delegate's {@code ready()} method. - * @return true if the stream is ready to be read + * + * @return true if the stream is ready to be read. * @throws IOException if an I/O error occurs. */ @Override @@ -236,6 +246,7 @@ public boolean ready() throws IOException { /** * Invokes the delegate's {@code reset()} method. + * * @throws IOException if an I/O error occurs. */ @Override @@ -249,8 +260,9 @@ public synchronized void reset() throws IOException { /** * Invokes the delegate's {@code skip(long)} method. - * @param ln the number of bytes to skip - * @return the number of bytes to skipped or EOF if the end of stream + * + * @param ln the number of bytes to skip. + * @return the number of bytes to skipped or EOF if the end of stream. * @throws IOException if an I/O error occurs. */ @Override diff --git a/src/main/java/org/apache/commons/io/input/QueueInputStream.java b/src/main/java/org/apache/commons/io/input/QueueInputStream.java index 5f701945cb3..d672d23fa2b 100644 --- a/src/main/java/org/apache/commons/io/input/QueueInputStream.java +++ b/src/main/java/org/apache/commons/io/input/QueueInputStream.java @@ -229,7 +229,7 @@ public int read() { /** * Reads up to {@code length} bytes of data from the input stream into - * an array of bytes. The first byte is read while honoring the timeout; the rest are read while not honoring + * an array of bytes. The first byte is read while honoring the timeout; the rest are read while not honoring * the timeout. The number of bytes actually read is returned as an integer. * * @param b the buffer into which the data is read. diff --git a/src/main/java/org/apache/commons/io/input/ReadAheadInputStream.java b/src/main/java/org/apache/commons/io/input/ReadAheadInputStream.java index bcee009a431..152cd42a586 100644 --- a/src/main/java/org/apache/commons/io/input/ReadAheadInputStream.java +++ b/src/main/java/org/apache/commons/io/input/ReadAheadInputStream.java @@ -20,7 +20,6 @@ import java.io.FilterInputStream; import java.io.IOException; import java.io.InputStream; -import java.io.InterruptedIOException; import java.nio.ByteBuffer; import java.util.Objects; import java.util.concurrent.ExecutorService; @@ -63,6 +62,9 @@ public class ReadAheadInputStream extends FilterInputStream { * .setExecutorService(Executors.newSingleThreadExecutor(ReadAheadInputStream::newThread)) * .get();} * + *+ * If an {@link ExecutorService} is not set, then a single-threaded daemon executor service is used. + *
* * @see #get() * @since 2.12.0 @@ -90,7 +92,7 @@ public Builder() { *+ * If not set, a single-threaded daemon executor service is used. + *
* - * @param executorService the executor service for the read-ahead thread. + * @param executorService the executor service for the read-ahead thread, may be {@code null}. * @return {@code this} instance. */ public Builder setExecutorService(final ExecutorService executorService) { @@ -203,7 +208,7 @@ private ReadAheadInputStream(final Builder builder) throws IOException { } /** - * Constructs an instance with the specified buffer size and read-ahead threshold + * Constructs an instance with the specified buffer size and read-ahead threshold. * * @param inputStream The underlying input stream. * @param bufferSizeInBytes The buffer size. @@ -215,7 +220,7 @@ public ReadAheadInputStream(final InputStream inputStream, final int bufferSizeI } /** - * Constructs an instance with the specified buffer size and read-ahead threshold + * Constructs an instance with the specified buffer size and read-ahead threshold. * * @param inputStream The underlying input stream. * @param bufferSizeInBytes The buffer size. @@ -228,7 +233,7 @@ public ReadAheadInputStream(final InputStream inputStream, final int bufferSizeI } /** - * Constructs an instance with the specified buffer size and read-ahead threshold + * Constructs an instance with the specified buffer size and read-ahead threshold. * * @param inputStream The underlying input stream. * @param bufferSizeInBytes The buffer size. @@ -239,7 +244,7 @@ private ReadAheadInputStream(final InputStream inputStream, final int bufferSize final boolean shutdownExecutorService) { super(Objects.requireNonNull(inputStream, "inputStream")); if (bufferSizeInBytes <= 0) { - throw new IllegalArgumentException("bufferSizeInBytes should be greater than 0, but the value is " + bufferSizeInBytes); + throw new IllegalArgumentException(String.format("bufferSizeInBytes <= 0, bufferSizeInBytes = %,d", bufferSizeInBytes)); } this.executorService = Objects.requireNonNull(executorService, "executorService"); this.shutdownExecutorService = shutdownExecutorService; @@ -287,21 +292,21 @@ public void close() throws IOException { } finally { stateChangeLock.unlock(); } - if (shutdownExecutorService) { try { - executorService.shutdownNow(); - executorService.awaitTermination(Long.MAX_VALUE, TimeUnit.SECONDS); + shutdownAwait(); } catch (final InterruptedException e) { - final InterruptedIOException iio = new InterruptedIOException(e.getMessage()); - iio.initCause(e); - throw iio; + Thread.currentThread().interrupt(); + throw Input.toInterruptedIOException(e); } finally { if (isSafeToCloseUnderlyingInputStream) { super.close(); } } } + if (isSafeToCloseUnderlyingInputStream) { + super.close(); + } } private void closeUnderlyingInputStreamIfNecessary() { @@ -346,7 +351,6 @@ public int read(final byte[] b, final int offset, int len) throws IOException { if (len == 0) { return 0; } - if (!activeBuffer.hasRemaining()) { // No remaining in active buffer - lock and switch to write ahead buffer. stateChangeLock.lock(); @@ -459,6 +463,11 @@ private void readAsync() throws IOException { }); } + boolean shutdownAwait() throws InterruptedException { + executorService.shutdownNow(); + return executorService.awaitTermination(Long.MAX_VALUE, TimeUnit.SECONDS); + } + private void signalAsyncReadComplete() { stateChangeLock.lock(); try { @@ -532,7 +541,7 @@ private long skipInternal(final long n) throws IOException { } /** - * Flips the active and read ahead buffer + * Flips the active and read ahead buffers. */ private void swapBuffers() { final ByteBuffer temp = activeBuffer; @@ -550,9 +559,8 @@ private void waitForAsyncReadComplete() throws IOException { asyncReadComplete.await(); } } catch (final InterruptedException e) { - final InterruptedIOException iio = new InterruptedIOException(e.getMessage()); - iio.initCause(e); - throw iio; + Thread.currentThread().interrupt(); + throw Input.toInterruptedIOException(e); } finally { try { isWaiting.set(false); 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 4d22d28f891..51cddcd2e98 100644 --- a/src/main/java/org/apache/commons/io/input/ReaderInputStream.java +++ b/src/main/java/org/apache/commons/io/input/ReaderInputStream.java @@ -209,6 +209,7 @@ private static CharsetEncoder newEncoder(final Charset charset) { * CharBuffer used as input for the decoder. It should be reasonably large as we read data from the underlying Reader into this buffer. */ private final CharBuffer encoderIn; + /** * ByteBuffer used as output for the decoder. This buffer can be small as it is only used to transfer data from the decoder to the buffer provided by the * caller. @@ -225,11 +226,11 @@ private ReaderInputStream(final Builder builder) throws IOException { } /** - * 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. + * Constructs a new {@link ReaderInputStream} that uses the virtual machine's {@linkplain 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 + * @deprecated Use {@link ReaderInputStream#builder()} instead. */ @Deprecated public ReaderInputStream(final Reader reader) { @@ -244,7 +245,7 @@ public ReaderInputStream(final Reader reader) { * * * @param reader the target {@link Reader} - * @param charset the charset encoding + * @param charset the charset encoding. * @deprecated Use {@link ReaderInputStream#builder()} instead, will be protected for subclasses. */ @Deprecated @@ -262,7 +263,7 @@ public ReaderInputStream(final Reader reader, final Charset charset) { * @param reader the target {@link Reader}. * @param charset the charset encoding. * @param bufferSize the size of the input buffer in number of characters. - * @deprecated Use {@link ReaderInputStream#builder()} instead + * @deprecated Use {@link ReaderInputStream#builder()} instead. */ @Deprecated public ReaderInputStream(final Reader reader, final Charset charset, final int bufferSize) { @@ -284,9 +285,9 @@ public ReaderInputStream(final Reader reader, final Charset charset, final int b * * * @param reader the target {@link Reader} - * @param charsetEncoder the charset encoder + * @param charsetEncoder the charset encoder. * @since 2.1 - * @deprecated Use {@link ReaderInputStream#builder()} instead + * @deprecated Use {@link ReaderInputStream#builder()} instead. */ @Deprecated public ReaderInputStream(final Reader reader, final CharsetEncoder charsetEncoder) { @@ -303,9 +304,9 @@ public ReaderInputStream(final Reader reader, final CharsetEncoder charsetEncode * * @param reader the target {@link Reader} * @param charsetEncoder the charset encoder, null defaults to the default Charset encoder. - * @param bufferSize the size of the input buffer in number of characters + * @param bufferSize the size of the input buffer in number of characters. * @since 2.1 - * @deprecated Use {@link ReaderInputStream#builder()} instead + * @deprecated Use {@link ReaderInputStream#builder()} instead. */ @Deprecated public ReaderInputStream(final Reader reader, final CharsetEncoder charsetEncoder, final int bufferSize) { @@ -325,8 +326,8 @@ public ReaderInputStream(final Reader reader, final CharsetEncoder charsetEncode * * * @param reader the target {@link Reader} - * @param charsetName the name of the charset encoding - * @deprecated Use {@link ReaderInputStream#builder()} instead + * @param charsetName the name of the charset encoding. + * @deprecated Use {@link ReaderInputStream#builder()} instead. */ @Deprecated public ReaderInputStream(final Reader reader, final String charsetName) { @@ -342,8 +343,8 @@ public ReaderInputStream(final Reader reader, final String charsetName) { * * @param reader the target {@link Reader} * @param charsetName the name of the charset encoding, null maps to the default Charset. - * @param bufferSize the size of the input buffer in number of characters - * @deprecated Use {@link ReaderInputStream#builder()} instead + * @param bufferSize the size of the input buffer in number of characters. + * @deprecated Use {@link ReaderInputStream#builder()} instead. */ @Deprecated public ReaderInputStream(final Reader reader, final String charsetName, final int bufferSize) { @@ -372,7 +373,7 @@ public void close() throws IOException { /** * Fills the internal char buffer from the reader. * - * @throws IOException If an I/O error occurs + * @throws IOException If an I/O error occurs. */ private void fillBuffer() throws IOException { if (endOfInput) { @@ -415,7 +416,7 @@ CharsetEncoder getCharsetEncoder() { /** * Reads a single byte. * - * @return either the byte read or {@code -1} if the end of the stream has been reached + * @return either the byte read or {@code -1} if the end of the stream has been reached. * @throws IOException if an I/O error occurs. */ @Override @@ -436,7 +437,7 @@ public int read() throws IOException { * Reads the specified number of bytes into an array. * * @param b the byte array to read into, must not be {@code null} - * @return the number of bytes read or {@code -1} if the end of the stream has been reached + * @return the number of bytes read or {@code -1} if the end of the stream has been reached. * @throws NullPointerException if the byte array is {@code null}. * @throws IOException if an I/O error occurs. */ @@ -448,10 +449,10 @@ public int read(final byte[] b) throws IOException { /** * Reads the specified number of bytes into an array. * - * @param array the byte array to read into - * @param off the offset to start reading bytes into - * @param len the number of bytes to read - * @return the number of bytes read or {@code -1} if the end of the stream has been reached + * @param array the byte array to read into. + * @param off the offset to start reading bytes into. + * @param len the number of bytes to read. + * @return the number of bytes read or {@code -1} if the end of the stream has been reached. * @throws NullPointerException if the byte array is {@code null}. * @throws IndexOutOfBoundsException if {@code off} or {@code len} are negative, or if {@code off + len} is greater than {@code array.length}. * @throws IOException if an I/O error occurs. 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 949ff8cbd8e..da5688b5155 100644 --- a/src/main/java/org/apache/commons/io/input/ReversedLinesFileReader.java +++ b/src/main/java/org/apache/commons/io/input/ReversedLinesFileReader.java @@ -25,7 +25,6 @@ import java.nio.charset.Charset; import java.nio.charset.CharsetEncoder; import java.nio.charset.StandardCharsets; -import java.nio.file.Files; import java.nio.file.Path; import java.nio.file.StandardOpenOption; import java.util.ArrayList; @@ -93,6 +92,7 @@ public static class Builder extends AbstractStreamBuilder+ * Package private for testing. + *
+ * + * @return The maximum bytes per second. + */ double getMaxBytesPerSecond() { return maxBytesPerSecond; } - private long getSleepMillis() { + /** + * Gets the number of milliseconds to sleep to match to the maximum bytes per second. + *+ * Package private for testing. + *
+ * + * @return the number of milliseconds to sleep to match to the maximum bytes per second. + */ + long getSleepMillis() { return toSleepMillis(getByteCount(), System.currentTimeMillis() - startTime, maxBytesPerSecond); } /** * Gets the total duration spent in sleep. + *+ * Package private for testing + *
* * @return Duration spent in sleep. */ - // package private for testing Duration getTotalSleepDuration() { return totalSleepDuration; } @@ -271,7 +288,8 @@ private void throttle() throws InterruptedIOException { try { TimeUnit.MILLISECONDS.sleep(sleepMillis); } catch (final InterruptedException e) { - throw new InterruptedIOException("Thread aborted"); + Thread.currentThread().interrupt(); + throw Input.toInterruptedIOException(e); } } } diff --git a/src/main/java/org/apache/commons/io/input/UncheckedFilterInputStream.java b/src/main/java/org/apache/commons/io/input/UncheckedFilterInputStream.java index ac6e003ab1f..eb6cf216251 100644 --- a/src/main/java/org/apache/commons/io/input/UncheckedFilterInputStream.java +++ b/src/main/java/org/apache/commons/io/input/UncheckedFilterInputStream.java @@ -110,7 +110,7 @@ public static Builder builder() { * Constructs a {@link UncheckedFilterInputStream}. * * @param builder A builder providing the underlying input stream. - * @throws IOException + * @throws IOException if an I/O error occurs. */ @SuppressWarnings("resource") // caller closes private UncheckedFilterInputStream(final Builder builder) throws IOException { diff --git a/src/main/java/org/apache/commons/io/input/UnixLineEndingInputStream.java b/src/main/java/org/apache/commons/io/input/UnixLineEndingInputStream.java index 3d0400fca71..be80d0d4eb1 100644 --- a/src/main/java/org/apache/commons/io/input/UnixLineEndingInputStream.java +++ b/src/main/java/org/apache/commons/io/input/UnixLineEndingInputStream.java @@ -43,8 +43,8 @@ public class UnixLineEndingInputStream extends InputStream { /** * Constructs an input stream that filters another stream * - * @param inputStream The input stream to wrap - * @param ensureLineFeedAtEndOfFile true to ensure that the file ends with LF + * @param inputStream The input stream to wrap. + * @param ensureLineFeedAtEndOfFile true to ensure that the file ends with LF. */ public UnixLineEndingInputStream(final InputStream inputStream, final boolean ensureLineFeedAtEndOfFile) { this.in = inputStream; @@ -53,6 +53,7 @@ public UnixLineEndingInputStream(final InputStream inputStream, final boolean en /** * Closes the stream. Also closes the underlying stream. + * * @throws IOException If an I/O error occurs. */ @Override @@ -112,7 +113,8 @@ public synchronized int read() throws IOException { /** * Reads the next item from the target, updating internal flags in the process - * @return the next int read from the target stream + * + * @return the next int read from the target stream. * @throws IOException If an I/O error occurs. */ private int readWithUpdate() throws IOException { diff --git a/src/main/java/org/apache/commons/io/input/UnsupportedOperationExceptions.java b/src/main/java/org/apache/commons/io/input/UnsupportedOperationExceptions.java index 63874faabb7..fea13e7c4cc 100644 --- a/src/main/java/org/apache/commons/io/input/UnsupportedOperationExceptions.java +++ b/src/main/java/org/apache/commons/io/input/UnsupportedOperationExceptions.java @@ -31,7 +31,7 @@ final class UnsupportedOperationExceptions { /** * Constructs a new instance of UnsupportedOperationException for a {@code mark} method. * - * @return a new instance of UnsupportedOperationException + * @return a new instance of UnsupportedOperationException. */ static UnsupportedOperationException mark() { // Use the same message as in java.io.InputStream.reset() in OpenJDK 8.0.275-1. @@ -41,8 +41,8 @@ static UnsupportedOperationException mark() { /** * Constructs a new instance of UnsupportedOperationException for the given unsupported a {@code method} name. * - * @param method A method name - * @return a new instance of UnsupportedOperationException + * @param method A method name. + * @return a new instance of UnsupportedOperationException. */ static UnsupportedOperationException method(final String method) { return new UnsupportedOperationException(method + " not supported"); @@ -51,7 +51,7 @@ static UnsupportedOperationException method(final String method) { /** * Constructs a new instance of UnsupportedOperationException for a {@code reset} method. * - * @return a new instance of UnsupportedOperationException + * @return a new instance of UnsupportedOperationException. */ static UnsupportedOperationException reset() { // Use the same message as in java.io.InputStream.reset() in OpenJDK 8.0.275-1. diff --git a/src/main/java/org/apache/commons/io/input/UnsynchronizedBufferedReader.java b/src/main/java/org/apache/commons/io/input/UnsynchronizedBufferedReader.java index bde55873f24..b5484116c32 100644 --- a/src/main/java/org/apache/commons/io/input/UnsynchronizedBufferedReader.java +++ b/src/main/java/org/apache/commons/io/input/UnsynchronizedBufferedReader.java @@ -212,8 +212,8 @@ public boolean markSupported() { /** * Returns the next character in the current reader without consuming it. So the next call to {@link #read()} will still return this value. * - * @return the next character - * @throws IOException If an I/O error occurs + * @return the next character. + * @throws IOException If an I/O error occurs. */ public int peek() throws IOException { mark(1); @@ -227,8 +227,8 @@ public int peek() throws IOException { * still return the next value. * * @param buf the buffer to fill for the look ahead. - * @return the buffer itself - * @throws IOException If an I/O error occurs + * @return the buffer itself. + * @throws IOException If an I/O error occurs. */ public int peek(final char[] buf) throws IOException { final int n = buf.length; diff --git a/src/main/java/org/apache/commons/io/input/UnsynchronizedByteArrayInputStream.java b/src/main/java/org/apache/commons/io/input/UnsynchronizedByteArrayInputStream.java index a56dec7206c..95f0805e21b 100644 --- a/src/main/java/org/apache/commons/io/input/UnsynchronizedByteArrayInputStream.java +++ b/src/main/java/org/apache/commons/io/input/UnsynchronizedByteArrayInputStream.java @@ -213,7 +213,7 @@ private UnsynchronizedByteArrayInputStream(final Builder builder) throws IOExcep /** * Constructs a new byte array input stream. * - * @param data the buffer + * @param data the buffer. * @deprecated Use {@link #builder()}, {@link Builder}, and {@link Builder#get()}. */ @Deprecated @@ -224,9 +224,9 @@ public UnsynchronizedByteArrayInputStream(final byte[] data) { /** * Constructs a new byte array input stream. * - * @param data the buffer - * @param offset the offset into the buffer - * @throws IllegalArgumentException if the offset is less than zero + * @param data the buffer. + * @param offset the offset into the buffer. + * @throws IllegalArgumentException if the offset is less than zero. * @deprecated Use {@link #builder()}, {@link Builder}, and {@link Builder#get()}. */ @Deprecated @@ -237,10 +237,10 @@ public UnsynchronizedByteArrayInputStream(final byte[] data, final int offset) { /** * Constructs a new byte array input stream. * - * @param data the buffer - * @param offset the offset into the buffer - * @param length the length of the buffer - * @throws IllegalArgumentException if the offset or length less than zero + * @param data the buffer. + * @param offset the offset into the buffer. + * @param length the length of the buffer. + * @throws IllegalArgumentException if the offset or length less than zero. * @deprecated Use {@link #builder()}, {@link Builder}, and {@link Builder#get()}. */ @Deprecated diff --git a/src/main/java/org/apache/commons/io/input/XmlStreamReader.java b/src/main/java/org/apache/commons/io/input/XmlStreamReader.java index 7f5102e8218..3d8a667c815 100644 --- a/src/main/java/org/apache/commons/io/input/XmlStreamReader.java +++ b/src/main/java/org/apache/commons/io/input/XmlStreamReader.java @@ -42,7 +42,6 @@ import org.apache.commons.io.IOUtils; import org.apache.commons.io.build.AbstractStreamBuilder; import org.apache.commons.io.function.IOConsumer; -import org.apache.commons.io.output.XmlStreamWriter; /** * Character stream that handles all the necessary Voodoo to figure out the charset encoding of the XML document within the stream. @@ -76,7 +75,7 @@ public class XmlStreamReader extends Reader { // @formatter:off /** - * Builds a new {@link XmlStreamWriter}. + * Builds a new {@link XmlStreamReader}. * * Constructs a Reader using an InputStream and the associated content-type header. This constructor is lenient regarding the encoding detection. *@@ -131,7 +130,7 @@ public Builder() { } /** - * Builds a new {@link XmlStreamWriter}. + * Builds a new {@link XmlStreamReader}. *
* You must set an aspect that supports {@link #getInputStream()}, otherwise, this method throws an exception. *
@@ -278,8 +277,8 @@ public static Builder builder() { /** * Gets the charset parameter value, {@code null} if not present, {@code null} if httpContentType is {@code null}. * - * @param httpContentType the HTTP content type - * @return The content type encoding (upcased) + * @param httpContentType the HTTP content type. + * @return The content type encoding (upcased). */ static String getContentTypeEncoding(final String httpContentType) { String encoding = null; @@ -298,8 +297,8 @@ static String getContentTypeEncoding(final String httpContentType) { /** * Gets the MIME type or {@code null} if httpContentType is {@code null}. * - * @param httpContentType the HTTP content type - * @return The mime content type + * @param httpContentType the HTTP content type. + * @return The mime content type. */ static String getContentTypeMime(final String httpContentType) { String mime = null; @@ -315,8 +314,8 @@ static String getContentTypeMime(final String httpContentType) { * Gets the encoding declared in the , {@code null} if none. * * @param inputStream InputStream to create the reader from. - * @param guessedEnc guessed encoding - * @return the encoding declared in the + * @param guessedEnc guessed encoding. + * @return the encoding declared in the . * @throws IOException thrown if there is a problem reading the stream. */ private static String getXmlProlog(final InputStream inputStream, final String guessedEnc) throws IOException { @@ -361,8 +360,8 @@ private static String getXmlProlog(final InputStream inputStream, final String g /** * Tests if the MIME type belongs to the APPLICATION XML family. * - * @param mime The mime type - * @return true if the mime type belongs to the APPLICATION XML family, otherwise false + * @param mime The mime type. + * @return true if the mime type belongs to the APPLICATION XML family, otherwise false. */ static boolean isAppXml(final String mime) { return mime != null && (mime.equals("application/xml") || mime.equals("application/xml-dtd") || mime.equals("application/xml-external-parsed-entity") @@ -372,8 +371,8 @@ static boolean isAppXml(final String mime) { /** * Tests if the MIME type belongs to the TEXT XML family. * - * @param mime The mime type - * @return true if the mime type belongs to the TEXT XML family, otherwise false + * @param mime The mime type. + * @return true if the mime type belongs to the TEXT XML family, otherwise false. */ static boolean isTextXml(final String mime) { return mime != null && (mime.equals("text/xml") || mime.equals("text/xml-external-parsed-entity") || mime.startsWith("text/") && mime.endsWith("+xml")); @@ -485,7 +484,7 @@ public XmlStreamReader(final InputStream inputStream, final boolean lenient) thr * * @param inputStream InputStream to create a Reader from. * @param lenient indicates if the charset encoding detection should be relaxed. - * @param defaultEncoding The default encoding + * @param defaultEncoding The default encoding. * @throws NullPointerException if the input stream is {@code null}. * @throws IOException thrown if there is a problem reading the stream. * @throws XmlStreamReaderException thrown if the charset encoding could not be determined according to the specification. @@ -589,7 +588,7 @@ public XmlStreamReader(final InputStream inputStream, final String httpContentTy * @param inputStream InputStream to create the reader from. * @param httpContentType content-type header to use for the resolution of the charset encoding. * @param lenient indicates if the charset encoding detection should be relaxed. - * @param defaultEncoding The default encoding + * @param defaultEncoding The default encoding. * @throws NullPointerException if the input stream is {@code null}. * @throws IOException thrown if there is a problem reading the file. * @throws XmlStreamReaderException thrown if the charset encoding could not be determined according to the specification. @@ -662,7 +661,7 @@ public XmlStreamReader(final URL url) throws IOException { * * * @param urlConnection URLConnection to create a Reader from. - * @param defaultEncoding The default encoding + * @param defaultEncoding The default encoding. * @throws NullPointerException if the input is {@code null}. * @throws IOException thrown if there is a problem reading the stream of the URLConnection. */ @@ -696,12 +695,13 @@ public XmlStreamReader(final URLConnection urlConnection, final String defaultEn /** * Calculates the HTTP encoding. - * @param bomEnc BOM encoding - * @param xmlGuessEnc XML Guess encoding - * @param xmlEnc XML encoding + * + * @param bomEnc BOM encoding. + * @param xmlGuessEnc XML Guess encoding. + * @param xmlEnc XML encoding. * @param lenient indicates if the charset encoding detection should be relaxed. - * @param httpContentType The HTTP content type - * @return the HTTP encoding + * @param httpContentType The HTTP content type. + * @return the HTTP encoding. * @throws IOException thrown if there is a problem reading the stream. */ String calculateHttpEncoding(final String bomEnc, final String xmlGuessEnc, final String xmlEnc, final boolean lenient, final String httpContentType) @@ -774,10 +774,10 @@ String calculateHttpEncoding(final String bomEnc, final String xmlGuessEnc, fina /** * Calculate the raw encoding. * - * @param bomEnc BOM encoding - * @param xmlGuessEnc XML Guess encoding - * @param xmlEnc XML encoding - * @return the raw encoding + * @param bomEnc BOM encoding. + * @param xmlGuessEnc XML Guess encoding. + * @param xmlEnc XML encoding. + * @return the raw encoding. * @throws IOException thrown if there is a problem reading the stream. */ String calculateRawEncoding(final String bomEnc, final String xmlGuessEnc, final String xmlEnc) throws IOException { @@ -795,11 +795,7 @@ String calculateRawEncoding(final String bomEnc, final String xmlGuessEnc, final // BOM is UTF-8 if (bomEnc.equals(UTF_8)) { - if (xmlGuessEnc != null && !xmlGuessEnc.equals(UTF_8)) { - final String msg = MessageFormat.format(RAW_EX_1, bomEnc, xmlGuessEnc, xmlEnc); - throw new XmlStreamReaderException(msg, bomEnc, xmlGuessEnc, xmlEnc); - } - if (xmlEnc != null && !xmlEnc.equals(UTF_8)) { + if (xmlGuessEnc != null && !xmlGuessEnc.equals(UTF_8) || xmlEnc != null && !xmlEnc.equals(UTF_8)) { final String msg = MessageFormat.format(RAW_EX_1, bomEnc, xmlGuessEnc, xmlEnc); throw new XmlStreamReaderException(msg, bomEnc, xmlGuessEnc, xmlEnc); } @@ -851,8 +847,8 @@ public void close() throws IOException { * Does lenient detection. * * @param httpContentType content-type header to use for the resolution of the charset encoding. - * @param ex The thrown exception - * @return the encoding + * @param ex The thrown exception. + * @return the encoding. * @throws IOException thrown if there is a problem reading the stream. */ private String doLenientDetection(String httpContentType, XmlStreamReaderException ex) throws IOException { @@ -899,10 +895,10 @@ public String getEncoding() { /** * Process the raw stream. * - * @param bomInput BOMInputStream to detect byte order marks - * @param piInput BOMInputStream to guess XML encoding + * @param bomInput BOMInputStream to detect byte order marks. + * @param piInput BOMInputStream to guess XML encoding. * @param lenient indicates if the charset encoding detection should be relaxed. - * @return the encoding to be used + * @return the encoding to be used. * @throws IOException thrown if there is a problem reading the stream. */ private String processHttpStream(final BOMInputStream bomInput, final BOMInputStream piInput, final boolean lenient) throws IOException { @@ -922,11 +918,11 @@ private String processHttpStream(final BOMInputStream bomInput, final BOMInputSt /** * Processes an HTTP stream. * - * @param bomInput BOMInputStream to detect byte order marks - * @param piInput BOMInputStream to guess XML encoding + * @param bomInput BOMInputStream to detect byte order marks. + * @param piInput BOMInputStream to guess XML encoding. * @param lenient indicates if the charset encoding detection should be relaxed. - * @param httpContentType The HTTP content type - * @return the encoding to be used + * @param httpContentType The HTTP content type. + * @return the encoding to be used. * @throws IOException thrown if there is a problem reading the stream. */ private String processHttpStream(final BOMInputStream bomInput, final BOMInputStream piInput, final boolean lenient, final String httpContentType) @@ -947,10 +943,10 @@ private String processHttpStream(final BOMInputStream bomInput, final BOMInputSt /** * Reads the underlying reader's {@code read(char[], int, int)} method. * - * @param buf the buffer to read the characters into - * @param offset The start offset - * @param len The number of bytes to read - * @return the number of characters read or -1 if the end of stream + * @param buf the buffer to read the characters into. + * @param offset The start offset. + * @param len The number of bytes to read. + * @return the number of characters read or -1 if the end of stream. * @throws IOException if an I/O error occurs. */ @Override diff --git a/src/main/java/org/apache/commons/io/input/buffer/CircularBufferInputStream.java b/src/main/java/org/apache/commons/io/input/buffer/CircularBufferInputStream.java index b92163478d0..cea865ae066 100644 --- a/src/main/java/org/apache/commons/io/input/buffer/CircularBufferInputStream.java +++ b/src/main/java/org/apache/commons/io/input/buffer/CircularBufferInputStream.java @@ -104,8 +104,8 @@ protected void fillBuffer() throws IOException { /** * Fills the buffer from the input stream until the given number of bytes have been added to the buffer. * - * @param count number of byte to fill into the buffer - * @return true if the buffer has bytes + * @param count number of byte to fill into the buffer. + * @return true if the buffer has bytes. * @throws IOException in case of an error while reading from the input stream. */ protected boolean haveBytes(final int count) throws IOException { diff --git a/src/main/java/org/apache/commons/io/input/buffer/CircularByteBuffer.java b/src/main/java/org/apache/commons/io/input/buffer/CircularByteBuffer.java index 43c8e71bd4a..64780b7c709 100644 --- a/src/main/java/org/apache/commons/io/input/buffer/CircularByteBuffer.java +++ b/src/main/java/org/apache/commons/io/input/buffer/CircularByteBuffer.java @@ -46,7 +46,7 @@ public CircularByteBuffer() { /** * Constructs a new instance with the given buffer size. * - * @param size the size of buffer to create + * @param size the size of buffer to create. */ public CircularByteBuffer(final int size) { buffer = IOUtils.byteArray(size); @@ -79,9 +79,9 @@ public void add(final byte value) { * for the bytes at offsets {@code offset+0}, {@code offset+1}, ..., * {@code offset+length-1} of byte array {@code targetBuffer}. * - * @param targetBuffer the buffer to copy - * @param offset start offset - * @param length length to copy + * @param targetBuffer the buffer to copy. + * @param offset start offset. + * @param length length to copy. * @throws IllegalStateException The buffer doesn't have sufficient space. Use * {@link #getSpace()} to prevent this exception. * @throws IllegalArgumentException Either of {@code offset}, or {@code length} is negative. @@ -119,7 +119,7 @@ public void clear() { /** * Gets the number of bytes, that are currently present in the buffer. * - * @return the number of bytes + * @return the number of bytes. */ public int getCurrentNumberOfBytes() { return currentNumberOfBytes; @@ -128,7 +128,7 @@ public int getCurrentNumberOfBytes() { /** * Gets the number of bytes, that can currently be added to the buffer. * - * @return the number of bytes that can be added + * @return the number of bytes that can be added. */ public int getSpace() { return buffer.length - currentNumberOfBytes; @@ -158,7 +158,7 @@ public boolean hasSpace() { /** * Tests whether there is currently room for the given number of bytes in the buffer. * - * @param count the byte count + * @param count the byte count. * @return true whether there is currently room for the given number of bytes in the buffer. * @see #hasSpace() * @see #getSpace() @@ -173,9 +173,9 @@ public boolean hasSpace(final int count) { * removed from the buffer. If the result is true, then the following invocations * of {@link #read()} are guaranteed to return exactly those bytes. * - * @param sourceBuffer the buffer to compare against - * @param offset start offset - * @param length length to compare + * @param sourceBuffer the buffer to compare against. + * @param offset start offset. + * @param length length to compare. * @return True, if the next invocations of {@link #read()} will return the * bytes at offsets {@code sourceBuffer}+0, {@code offset}+1, ..., * {@code offset}+{@code length}-1 of byte array {@code sourceBuffer}. diff --git a/src/main/java/org/apache/commons/io/input/buffer/PeekableInputStream.java b/src/main/java/org/apache/commons/io/input/buffer/PeekableInputStream.java index ec96054fc43..8bb0f7c7158 100644 --- a/src/main/java/org/apache/commons/io/input/buffer/PeekableInputStream.java +++ b/src/main/java/org/apache/commons/io/input/buffer/PeekableInputStream.java @@ -53,8 +53,8 @@ public PeekableInputStream(final InputStream inputStream, final int bufferSize) * Returns whether the next bytes in the buffer are as given by {@code sourceBuffer}. This is equivalent to * {@link #peek(byte[], int, int)} with {@code offset} == 0, and {@code length} == {@code sourceBuffer.length} * - * @param sourceBuffer the buffer to compare against - * @return true if the next bytes are as given + * @param sourceBuffer the buffer to compare against. + * @return true if the next bytes are as given. * @throws IOException Refilling the buffer failed. */ public boolean peek(final byte[] sourceBuffer) throws IOException { @@ -66,11 +66,11 @@ public boolean peek(final byte[] sourceBuffer) throws IOException { * Returns whether the next bytes in the buffer are as given by {@code sourceBuffer}, {code offset}, and * {@code length}. * - * @param sourceBuffer the buffer to compare against - * @param offset the start offset - * @param length the length to compare - * @return true if the next bytes in the buffer are as given - * @throws IOException if there is a problem calling fillBuffer() + * @param sourceBuffer the buffer to compare against. + * @param offset the start offset. + * @param length the length to compare. + * @return true if the next bytes in the buffer are as given. + * @throws IOException if there is a problem calling fillBuffer(). */ public boolean peek(final byte[] sourceBuffer, final int offset, final int length) throws IOException { Objects.requireNonNull(sourceBuffer, "sourceBuffer"); diff --git a/src/main/java/org/apache/commons/io/monitor/FileAlterationListener.java b/src/main/java/org/apache/commons/io/monitor/FileAlterationListener.java index ce64c8d4ed4..b7bf2a0cdb4 100644 --- a/src/main/java/org/apache/commons/io/monitor/FileAlterationListener.java +++ b/src/main/java/org/apache/commons/io/monitor/FileAlterationListener.java @@ -31,56 +31,56 @@ public interface FileAlterationListener { /** * Directory changed Event. * - * @param directory The directory changed + * @param directory The directory changed. */ void onDirectoryChange(File directory); /** * Directory created Event. * - * @param directory The directory created + * @param directory The directory created. */ void onDirectoryCreate(File directory); /** * Directory deleted Event. * - * @param directory The directory deleted + * @param directory The directory deleted. */ void onDirectoryDelete(File directory); /** * File changed Event. * - * @param file The file changed + * @param file The file changed. */ void onFileChange(File file); /** * File created Event. * - * @param file The file created + * @param file The file created. */ void onFileCreate(File file); /** * File deleted Event. * - * @param file The file deleted + * @param file The file deleted. */ void onFileDelete(File file); /** * File system observer started checking event. * - * @param observer The file system observer + * @param observer The file system observer. */ void onStart(FileAlterationObserver observer); /** * File system observer finished checking event. * - * @param observer The file system observer + * @param observer The file system observer. */ void onStop(FileAlterationObserver observer); } diff --git a/src/main/java/org/apache/commons/io/monitor/FileAlterationListenerAdaptor.java b/src/main/java/org/apache/commons/io/monitor/FileAlterationListenerAdaptor.java index 0b54bbd6723..c676470fa31 100644 --- a/src/main/java/org/apache/commons/io/monitor/FileAlterationListenerAdaptor.java +++ b/src/main/java/org/apache/commons/io/monitor/FileAlterationListenerAdaptor.java @@ -36,7 +36,7 @@ public FileAlterationListenerAdaptor() { /** * Directory changed Event. * - * @param directory The directory changed (ignored) + * @param directory The directory changed (ignored). */ @Override public void onDirectoryChange(final File directory) { @@ -46,7 +46,7 @@ public void onDirectoryChange(final File directory) { /** * Directory created Event. * - * @param directory The directory created (ignored) + * @param directory The directory created (ignored). */ @Override public void onDirectoryCreate(final File directory) { @@ -56,7 +56,7 @@ public void onDirectoryCreate(final File directory) { /** * Directory deleted Event. * - * @param directory The directory deleted (ignored) + * @param directory The directory deleted (ignored). */ @Override public void onDirectoryDelete(final File directory) { @@ -66,7 +66,7 @@ public void onDirectoryDelete(final File directory) { /** * File changed Event. * - * @param file The file changed (ignored) + * @param file The file changed (ignored). */ @Override public void onFileChange(final File file) { @@ -76,7 +76,7 @@ public void onFileChange(final File file) { /** * File created Event. * - * @param file The file created (ignored) + * @param file The file created (ignored). */ @Override public void onFileCreate(final File file) { @@ -86,7 +86,7 @@ public void onFileCreate(final File file) { /** * File deleted Event. * - * @param file The file deleted (ignored) + * @param file The file deleted (ignored). */ @Override public void onFileDelete(final File file) { @@ -96,7 +96,7 @@ public void onFileDelete(final File file) { /** * File system observer started checking event. * - * @param observer The file system observer (ignored) + * @param observer The file system observer (ignored). */ @Override public void onStart(final FileAlterationObserver observer) { @@ -106,7 +106,7 @@ public void onStart(final FileAlterationObserver observer) { /** * File system observer finished checking event. * - * @param observer The file system observer (ignored) + * @param observer The file system observer (ignored). */ @Override public void onStop(final FileAlterationObserver observer) { diff --git a/src/main/java/org/apache/commons/io/monitor/FileAlterationMonitor.java b/src/main/java/org/apache/commons/io/monitor/FileAlterationMonitor.java index 394e7aca661..ab3a65b9416 100644 --- a/src/main/java/org/apache/commons/io/monitor/FileAlterationMonitor.java +++ b/src/main/java/org/apache/commons/io/monitor/FileAlterationMonitor.java @@ -98,7 +98,7 @@ public FileAlterationMonitor(final long interval, final FileAlterationObserver.. /** * Adds a file system observer to this monitor. * - * @param observer The file system observer to add + * @param observer The file system observer to add. */ public void addObserver(final FileAlterationObserver observer) { if (observer != null) { @@ -109,7 +109,7 @@ public void addObserver(final FileAlterationObserver observer) { /** * Returns the interval. * - * @return the interval + * @return the interval. */ public long getInterval() { return intervalMillis; @@ -128,7 +128,7 @@ public Iterable