From 52f61bbe6e0d499032474bdaee54563844f42baf Mon Sep 17 00:00:00 2001 From: Elliotte Rusty Harold Date: Thu, 28 May 2020 07:23:39 -0400 Subject: [PATCH 1/2] deprecate more methods and clean up api doc and tests --- .../maven/shared/utils/io/FileUtils.java | 120 ++++++++++-------- .../maven/shared/utils/io/FileUtilsTest.java | 43 +------ 2 files changed, 71 insertions(+), 92 deletions(-) diff --git a/src/main/java/org/apache/maven/shared/utils/io/FileUtils.java b/src/main/java/org/apache/maven/shared/utils/io/FileUtils.java index d8023c5d..df47230a 100644 --- a/src/main/java/org/apache/maven/shared/utils/io/FileUtils.java +++ b/src/main/java/org/apache/maven/shared/utils/io/FileUtils.java @@ -1221,8 +1221,7 @@ private static boolean deleteFile( @Nonnull File file ) * Make a directory. * * @param file not null - * @throws IOException If there already exists a file with specified name or - * the directory is unable to be created + * @throws IOException if a file already exists with the specified name or the directory is unable to be created * @throws IllegalArgumentException if the file contains illegal Windows characters under Windows OS. * @see #INVALID_CHARACTERS_FOR_WINDOWS_FILE_NAME */ @@ -1260,7 +1259,9 @@ public static void forceMkdir( @Nonnull final File file ) * * @param directory a directory * @throws IOException if any + * @deprecated use {@code org.apache.commons.io.FileUtils.deleteDirectory()} */ + @Deprecated public static void deleteDirectory( @Nonnull final String directory ) throws IOException { @@ -1272,7 +1273,9 @@ public static void deleteDirectory( @Nonnull final String directory ) * * @param directory a directory * @throws IOException if any + * @deprecated use {@code org.apache.commons.io.FileUtils.deleteDirectory()} */ + @Deprecated public static void deleteDirectory( @Nonnull final File directory ) throws IOException { @@ -1298,11 +1301,14 @@ public static void deleteDirectory( @Nonnull final File directory ) } /** - * Clean a directory without deleting it. + * Remove all files from a directory without deleting it. * * @param directory a directory - * @throws IOException if any + * @throws IOException if any. This can leave cleaning in a half-finished state where + * some but not all files have been deleted. + * @deprecated use {@code org.apache.commons.io.FileUtils.cleanDirectory()} */ + @Deprecated public static void cleanDirectory( @Nonnull final File directory ) throws IOException { @@ -1350,7 +1356,9 @@ public static void cleanDirectory( @Nonnull final File directory ) * * @param directory a directory * @return size of directory in bytes + * @deprecated use {@code org.apache.commons.io.FileUtils.sizeOf()} */ + @Deprecated public static long sizeOfDirectory( @Nonnull final String directory ) { return sizeOfDirectory( new File( directory ) ); @@ -1361,7 +1369,9 @@ public static long sizeOfDirectory( @Nonnull final String directory ) * * @param directory a directory * @return size of directory in bytes + * @deprecated use {@code org.apache.commons.io.FileUtils.sizeOf()} */ + @Deprecated public static long sizeOfDirectory( @Nonnull final File directory ) { if ( !directory.exists() ) @@ -1404,8 +1414,8 @@ public static long sizeOfDirectory( @Nonnull final File directory ) * including the directory name in each of the files * * @param directory the directory to scan - * @param includes the includes pattern, comma separated - * @param excludes the excludes pattern, comma separated + * @param includes the Ant includes pattern, comma separated + * @param excludes the Ant excludes pattern, comma separated * @return a list of File objects * @throws IOException in case of failure. * @see #getFileNames(File, String, String, boolean) @@ -1450,11 +1460,11 @@ public static List getFiles( @Nonnull File directory, @Nullable String inc * This method use case sensitive file name. * * @param directory the directory to scan - * @param includes the includes pattern, comma separated - * @param excludes the excludes pattern, comma separated - * @param includeBasedir true to include the base dir in each String of file - * @return a list of files as String - * @throws IOException in case of failure. + * @param includes the Ant includes pattern, comma separated + * @param excludes the Ant excludes pattern, comma separated + * @param includeBasedir true to include the base directory in each String of file + * @return a list of file names + * @throws IOException in case of failure */ @Nonnull public static List getFileNames( @Nonnull File directory, @Nullable String includes, @Nullable String excludes, boolean includeBasedir ) @@ -1467,8 +1477,8 @@ public static List getFiles( @Nonnull File directory, @Nullable String inc * Return a list of files as String depending options. * * @param directory the directory to scan - * @param includes the includes pattern, comma separated - * @param excludes the excludes pattern, comma separated + * @param includes the Ant includes pattern, comma separated + * @param excludes the Ant excludes pattern, comma separated * @param includeBasedir true to include the base dir in each String of file * @param isCaseSensitive true if case sensitive * @return a list of files as String @@ -1487,8 +1497,8 @@ public static List getFiles( @Nonnull File directory, @Nullable String inc * This method use case sensitive file name. * * @param directory the directory to scan - * @param includes the includes pattern, comma separated - * @param excludes the excludes pattern, comma separated + * @param includes the Ant includes pattern, comma separated + * @param excludes the Ant excludes pattern, comma separated * @param includeBasedir true to include the base dir in each String of file * @return a list of directories as String * @throws IOException in case of failure. @@ -1501,15 +1511,15 @@ public static List getFiles( @Nonnull File directory, @Nullable String inc } /** - * Return a list of directories as String depending options. + * Return a list of directories as Strings. * * @param directory the directory to scan - * @param includes the includes pattern, comma separated - * @param excludes the excludes pattern, comma separated - * @param includeBasedir true to include the base dir in each String of file + * @param includes the Ant includes pattern, comma separated + * @param excludes the Ant excludes pattern, comma separated + * @param includeBasedir true to include the base directory in each String of file * @param isCaseSensitive true if case sensitive * @return a list of directories as String - * @throws IOException in case of failure. + * @throws IOException in case of failure */ @Nonnull public static List getDirectoryNames( @Nonnull File directory, @Nullable String includes, @Nullable String excludes, boolean includeBasedir, @@ -1520,16 +1530,16 @@ public static List getFiles( @Nonnull File directory, @Nullable String inc } /** - * Return a list of files as String depending options. + * Return a list of file names as Strings. * * @param directory the directory to scan - * @param includes the includes pattern, comma separated - * @param excludes the excludes pattern, comma separated - * @param includeBasedir true to include the base dir in each String of file + * @param includes the Ant includes pattern, comma separated + * @param excludes the Ant excludes pattern, comma separated + * @param includeBasedir true to include the base directory in each String of file * @param isCaseSensitive true if case sensitive - * @param getFiles true if get files - * @param getDirectories true if get directories - * @return a list of files as String + * @param getFiles true to include regular files + * @param getDirectories true to include directories + * @return a list of file names */ @Nonnull public static List getFileAndDirectoryNames( File directory, @Nullable String includes, @Nullable String excludes, boolean includeBasedir, @@ -1594,10 +1604,10 @@ public static List getFiles( @Nonnull File directory, @Nullable String inc } /** - * Copy a directory to an other one. + * Copy the contents of a directory into another one. * - * @param sourceDirectory the source dir - * @param destinationDirectory the target dir + * @param sourceDirectory the source directory + * @param destinationDirectory the target directory * @throws IOException if any */ public static void copyDirectory( @Nonnull File sourceDirectory, @Nonnull File destinationDirectory ) @@ -1607,12 +1617,12 @@ public static void copyDirectory( @Nonnull File sourceDirectory, @Nonnull File d } /** - * Copy a directory to an other one. + * Copy the contents of a directory into another one. * - * @param sourceDirectory the source dir - * @param destinationDirectory the target dir - * @param includes include pattern - * @param excludes exlucde pattern + * @param sourceDirectory the source directory + * @param destinationDirectory the target directory + * @param includes Ant include pattern + * @param excludes Ant exclude pattern * @throws IOException if any * @see #getFiles(File, String, String) */ @@ -1634,18 +1644,20 @@ public static void copyDirectory( @Nonnull File sourceDirectory, @Nonnull File d } /** - * Copies a entire directory structure. + * Copies an entire directory structure. *

