From 3465e73666fd39e0c7e50debc3c375a18bc96e53 Mon Sep 17 00:00:00 2001 From: Elliotte Rusty Harold Date: Fri, 6 Oct 2023 07:45:51 -0400 Subject: [PATCH 1/7] [IO-814] Don't throw UncheckedIOException --- .../org/apache/commons/io/file/PathUtils.java | 142 +++++++++--------- 1 file changed, 68 insertions(+), 74 deletions(-) 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 3cd85f086ed..6d462f93332 100644 --- a/src/main/java/org/apache/commons/io/file/PathUtils.java +++ b/src/main/java/org/apache/commons/io/file/PathUtils.java @@ -21,7 +21,6 @@ import java.io.IOException; import java.io.InputStream; import java.io.OutputStream; -import java.io.UncheckedIOException; import java.math.BigInteger; import java.net.URI; import java.net.URISyntaxException; @@ -77,7 +76,6 @@ import org.apache.commons.io.filefilter.IOFileFilter; import org.apache.commons.io.function.IOFunction; import org.apache.commons.io.function.IOSupplier; -import org.apache.commons.io.function.Uncheck; /** * NIO Path utilities. @@ -106,7 +104,7 @@ private static class RelativeSortedPaths { * @param maxDepth See {@link Files#walkFileTree(Path,Set,int,FileVisitor)}. * @param linkOptions Options indicating how symbolic links are handled. * @param fileVisitOptions See {@link Files#walkFileTree(Path,Set,int,FileVisitor)}. - * @throws IOException if an I/O error is thrown by a visitor method. + * @throws IOException if an I/O error is thrown by a visitor method */ private RelativeSortedPaths(final Path dir1, final Path dir2, final int maxDepth, final LinkOption[] linkOptions, final FileVisitOption[] fileVisitOptions) throws IOException { @@ -217,7 +215,7 @@ private RelativeSortedPaths(final Path dir1, final Path dir2, final int maxDepth * @param directory The directory to accumulate information. * @param maxDepth See {@link Files#walkFileTree(Path,Set,int,FileVisitor)}. * @param fileVisitOptions See {@link Files#walkFileTree(Path,Set,int,FileVisitor)}. - * @throws IOException if an I/O error is thrown by a visitor method. + * @throws IOException if an I/O error is thrown by a visitor method * @return file tree information. */ private static AccumulatorPathVisitor accumulate(final Path directory, final int maxDepth, final FileVisitOption[] fileVisitOptions) throws IOException { @@ -229,7 +227,7 @@ private static AccumulatorPathVisitor accumulate(final Path directory, final int * * @param directory directory to clean. * @return The visitation path counters. - * @throws IOException if an I/O error is thrown by a visitor method. + * @throws IOException if an I/O error is thrown by a visitor method */ public static PathCounters cleanDirectory(final Path directory) throws IOException { return cleanDirectory(directory, EMPTY_DELETE_OPTION_ARRAY); @@ -241,7 +239,7 @@ public static PathCounters cleanDirectory(final Path directory) throws IOExcepti * @param directory directory to clean. * @param deleteOptions How to handle deletion. * @return The visitation path counters. - * @throws IOException if an I/O error is thrown by a visitor method. + * @throws IOException if an I/O error is thrown by a visitor method * @since 2.8.0 */ public static PathCounters cleanDirectory(final Path directory, final DeleteOption... deleteOptions) throws IOException { @@ -253,7 +251,7 @@ public static PathCounters cleanDirectory(final Path directory, final DeleteOpti * * @param file the {@link Path} to test. * @param fileTime the time reference. - * @param options options indicating how to handle symbolic links. + * @param options options indicating how to handle symbolic links * @return See {@link FileTime#compareTo(FileTime)} * @throws IOException if an I/O error occurs. * @throws NullPointerException if the file is {@code null}. @@ -285,7 +283,7 @@ public static long copy(final IOSupplier in, final Path target, fin * @param targetDirectory The target directory. * @param copyOptions Specifies how the copying should be done. * @return The visitation path counters. - * @throws IOException if an I/O error is thrown by a visitor method. + * @throws IOException if an I/O error is thrown by a visitor method */ public static PathCounters copyDirectory(final Path sourceDirectory, final Path targetDirectory, final CopyOption... copyOptions) throws IOException { final Path absoluteSource = sourceDirectory.toAbsolutePath(); @@ -343,7 +341,7 @@ public static Path copyFileToDirectory(final URL sourceFile, final Path targetDi * * @param directory directory to delete. * @return The visitor used to count the given directory. - * @throws IOException if an I/O error is thrown by a visitor method. + * @throws IOException if an I/O error is thrown by a visitor method */ public static PathCounters countDirectory(final Path directory) throws IOException { return visitFileTree(CountingPathVisitor.withLongCounters(), directory).getPathCounters(); @@ -481,7 +479,7 @@ public static PathCounters delete(final Path path, final LinkOption[] linkOption * * @param directory directory to delete. * @return The visitor used to delete the given directory. - * @throws IOException if an I/O error is thrown by a visitor method. + * @throws IOException if an I/O error is thrown by a visitor method */ public static PathCounters deleteDirectory(final Path directory) throws IOException { return deleteDirectory(directory, EMPTY_DELETE_OPTION_ARRAY); @@ -493,7 +491,7 @@ public static PathCounters deleteDirectory(final Path directory) throws IOExcept * @param directory directory to delete. * @param deleteOptions How to handle deletion. * @return The visitor used to delete the given directory. - * @throws IOException if an I/O error is thrown by a visitor method. + * @throws IOException if an I/O error is thrown by a visitor method * @since 2.8.0 */ public static PathCounters deleteDirectory(final Path directory, final DeleteOption... deleteOptions) throws IOException { @@ -510,7 +508,7 @@ public static PathCounters deleteDirectory(final Path directory, final DeleteOpt * @param linkOptions How to handle symbolic links. * @param deleteOptions How to handle deletion. * @return The visitor used to delete the given directory. - * @throws IOException if an I/O error is thrown by a visitor method. + * @throws IOException if an I/O error is thrown by a visitor method * @since 2.9.0 */ public static PathCounters deleteDirectory(final Path directory, final LinkOption[] linkOptions, final DeleteOption... deleteOptions) throws IOException { @@ -614,7 +612,7 @@ public static void deleteOnExit(final Path path) { * @param path1 The first directory. * @param path2 The second directory. * @return Whether the two directories contain the same files while considering file contents. - * @throws IOException if an I/O error is thrown by a visitor method. + * @throws IOException if an I/O error is thrown by a visitor method */ public static boolean directoryAndFileContentEquals(final Path path1, final Path path2) throws IOException { return directoryAndFileContentEquals(path1, path2, EMPTY_LINK_OPTION_ARRAY, EMPTY_OPEN_OPTION_ARRAY, EMPTY_FILE_VISIT_OPTION_ARRAY); @@ -630,7 +628,7 @@ public static boolean directoryAndFileContentEquals(final Path path1, final Path * @param openOptions options to open files. * @param fileVisitOption options to configure traversal. * @return Whether the two directories contain the same files while considering file contents. - * @throws IOException if an I/O error is thrown by a visitor method. + * @throws IOException if an I/O error is thrown by a visitor method */ public static boolean directoryAndFileContentEquals(final Path path1, final Path path2, final LinkOption[] linkOptions, final OpenOption[] openOptions, final FileVisitOption[] fileVisitOption) throws IOException { @@ -671,7 +669,7 @@ public static boolean directoryAndFileContentEquals(final Path path1, final Path * @param path1 The first directory. * @param path2 The second directory. * @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. + * @throws IOException if an I/O error is thrown by a visitor method */ public static boolean directoryContentEquals(final Path path1, final Path path2) throws IOException { return directoryContentEquals(path1, path2, Integer.MAX_VALUE, EMPTY_LINK_OPTION_ARRAY, EMPTY_FILE_VISIT_OPTION_ARRAY); @@ -687,7 +685,7 @@ public static boolean directoryContentEquals(final Path path1, final Path path2) * @param linkOptions options to follow links. * @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. + * @throws IOException if an I/O error is thrown by a visitor method */ public static boolean directoryContentEquals(final Path path1, final Path path2, final int maxDepth, final LinkOption[] linkOptions, final FileVisitOption[] fileVisitOptions) throws IOException { @@ -1019,7 +1017,7 @@ public static boolean isEmptyFile(final Path file) throws IOException { * * @param file the {@link Path} to test. * @param czdt the time reference. - * @param options options indicating how to handle symbolic links. + * @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. * @throws NullPointerException if the file is {@code null}. @@ -1035,7 +1033,7 @@ public static boolean isNewer(final Path file, final ChronoZonedDateTime czdt * * @param file the {@link Path} to test. * @param fileTime the time reference. - * @param options options indicating how to handle symbolic links. + * @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. * @throws NullPointerException if the file is {@code null}. @@ -1053,7 +1051,7 @@ public static boolean isNewer(final Path file, final FileTime fileTime, final Li * * @param file the {@link Path} to test. * @param instant the time reference. - * @param options options indicating how to handle symbolic links. + * @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. * @throws NullPointerException if the file is {@code null}. @@ -1068,7 +1066,7 @@ public static boolean isNewer(final Path file, final Instant instant, final Link * * @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 options options indicating how to handle symbolic links. + * @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. * @throws NullPointerException if the file is {@code null}. @@ -1096,7 +1094,7 @@ public static boolean isNewer(final Path file, final Path reference) throws IOEx * * @param file the {@link Path} to test. * @param fileTime the time reference. - * @param options options indicating how to handle symbolic links. + * @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. * @throws NullPointerException if the file is {@code null}. @@ -1114,7 +1112,7 @@ public static boolean isOlder(final Path file, final FileTime fileTime, final Li * * @param file the {@link Path} to test. * @param instant the time reference. - * @param options options indicating how to handle symbolic links. + * @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. * @throws NullPointerException if the file is {@code null}. @@ -1129,7 +1127,7 @@ public static boolean isOlder(final Path file, final Instant instant, final Link * * @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 options options indicating how to handle symbolic links. + * @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. * @throws NullPointerException if the file is {@code null}. @@ -1156,7 +1154,7 @@ public static boolean isOlder(final Path file, final Path reference) throws IOEx * Tests whether the given path is on a POSIX file system. * * @param test The Path to test. - * @param options options indicating how to handle symbolic links. + * @param options options indicating how to handle symbolic links * @return true if test is on a POSIX file system. * @since 2.12.0 */ @@ -1169,7 +1167,7 @@ public static boolean isPosix(final Path test, final LinkOption... options) { * {@code Files.isRegularFile(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 regular file; {@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 regular file or not. * @throws SecurityException In the case of the default provider, and a security manager is installed, the @@ -1247,21 +1245,20 @@ private static boolean overrideReadOnly(final DeleteOption... deleteOptions) { } /** - * Reads the BasicFileAttributes from the given path. Returns null instead of throwing - * {@link UnsupportedOperationException}. Throws {@link Uncheck} instead of {@link IOException}. + * Reads the BasicFileAttributes from the given path. Returns null if the attributes can't be read. * - * @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. - * @return the file attributes. + * @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 + * @return the file attributes or null if the attributes can't be read * @see Files#readAttributes(Path, Class, LinkOption...) * @since 2.12.0 */ public static A readAttributes(final Path path, final Class type, final LinkOption... options) { try { - return path == null ? null : Uncheck.apply(Files::readAttributes, path, type, options); - } catch (final UnsupportedOperationException e) { + return path == null ? null : Files.readAttributes(path, type, options); + } catch (final UnsupportedOperationException | IOException e) { // For example, on Windows. return null; } @@ -1270,24 +1267,22 @@ public static A readAttributes(final Path path, /** * Reads the BasicFileAttributes from the given path. * - * @param path the path to read. - * @return the path attributes. - * @throws IOException if an I/O error occurs. + * @param path the path to read + * @return the path attributes + * @throws IOException if an I/O error occurs * @since 2.9.0 - * @deprecated Will be removed in 3.0.0 in favor of {@link #readBasicFileAttributes(Path, LinkOption...)}. */ - @Deprecated public static BasicFileAttributes readBasicFileAttributes(final Path path) throws IOException { return Files.readAttributes(path, BasicFileAttributes.class); } /** - * Reads the BasicFileAttributes from the given path. Returns null instead of throwing - * {@link UnsupportedOperationException}. + * Reads the BasicFileAttributes from the given path. Returns null if the attributes + * can't be read. * - * @param path the path to read. - * @param options options indicating how to handle symbolic links. - * @return the path attributes. + * @param path the path to read + * @param options options indicating how to handle symbolic links + * @return the path attributes * @since 2.12.0 */ public static BasicFileAttributes readBasicFileAttributes(final Path path, final LinkOption... options) { @@ -1295,12 +1290,11 @@ public static BasicFileAttributes readBasicFileAttributes(final Path path, final } /** - * Reads the BasicFileAttributes from the given path. Returns null instead of throwing - * {@link UnsupportedOperationException}. + * Reads the BasicFileAttributes from the given path. Returns null if the attributes + * can't be read. * - * @param path the path to read. + * @param path the Path to read * @return the path attributes. - * @throws UncheckedIOException if an I/O error occurs * @since 2.9.0 * @deprecated Use {@link #readBasicFileAttributes(Path, LinkOption...)}. */ @@ -1310,12 +1304,12 @@ public static BasicFileAttributes readBasicFileAttributesUnchecked(final Path pa } /** - * Reads the DosFileAttributes from the given path. Returns null instead of throwing - * {@link UnsupportedOperationException}. + * Reads the DosFileAttributes from the given path. Returns null if the attributes + * can't be read. * - * @param path the path to read. - * @param options options indicating how to handle symbolic links. - * @return the path attributes. + * @param path the path to read + * @param options options indicating how to handle symbolic links + * @return the path attributes * @since 2.12.0 */ public static DosFileAttributes readDosFileAttributes(final Path path, final LinkOption... options) { @@ -1327,12 +1321,12 @@ private static Path readIfSymbolicLink(final Path path) throws IOException { } /** - * Reads the PosixFileAttributes or DosFileAttributes from the given path. Returns null instead of throwing - * {@link UnsupportedOperationException}. + * Reads the PosixFileAttributes or DosFileAttributes from the given path. Returns null if the attributes + * can't be read. * - * @param path The Path to read. - * @param options options indicating how to handle symbolic links. - * @return the file attributes. + * @param path the Path to read + * @param options options indicating how to handle symbolic links + * @return the file attributes * @since 2.12.0 */ public static BasicFileAttributes readOsFileAttributes(final Path path, final LinkOption... options) { @@ -1344,9 +1338,9 @@ public static BasicFileAttributes readOsFileAttributes(final Path path, final Li * Reads the PosixFileAttributes from the given path. Returns null instead of throwing * {@link UnsupportedOperationException}. * - * @param path The Path to read. - * @param options options indicating how to handle symbolic links. - * @return the file attributes. + * @param path the Path to read + * @param options options indicating how to handle symbolic links + * @return the file attributes * @since 2.12.0 */ public static PosixFileAttributes readPosixFileAttributes(final Path path, final LinkOption... options) { @@ -1354,12 +1348,12 @@ public static PosixFileAttributes readPosixFileAttributes(final Path path, final } /** - * Reads the given path as a String. + * Reads the file at the given path into a String. * - * @param path The source path. - * @param charset How to convert bytes to a String, null uses the default Charset. - * @return a new String. - * @throws IOException if an I/O error occurs reading from the stream. + * @param path the source path + * @param charset how to convert bytes to a String, null uses the default Charset. + * @return a new String + * @throws IOException if an I/O error occurs reading from the stream * @see Files#readAllBytes(Path) * @since 2.12.0 */ @@ -1389,7 +1383,7 @@ static List relativize(final Collection collection, final Path paren * * @param file The {@link File} to check. * @param fileParamName The parameter name to use in the exception message in case of {@code null} input. - * @param options options indicating how to handle symbolic links. + * @param options options indicating how to handle symbolic links * @return the given file. * @throws NullPointerException if the given {@link File} is {@code null}. * @throws IllegalArgumentException if the given {@link File} does not exist. @@ -1510,7 +1504,7 @@ private static void setPosixReadOnlyFile(final Path path, final boolean readOnly * * @param path The path to set. * @param readOnly true for read-only, false for not read-only. - * @param linkOptions options indicating how to handle symbolic links. + * @param linkOptions options indicating how to handle symbolic links * @return The given path. * @throws IOException if an I/O error occurs. * @since 2.8.0 @@ -1651,7 +1645,7 @@ public static Path touch(final Path file) throws IOException { * @return the given visitor. * * @throws NoSuchFileException if the directory does not exist. - * @throws IOException if an I/O error is thrown by a visitor method. + * @throws IOException if an I/O error is thrown by a visitor method * @throws NullPointerException if the directory is {@code null}. */ public static > T visitFileTree(final T visitor, final Path directory) throws IOException { @@ -1671,7 +1665,7 @@ public static > T visitFileTree(final T visi * @param See {@link Files#walkFileTree(Path,Set,int,FileVisitor)}. * @return the given visitor. * - * @throws IOException if an I/O error is thrown by a visitor method. + * @throws IOException if an I/O error is thrown by a visitor method */ public static > T visitFileTree(final T visitor, final Path start, final Set options, final int maxDepth) throws IOException { @@ -1690,7 +1684,7 @@ public static > T visitFileTree(final T visi * @param See {@link Files#walkFileTree(Path,FileVisitor)}. * @return the given visitor. * - * @throws IOException if an I/O error is thrown by a visitor method. + * @throws IOException if an I/O error is thrown by a visitor method */ public static > T visitFileTree(final T visitor, final String first, final String... more) throws IOException { return visitFileTree(visitor, Paths.get(first, more)); @@ -1706,7 +1700,7 @@ public static > T visitFileTree(final T visi * @param See {@link Files#walkFileTree(Path,FileVisitor)}. * @return the given visitor. * - * @throws IOException if an I/O error is thrown by a visitor method. + * @throws IOException if an I/O error is thrown by a visitor method */ public static > T visitFileTree(final T visitor, final URI uri) throws IOException { return visitFileTree(visitor, Paths.get(uri)); @@ -1721,7 +1715,7 @@ public static > T visitFileTree(final T visi * * @param file the file to check, must not be {@code null}. * @param timeout the maximum time to wait. - * @param options options indicating how to handle symbolic links. + * @param options options indicating how to handle symbolic links * @return true if file exists. * @throws NullPointerException if the file is {@code null}. * @since 2.12.0 @@ -1810,7 +1804,7 @@ public static Path writeString(final Path path, final CharSequence charSequence, } /** - * Does allow to instantiate. + * Prevent instantiation */ private PathUtils() { // do not instantiate. From 839f442f131c625d80a27b167f2259e456edd5b7 Mon Sep 17 00:00:00 2001 From: Elliotte Rusty Harold Date: Sat, 7 Oct 2023 07:57:23 -0400 Subject: [PATCH 2/7] revert javadoc nits --- .../org/apache/commons/io/file/PathUtils.java | 90 ++++++++++--------- 1 file changed, 46 insertions(+), 44 deletions(-) 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 6d462f93332..1aff914530e 100644 --- a/src/main/java/org/apache/commons/io/file/PathUtils.java +++ b/src/main/java/org/apache/commons/io/file/PathUtils.java @@ -21,6 +21,7 @@ import java.io.IOException; import java.io.InputStream; import java.io.OutputStream; +import java.io.UncheckedIOException; import java.math.BigInteger; import java.net.URI; import java.net.URISyntaxException; @@ -76,6 +77,7 @@ import org.apache.commons.io.filefilter.IOFileFilter; import org.apache.commons.io.function.IOFunction; import org.apache.commons.io.function.IOSupplier; +import org.apache.commons.io.function.Uncheck; /** * NIO Path utilities. @@ -104,7 +106,7 @@ private static class RelativeSortedPaths { * @param maxDepth See {@link Files#walkFileTree(Path,Set,int,FileVisitor)}. * @param linkOptions Options indicating how symbolic links are handled. * @param fileVisitOptions See {@link Files#walkFileTree(Path,Set,int,FileVisitor)}. - * @throws IOException if an I/O error is thrown by a visitor method + * @throws IOException if an I/O error is thrown by a visitor method. */ private RelativeSortedPaths(final Path dir1, final Path dir2, final int maxDepth, final LinkOption[] linkOptions, final FileVisitOption[] fileVisitOptions) throws IOException { @@ -215,7 +217,7 @@ private RelativeSortedPaths(final Path dir1, final Path dir2, final int maxDepth * @param directory The directory to accumulate information. * @param maxDepth See {@link Files#walkFileTree(Path,Set,int,FileVisitor)}. * @param fileVisitOptions See {@link Files#walkFileTree(Path,Set,int,FileVisitor)}. - * @throws IOException if an I/O error is thrown by a visitor method + * @throws IOException if an I/O error is thrown by a visitor method. * @return file tree information. */ private static AccumulatorPathVisitor accumulate(final Path directory, final int maxDepth, final FileVisitOption[] fileVisitOptions) throws IOException { @@ -227,7 +229,7 @@ private static AccumulatorPathVisitor accumulate(final Path directory, final int * * @param directory directory to clean. * @return The visitation path counters. - * @throws IOException if an I/O error is thrown by a visitor method + * @throws IOException if an I/O error is thrown by a visitor method. */ public static PathCounters cleanDirectory(final Path directory) throws IOException { return cleanDirectory(directory, EMPTY_DELETE_OPTION_ARRAY); @@ -239,7 +241,7 @@ public static PathCounters cleanDirectory(final Path directory) throws IOExcepti * @param directory directory to clean. * @param deleteOptions How to handle deletion. * @return The visitation path counters. - * @throws IOException if an I/O error is thrown by a visitor method + * @throws IOException if an I/O error is thrown by a visitor method. * @since 2.8.0 */ public static PathCounters cleanDirectory(final Path directory, final DeleteOption... deleteOptions) throws IOException { @@ -251,7 +253,7 @@ public static PathCounters cleanDirectory(final Path directory, final DeleteOpti * * @param file the {@link Path} to test. * @param fileTime the time reference. - * @param options options indicating how to handle symbolic links + * @param options options indicating how to handle symbolic links. * @return See {@link FileTime#compareTo(FileTime)} * @throws IOException if an I/O error occurs. * @throws NullPointerException if the file is {@code null}. @@ -283,7 +285,7 @@ public static long copy(final IOSupplier in, final Path target, fin * @param targetDirectory The target directory. * @param copyOptions Specifies how the copying should be done. * @return The visitation path counters. - * @throws IOException if an I/O error is thrown by a visitor method + * @throws IOException if an I/O error is thrown by a visitor method. */ public static PathCounters copyDirectory(final Path sourceDirectory, final Path targetDirectory, final CopyOption... copyOptions) throws IOException { final Path absoluteSource = sourceDirectory.toAbsolutePath(); @@ -341,7 +343,7 @@ public static Path copyFileToDirectory(final URL sourceFile, final Path targetDi * * @param directory directory to delete. * @return The visitor used to count the given directory. - * @throws IOException if an I/O error is thrown by a visitor method + * @throws IOException if an I/O error is thrown by a visitor method. */ public static PathCounters countDirectory(final Path directory) throws IOException { return visitFileTree(CountingPathVisitor.withLongCounters(), directory).getPathCounters(); @@ -479,7 +481,7 @@ public static PathCounters delete(final Path path, final LinkOption[] linkOption * * @param directory directory to delete. * @return The visitor used to delete the given directory. - * @throws IOException if an I/O error is thrown by a visitor method + * @throws IOException if an I/O error is thrown by a visitor method. */ public static PathCounters deleteDirectory(final Path directory) throws IOException { return deleteDirectory(directory, EMPTY_DELETE_OPTION_ARRAY); @@ -491,7 +493,7 @@ public static PathCounters deleteDirectory(final Path directory) throws IOExcept * @param directory directory to delete. * @param deleteOptions How to handle deletion. * @return The visitor used to delete the given directory. - * @throws IOException if an I/O error is thrown by a visitor method + * @throws IOException if an I/O error is thrown by a visitor method. * @since 2.8.0 */ public static PathCounters deleteDirectory(final Path directory, final DeleteOption... deleteOptions) throws IOException { @@ -508,7 +510,7 @@ public static PathCounters deleteDirectory(final Path directory, final DeleteOpt * @param linkOptions How to handle symbolic links. * @param deleteOptions How to handle deletion. * @return The visitor used to delete the given directory. - * @throws IOException if an I/O error is thrown by a visitor method + * @throws IOException if an I/O error is thrown by a visitor method. * @since 2.9.0 */ public static PathCounters deleteDirectory(final Path directory, final LinkOption[] linkOptions, final DeleteOption... deleteOptions) throws IOException { @@ -612,7 +614,7 @@ public static void deleteOnExit(final Path path) { * @param path1 The first directory. * @param path2 The second directory. * @return Whether the two directories contain the same files while considering file contents. - * @throws IOException if an I/O error is thrown by a visitor method + * @throws IOException if an I/O error is thrown by a visitor method. */ public static boolean directoryAndFileContentEquals(final Path path1, final Path path2) throws IOException { return directoryAndFileContentEquals(path1, path2, EMPTY_LINK_OPTION_ARRAY, EMPTY_OPEN_OPTION_ARRAY, EMPTY_FILE_VISIT_OPTION_ARRAY); @@ -628,7 +630,7 @@ public static boolean directoryAndFileContentEquals(final Path path1, final Path * @param openOptions options to open files. * @param fileVisitOption options to configure traversal. * @return Whether the two directories contain the same files while considering file contents. - * @throws IOException if an I/O error is thrown by a visitor method + * @throws IOException if an I/O error is thrown by a visitor method. */ public static boolean directoryAndFileContentEquals(final Path path1, final Path path2, final LinkOption[] linkOptions, final OpenOption[] openOptions, final FileVisitOption[] fileVisitOption) throws IOException { @@ -669,7 +671,7 @@ public static boolean directoryAndFileContentEquals(final Path path1, final Path * @param path1 The first directory. * @param path2 The second directory. * @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 + * @throws IOException if an I/O error is thrown by a visitor method. */ public static boolean directoryContentEquals(final Path path1, final Path path2) throws IOException { return directoryContentEquals(path1, path2, Integer.MAX_VALUE, EMPTY_LINK_OPTION_ARRAY, EMPTY_FILE_VISIT_OPTION_ARRAY); @@ -685,7 +687,7 @@ public static boolean directoryContentEquals(final Path path1, final Path path2) * @param linkOptions options to follow links. * @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 + * @throws IOException if an I/O error is thrown by a visitor method. */ public static boolean directoryContentEquals(final Path path1, final Path path2, final int maxDepth, final LinkOption[] linkOptions, final FileVisitOption[] fileVisitOptions) throws IOException { @@ -1017,7 +1019,7 @@ public static boolean isEmptyFile(final Path file) throws IOException { * * @param file the {@link Path} to test. * @param czdt the time reference. - * @param options options indicating how to handle symbolic links + * @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. * @throws NullPointerException if the file is {@code null}. @@ -1033,7 +1035,7 @@ public static boolean isNewer(final Path file, final ChronoZonedDateTime czdt * * @param file the {@link Path} to test. * @param fileTime the time reference. - * @param options options indicating how to handle symbolic links + * @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. * @throws NullPointerException if the file is {@code null}. @@ -1051,7 +1053,7 @@ public static boolean isNewer(final Path file, final FileTime fileTime, final Li * * @param file the {@link Path} to test. * @param instant the time reference. - * @param options options indicating how to handle symbolic links + * @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. * @throws NullPointerException if the file is {@code null}. @@ -1066,7 +1068,7 @@ public static boolean isNewer(final Path file, final Instant instant, final Link * * @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 options options indicating how to handle symbolic links + * @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. * @throws NullPointerException if the file is {@code null}. @@ -1094,7 +1096,7 @@ public static boolean isNewer(final Path file, final Path reference) throws IOEx * * @param file the {@link Path} to test. * @param fileTime the time reference. - * @param options options indicating how to handle symbolic links + * @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. * @throws NullPointerException if the file is {@code null}. @@ -1112,7 +1114,7 @@ public static boolean isOlder(final Path file, final FileTime fileTime, final Li * * @param file the {@link Path} to test. * @param instant the time reference. - * @param options options indicating how to handle symbolic links + * @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. * @throws NullPointerException if the file is {@code null}. @@ -1127,7 +1129,7 @@ public static boolean isOlder(final Path file, final Instant instant, final Link * * @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 options options indicating how to handle symbolic links + * @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. * @throws NullPointerException if the file is {@code null}. @@ -1154,7 +1156,7 @@ public static boolean isOlder(final Path file, final Path reference) throws IOEx * Tests whether the given path is on a POSIX file system. * * @param test The Path to test. - * @param options options indicating how to handle symbolic links + * @param options options indicating how to handle symbolic links. * @return true if test is on a POSIX file system. * @since 2.12.0 */ @@ -1167,7 +1169,7 @@ public static boolean isPosix(final Path test, final LinkOption... options) { * {@code Files.isRegularFile(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 regular file; {@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 regular file or not. * @throws SecurityException In the case of the default provider, and a security manager is installed, the @@ -1248,7 +1250,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 path the Path to test + * @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 * @return the file attributes or null if the attributes can't be read @@ -1267,7 +1269,7 @@ public static A readAttributes(final Path path, /** * Reads the BasicFileAttributes from the given path. * - * @param path the path to read + * @param path the path to read. * @return the path attributes * @throws IOException if an I/O error occurs * @since 2.9.0 @@ -1280,7 +1282,7 @@ public static BasicFileAttributes readBasicFileAttributes(final Path path) throw * Reads the BasicFileAttributes from the given path. Returns null if the attributes * can't be read. * - * @param path the path to read + * @param path the path to read. * @param options options indicating how to handle symbolic links * @return the path attributes * @since 2.12.0 @@ -1293,7 +1295,7 @@ public static BasicFileAttributes readBasicFileAttributes(final Path path, final * Reads the BasicFileAttributes from the given path. Returns null if the attributes * can't be read. * - * @param path the Path to read + * @param path the Path to read. * @return the path attributes. * @since 2.9.0 * @deprecated Use {@link #readBasicFileAttributes(Path, LinkOption...)}. @@ -1307,7 +1309,7 @@ public static BasicFileAttributes readBasicFileAttributesUnchecked(final Path pa * Reads the DosFileAttributes from the given path. Returns null if the attributes * can't be read. * - * @param path the path to read + * @param path the path to read. * @param options options indicating how to handle symbolic links * @return the path attributes * @since 2.12.0 @@ -1324,7 +1326,7 @@ private static Path readIfSymbolicLink(final Path path) throws IOException { * Reads the PosixFileAttributes or DosFileAttributes from the given path. Returns null if the attributes * can't be read. * - * @param path the Path to read + * @param path the Path to read. * @param options options indicating how to handle symbolic links * @return the file attributes * @since 2.12.0 @@ -1338,9 +1340,9 @@ public static BasicFileAttributes readOsFileAttributes(final Path path, final Li * Reads the PosixFileAttributes from the given path. Returns null instead of throwing * {@link UnsupportedOperationException}. * - * @param path the Path to read - * @param options options indicating how to handle symbolic links - * @return the file attributes + * @param path The Path to read. + * @param options options indicating how to handle symbolic links. + * @return the file attributes. * @since 2.12.0 */ public static PosixFileAttributes readPosixFileAttributes(final Path path, final LinkOption... options) { @@ -1348,12 +1350,12 @@ public static PosixFileAttributes readPosixFileAttributes(final Path path, final } /** - * Reads the file at the given path into a String. + * Reads the given path as a String. * - * @param path the source path - * @param charset how to convert bytes to a String, null uses the default Charset. - * @return a new String - * @throws IOException if an I/O error occurs reading from the stream + * @param path The source path. + * @param charset How to convert bytes to a String, null uses the default Charset. + * @return a new String. + * @throws IOException if an I/O error occurs reading from the stream. * @see Files#readAllBytes(Path) * @since 2.12.0 */ @@ -1383,7 +1385,7 @@ static List relativize(final Collection collection, final Path paren * * @param file The {@link File} to check. * @param fileParamName The parameter name to use in the exception message in case of {@code null} input. - * @param options options indicating how to handle symbolic links + * @param options options indicating how to handle symbolic links. * @return the given file. * @throws NullPointerException if the given {@link File} is {@code null}. * @throws IllegalArgumentException if the given {@link File} does not exist. @@ -1504,7 +1506,7 @@ private static void setPosixReadOnlyFile(final Path path, final boolean readOnly * * @param path The path to set. * @param readOnly true for read-only, false for not read-only. - * @param linkOptions options indicating how to handle symbolic links + * @param linkOptions options indicating how to handle symbolic links. * @return The given path. * @throws IOException if an I/O error occurs. * @since 2.8.0 @@ -1645,7 +1647,7 @@ public static Path touch(final Path file) throws IOException { * @return the given visitor. * * @throws NoSuchFileException if the directory does not exist. - * @throws IOException if an I/O error is thrown by a visitor method + * @throws IOException if an I/O error is thrown by a visitor method. * @throws NullPointerException if the directory is {@code null}. */ public static > T visitFileTree(final T visitor, final Path directory) throws IOException { @@ -1665,7 +1667,7 @@ public static > T visitFileTree(final T visi * @param See {@link Files#walkFileTree(Path,Set,int,FileVisitor)}. * @return the given visitor. * - * @throws IOException if an I/O error is thrown by a visitor method + * @throws IOException if an I/O error is thrown by a visitor method. */ public static > T visitFileTree(final T visitor, final Path start, final Set options, final int maxDepth) throws IOException { @@ -1684,7 +1686,7 @@ public static > T visitFileTree(final T visi * @param See {@link Files#walkFileTree(Path,FileVisitor)}. * @return the given visitor. * - * @throws IOException if an I/O error is thrown by a visitor method + * @throws IOException if an I/O error is thrown by a visitor method. */ public static > T visitFileTree(final T visitor, final String first, final String... more) throws IOException { return visitFileTree(visitor, Paths.get(first, more)); @@ -1700,7 +1702,7 @@ public static > T visitFileTree(final T visi * @param See {@link Files#walkFileTree(Path,FileVisitor)}. * @return the given visitor. * - * @throws IOException if an I/O error is thrown by a visitor method + * @throws IOException if an I/O error is thrown by a visitor method. */ public static > T visitFileTree(final T visitor, final URI uri) throws IOException { return visitFileTree(visitor, Paths.get(uri)); @@ -1715,7 +1717,7 @@ public static > T visitFileTree(final T visi * * @param file the file to check, must not be {@code null}. * @param timeout the maximum time to wait. - * @param options options indicating how to handle symbolic links + * @param options options indicating how to handle symbolic links. * @return true if file exists. * @throws NullPointerException if the file is {@code null}. * @since 2.12.0 From afc6678955d88c2ca7746238102d2467afd40d22 Mon Sep 17 00:00:00 2001 From: Elliotte Rusty Harold Date: Sat, 7 Oct 2023 07:59:57 -0400 Subject: [PATCH 3/7] revert javadoc nits --- .../org/apache/commons/io/file/PathUtils.java | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) 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 1aff914530e..0be0ac32af7 100644 --- a/src/main/java/org/apache/commons/io/file/PathUtils.java +++ b/src/main/java/org/apache/commons/io/file/PathUtils.java @@ -1249,9 +1249,9 @@ 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 path the Path to test. - * @param type the {@link Class} of the file attributes required to read + * @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 * @return the file attributes or null if the attributes can't be read * @see Files#readAttributes(Path, Class, LinkOption...) @@ -1270,8 +1270,8 @@ public static A readAttributes(final Path path, * Reads the BasicFileAttributes from the given path. * * @param path the path to read. - * @return the path attributes - * @throws IOException if an I/O error occurs + * @return the path attributes. + * @throws IOException if an I/O error occurs. * @since 2.9.0 */ public static BasicFileAttributes readBasicFileAttributes(final Path path) throws IOException { @@ -1283,8 +1283,8 @@ public static BasicFileAttributes readBasicFileAttributes(final Path path) throw * can't be read. * * @param path the path to read. - * @param options options indicating how to handle symbolic links - * @return the path attributes + * @param options options indicating how to handle symbolic links. + * @return the path attributes. * @since 2.12.0 */ public static BasicFileAttributes readBasicFileAttributes(final Path path, final LinkOption... options) { @@ -1310,8 +1310,8 @@ public static BasicFileAttributes readBasicFileAttributesUnchecked(final Path pa * can't be read. * * @param path the path to read. - * @param options options indicating how to handle symbolic links - * @return the path attributes + * @param options options indicating how to handle symbolic links. + * @return the path attributes. * @since 2.12.0 */ public static DosFileAttributes readDosFileAttributes(final Path path, final LinkOption... options) { @@ -1327,8 +1327,8 @@ private static Path readIfSymbolicLink(final Path path) throws IOException { * can't be read. * * @param path the Path to read. - * @param options options indicating how to handle symbolic links - * @return the file attributes + * @param options options indicating how to handle symbolic links. + * @return the file attributes. * @since 2.12.0 */ public static BasicFileAttributes readOsFileAttributes(final Path path, final LinkOption... options) { From 440c36a394df07658e04508f5933a06a81bcf2e6 Mon Sep 17 00:00:00 2001 From: Elliotte Rusty Harold Date: Sat, 7 Oct 2023 08:11:40 -0400 Subject: [PATCH 4/7] revert javadoc nits --- src/main/java/org/apache/commons/io/file/PathUtils.java | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) 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 0be0ac32af7..b245e528205 100644 --- a/src/main/java/org/apache/commons/io/file/PathUtils.java +++ b/src/main/java/org/apache/commons/io/file/PathUtils.java @@ -1252,8 +1252,8 @@ private static boolean overrideReadOnly(final DeleteOption... deleteOptions) { * @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 - * @return the file attributes or null if the attributes can't be read + * @param options options indicating how to handle symbolic links. + * @return the file attributes or null if the attributes can't be read. * @see Files#readAttributes(Path, Class, LinkOption...) * @since 2.12.0 */ @@ -1295,7 +1295,7 @@ public static BasicFileAttributes readBasicFileAttributes(final Path path, final * Reads the BasicFileAttributes from the given path. Returns null if the attributes * can't be read. * - * @param path the Path to read. + * @param path the path to read. * @return the path attributes. * @since 2.9.0 * @deprecated Use {@link #readBasicFileAttributes(Path, LinkOption...)}. @@ -1309,7 +1309,7 @@ public static BasicFileAttributes readBasicFileAttributesUnchecked(final Path pa * Reads the DosFileAttributes from the given path. Returns null if the attributes * can't be read. * - * @param path the path to read. + * @param path The path to read. * @param options options indicating how to handle symbolic links. * @return the path attributes. * @since 2.12.0 From b1101bdbdabc035e1265d3ea906f892cf6d333a6 Mon Sep 17 00:00:00 2001 From: Elliotte Rusty Harold Date: Sat, 7 Oct 2023 08:16:24 -0400 Subject: [PATCH 5/7] revert javadoc nits --- src/main/java/org/apache/commons/io/file/PathUtils.java | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 b245e528205..43e7cc74b52 100644 --- a/src/main/java/org/apache/commons/io/file/PathUtils.java +++ b/src/main/java/org/apache/commons/io/file/PathUtils.java @@ -1309,7 +1309,7 @@ public static BasicFileAttributes readBasicFileAttributesUnchecked(final Path pa * Reads the DosFileAttributes from the given path. Returns null if the attributes * can't be read. * - * @param path The path to read. + * @param path the path to read. * @param options options indicating how to handle symbolic links. * @return the path attributes. * @since 2.12.0 @@ -1326,7 +1326,7 @@ private static Path readIfSymbolicLink(final Path path) throws IOException { * Reads the PosixFileAttributes or DosFileAttributes from the given path. Returns null if the attributes * can't be read. * - * @param path the Path to read. + * @param path The Path to read. * @param options options indicating how to handle symbolic links. * @return the file attributes. * @since 2.12.0 From f70b53338250f5fd3a4ada53fb41b537535a2653 Mon Sep 17 00:00:00 2001 From: Gary Gregory Date: Sat, 7 Oct 2023 08:27:47 -0400 Subject: [PATCH 6/7] Remove unused imports --- src/main/java/org/apache/commons/io/file/PathUtils.java | 2 -- 1 file changed, 2 deletions(-) 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 43e7cc74b52..98dfdddafec 100644 --- a/src/main/java/org/apache/commons/io/file/PathUtils.java +++ b/src/main/java/org/apache/commons/io/file/PathUtils.java @@ -21,7 +21,6 @@ import java.io.IOException; import java.io.InputStream; import java.io.OutputStream; -import java.io.UncheckedIOException; import java.math.BigInteger; import java.net.URI; import java.net.URISyntaxException; @@ -77,7 +76,6 @@ import org.apache.commons.io.filefilter.IOFileFilter; import org.apache.commons.io.function.IOFunction; import org.apache.commons.io.function.IOSupplier; -import org.apache.commons.io.function.Uncheck; /** * NIO Path utilities. From e21541f680985f9eec9f54e9954bdd2d01fdcebe Mon Sep 17 00:00:00 2001 From: Gary Gregory Date: Sat, 7 Oct 2023 10:18:09 -0400 Subject: [PATCH 7/7] Javadoc --- src/main/java/org/apache/commons/io/file/PathUtils.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 98dfdddafec..ba553df225f 100644 --- a/src/main/java/org/apache/commons/io/file/PathUtils.java +++ b/src/main/java/org/apache/commons/io/file/PathUtils.java @@ -1804,7 +1804,7 @@ public static Path writeString(final Path path, final CharSequence charSequence, } /** - * Prevent instantiation + * Prevents instantiation. */ private PathUtils() { // do not instantiate.