* Note: *

    *
  • It will include empty directories. - *
  • The sourceDirectory must exists. + *
  • The sourceDirectory must exist. *
* * @param sourceDirectory the source dir * @param destinationDirectory the target dir * @throws IOException if any + * @deprecated use {@code org.apache.commons.io.FileUtils.copyDirectory()} */ + @Deprecated public static void copyDirectoryStructure( @Nonnull File sourceDirectory, @Nonnull File destinationDirectory ) throws IOException { @@ -1743,7 +1755,9 @@ else if ( file.isDirectory() ) * @param to the new file name * @throws IOException if anything bad happens during this process. * Note that to may have been deleted already when this happens. + * @deprecated use {@code java.nio.Files.move()} */ + @Deprecated public static void rename( @Nonnull File from, @Nonnull File to ) throws IOException { @@ -1774,23 +1788,24 @@ public static void rename( @Nonnull File from, @Nonnull File to ) *

The file denoted by the returned abstract pathname did not * exist before this method was invoked, any subsequent invocation * of this method will yield a different file name.

- *

+ *

* The filename is prefixNNNNNsuffix where NNNN is a random number *

- *

This method is different to {@link File#createTempFile(String, String, File)} of JDK 1.2 + *

This method is different to {@link File#createTempFile(String, String, File)} * as it doesn't create the file itself. * It uses the location pointed to by java.io.tmpdir - * when the parentDir attribute is - * null.

- *

To delete automatically the file created by this method, use the + * when the parentDir attribute is null.

+ *

To automatically delete the file created by this method, use the * {@link File#deleteOnExit()} method.

* * @param prefix prefix before the random number * @param suffix file extension; include the '.' - * @param parentDir Directory to create the temporary file in -java.io.tmpdir - * used if not specificed + * @param parentDir directory to create the temporary file in -java.io.tmpdir + * used if not specified * @return a File reference to the new temporary file. + * @deprecated use {@code java.nio.Files.createTempFile()} */ + @Deprecated public static File createTempFile( @Nonnull String prefix, @Nonnull String suffix, @Nullable File parentDir ) { File result; @@ -1823,7 +1838,7 @@ private static int positiveRandom( Random rand ) } /** - * If wrappers is null or empty, the file will be copy only if to.lastModified() < from.lastModified() + * If wrappers is null or empty, the file will be copied only if to.lastModified() < from.lastModified() * * @param from the file to copy * @param to the destination file @@ -1840,13 +1855,12 @@ public static void copyFile( @Nonnull File from, @Nonnull File to, @Nullable Str /** * Wrapper class for Filter. - * */ public abstract static class FilterWrapper { /** * @param fileReader {@link Reader} - * @return The Reader instance. + * @return the Reader instance */ public abstract Reader getReader( Reader fileReader ); } @@ -1859,8 +1873,8 @@ public abstract static class FilterWrapper * @param to the destination file * @param encoding the file output encoding (only if wrappers is not empty) * @param wrappers array of {@link FilterWrapper} - * @param overwrite if true and f wrappers is null or empty, the file will be copy enven if to.lastModified() < - * from.lastModified() + * @param overwrite if true and wrappers is null or empty, the file will be copied even if + * to.lastModified() < from.lastModified() * @throws IOException if an IO error occurs during copying or filtering */ public static void copyFile( @Nonnull File from, @Nonnull File to, @Nullable String encoding, @@ -2103,10 +2117,10 @@ public static boolean isSymbolicLinkForSure( @Nonnull final File file ) } /** - * @param symlink The link name. - * @param target The target. - * @return The linked file. - * @throws IOException in case of an error. + * @param symlink the link name + * @param target the target + * @return the linked file + * @throws IOException in case of an error */ @Nonnull public static File createSymbolicLink( @Nonnull File symlink, @Nonnull File target ) throws IOException diff --git a/src/test/java/org/apache/maven/shared/utils/io/FileUtilsTest.java b/src/test/java/org/apache/maven/shared/utils/io/FileUtilsTest.java index 90d93c60..9fa7c85e 100644 --- a/src/test/java/org/apache/maven/shared/utils/io/FileUtilsTest.java +++ b/src/test/java/org/apache/maven/shared/utils/io/FileUtilsTest.java @@ -74,6 +74,7 @@ * @version $Id: FileUtilsTestCase.java 1081025 2011-03-13 00:45:10Z niallp $ * @see FileUtils */ +@SuppressWarnings( "deprecation" ) public class FileUtilsTest { @@ -90,11 +91,6 @@ public class FileUtilsTest */ private static final int TEST_DIRECTORY_SIZE = 0; - /** - * Delay in milliseconds to make sure test for "last modified date" are accurate - */ - //private static final int LAST_MODIFIED_DELAY = 600; - private File testFile1; private File testFile2; @@ -132,18 +128,10 @@ void createFile( File file, long size ) { throw new IOException( "Cannot create file " + file + " as the parent directory does not exist" ); } - - OutputStream out = null; - try + + try (OutputStream out = new BufferedOutputStream( new FileOutputStream( file ) ) ) { - out = new BufferedOutputStream( new FileOutputStream( file ) ); FileTestHelper.generateTestData( out, size ); - out.close(); - out = null; - } - finally - { - IOUtil.close( out ); } } @@ -258,26 +246,6 @@ public void toURLs1() assertThat( urls[2].toExternalForm(), containsString( "test%20file.txt" ) ); } -// @Test public void toURLs2() throws Exception { -// File[] files = new File[] { -// new File(getTestDirectory(), "file1.txt"), -// null, -// }; -// URL[] urls = FileUtils.toURLs(files); -// -// assertEquals(files.length, urls.length); -// assertEquals(true, urls[0].toExternalForm().startsWith("file:")); -// assertEquals(true, urls[0].toExternalForm().indexOf("file1.txt") > 0); -// assertEquals(null, urls[1]); -// } -// -// @Test public void toURLs3() throws Exception { -// File[] files = null; -// URL[] urls = FileUtils.toURLs(files); -// -// assertEquals(0, urls.length); -// } - // contentEquals @Test @@ -676,8 +644,6 @@ public void copyFileWithFilteringAndNewerDestinationAndMatchingContent() "Hello Bob!" ); - String encoding = null; - FileUtils.copyFile( from, to, null, wrappers( "name", "Bob" ) ); assertFileContent( to, "Hello Bob!" ); @@ -689,7 +655,7 @@ public void copyFileWithFilteringAndNewerDestinationAndMatchingContent() private FileUtils.FilterWrapper[] wrappers( String key, String value ) { - final Map map = new HashMap(); + final Map map = new HashMap<>(); map.put( key, value ); return new FileUtils.FilterWrapper[] { @@ -1416,7 +1382,6 @@ public void getDefaultExcludes() //// getDefaultExcludesAsList @Test - @SuppressWarnings( "unchecked" ) public void getDefaultExcludesAsList() throws Exception { From c51d9d98408110c0bab1c6b58f283b99b0ad8e74 Mon Sep 17 00:00:00 2001 From: Elliotte Rusty Harold Date: Thu, 28 May 2020 15:52:54 -0400 Subject: [PATCH 2/2] Files.createSymbolicLink(Path) --- src/main/java/org/apache/maven/shared/utils/io/FileUtils.java | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/main/java/org/apache/maven/shared/utils/io/FileUtils.java b/src/main/java/org/apache/maven/shared/utils/io/FileUtils.java index df47230a..b04b34b5 100644 --- a/src/main/java/org/apache/maven/shared/utils/io/FileUtils.java +++ b/src/main/java/org/apache/maven/shared/utils/io/FileUtils.java @@ -2117,10 +2117,14 @@ public static boolean isSymbolicLinkForSure( @Nonnull final File file ) } /** + * Create a new symbolic link, possibly replacing an existing symbolic link. + * * @param symlink the link name * @param target the target * @return the linked file * @throws IOException in case of an error + * @see {@code java.nio.file.Files.createSymbolicLink(Path)} which creates a new + * symbolic link but does not replace exsiting symbolic links */ @Nonnull public static File createSymbolicLink( @Nonnull File symlink, @Nonnull File target ) throws IOException