You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by gg...@apache.org on 2019/05/16 15:12:49 UTC
[commons-io] branch master updated: Close Javadoc tags.
This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-io.git
The following commit(s) were added to refs/heads/master by this push:
new 645f4ef Close Javadoc tags.
645f4ef is described below
commit 645f4ef4971ac1517df922808e33fce6b577fa2c
Author: Gary Gregory <ga...@gmail.com>
AuthorDate: Thu May 16 11:12:46 2019 -0400
Close Javadoc tags.
---
src/main/java/org/apache/commons/io/FileUtils.java | 84 ++++++++++++++++++++--
1 file changed, 78 insertions(+), 6 deletions(-)
diff --git a/src/main/java/org/apache/commons/io/FileUtils.java b/src/main/java/org/apache/commons/io/FileUtils.java
index ac2118b..874eff9 100644
--- a/src/main/java/org/apache/commons/io/FileUtils.java
+++ b/src/main/java/org/apache/commons/io/FileUtils.java
@@ -57,6 +57,7 @@ import org.apache.commons.io.output.NullOutputStream;
* General file manipulation utilities.
* <p>
* Facilities are provided in the following areas:
+ * </p>
* <ul>
* <li>writing to a file
* <li>reading from a file
@@ -73,8 +74,10 @@ import org.apache.commons.io.output.NullOutputStream;
* Note that a specific charset should be specified whenever possible.
* Relying on the platform default means that the code is Locale-dependent.
* Only use the default if the files are known to always use the platform default.
+ * </p>
* <p>
* Origin of code: Excalibur, Alexandria, Commons-Utils
+ * </p>
*/
public class FileUtils {
@@ -268,10 +271,12 @@ public class FileUtils {
* <p>
* At the end of the method either the stream will be successfully opened,
* or an exception will have been thrown.
+ * </p>
* <p>
* An exception is thrown if the file does not exist.
* An exception is thrown if the file object exists but is a directory.
* An exception is thrown if the file exists but cannot be read.
+ * </p>
*
* @param file the file to open for input, must not be {@code null}
* @return a new {@link FileInputStream} for the specified file
@@ -301,12 +306,14 @@ public class FileUtils {
* <p>
* At the end of the method either the stream will be successfully opened,
* or an exception will have been thrown.
+ * </p>
* <p>
* The parent directory will be created if it does not exist.
* The file will be created if it does not exist.
* An exception is thrown if the file object exists but is a directory.
* An exception is thrown if the file exists but cannot be written to.
* An exception is thrown if the parent directory cannot be created.
+ * </p>
*
* @param file the file to open for output, must not be {@code null}
* @return a new {@link FileOutputStream} for the specified file
@@ -325,12 +332,14 @@ public class FileUtils {
* <p>
* At the end of the method either the stream will be successfully opened,
* or an exception will have been thrown.
+ * </p>
* <p>
* The parent directory will be created if it does not exist.
* The file will be created if it does not exist.
* An exception is thrown if the file object exists but is a directory.
* An exception is thrown if the file exists but cannot be written to.
* An exception is thrown if the parent directory cannot be created.
+ * </p>
*
* @param file the file to open for output, must not be {@code null}
* @param append if {@code true}, then bytes will be added to the
@@ -426,6 +435,7 @@ public class FileUtils {
* NOTE: As from v1.3, this method throws an IOException if the last
* modified date of the file cannot be set. Also, as from v1.3 this method
* creates parent directories if they do not exist.
+ * </p>
*
* @param file the File to touch
* @throws IOException If an I/O problem occurs
@@ -489,13 +499,16 @@ public class FileUtils {
* an IOFileFilter for directories. You don't need to bind a
* DirectoryFileFilter (via logical AND) to this filter. This method does
* that for you.
+ * </p>
* <p>
* An example: If you want to search through all directories called
* "temp" you pass in <code>FileFilterUtils.NameFileFilter("temp")</code>
+ * </p>
* <p>
* Another common usage of this method is find files in a directory
* tree but ignoring the directories generated CVS. You can simply pass
* in <code>FileFilterUtils.makeCVSAware(null)</code>.
+ * </p>
*
* @param directory the directory to search in
* @param fileFilter filter to apply when finding files. Must not be {@code null},
@@ -558,7 +571,7 @@ public class FileUtils {
* <p>
* The resulting collection includes the starting directory and
* any subdirectories that match the directory filter.
- * <p>
+ * </p>
*
* @param directory the directory to search in
* @param fileFilter filter to apply when finding files.
@@ -616,7 +629,8 @@ public class FileUtils {
* All files found are filtered by an IOFileFilter. This method is
* based on {@link #listFiles(File, IOFileFilter, IOFileFilter)},
* which supports Iterable ('foreach' loop).
- * <p>
+ * </p>
+ *
* @param directory the directory to search in
* @param fileFilter filter to apply when finding files.
* @param dirFilter optional filter to apply when finding subdirectories.
@@ -639,8 +653,10 @@ public class FileUtils {
* All files found are filtered by an IOFileFilter. This method is
* based on {@link #listFilesAndDirs(File, IOFileFilter, IOFileFilter)},
* which supports Iterable ('foreach' loop).
+ * </p>
* <p>
* The resulting iterator includes the subdirectories themselves.
+ * </p>
*
* @param directory the directory to search in
* @param fileFilter filter to apply when finding files.
@@ -722,8 +738,10 @@ public class FileUtils {
* This method checks to see if the two files are different lengths
* or if they point to the same file, before resorting to byte-by-byte
* comparison of the contents.
+ * </p>
* <p>
* Code origin: Avalon
+ * </p>
*
* @param file1 the first file
* @param file2 the second file
@@ -769,7 +787,7 @@ public class FileUtils {
* <p>
* This method checks to see if the two files point to the same file,
* before resorting to line-by-line comparison of the contents.
- * <p>
+ * </p>
*
* @param file1 the first file
* @param file2 the second file
@@ -823,6 +841,7 @@ public class FileUtils {
* 1.5, this method uses UTF-8 to decode percent-encoded octets to characters.
* Additionally, malformed percent-encoded octets are handled leniently by
* passing them through literally.
+ * </p>
*
* @param url the file URL to convert, {@code null} returns {@code null}
* @return the equivalent <code>File</code> object, or {@code null}
@@ -891,10 +910,12 @@ public class FileUtils {
* If the input is {@code null}, an empty array is returned.
* If the input contains {@code null}, the output array contains {@code null} at the same
* index.
+ * </p>
* <p>
* This method will decode the URL.
* Syntax such as <code>file:///my%20docs/file.txt</code> will be
* correctly decoded to <code>/my docs/file.txt</code>.
+ * </p>
*
* @param urls the file URLs to convert, {@code null} returns empty array
* @return a non-{@code null} array of Files matching the input, with a {@code null} item
@@ -925,6 +946,7 @@ public class FileUtils {
* Converts each of an array of <code>File</code> to a <code>URL</code>.
* <p>
* Returns an array of the same size as the input.
+ * </p>
*
* @param files the files to convert, must not be {@code null}
* @return an array of URLs matching the input
@@ -949,11 +971,13 @@ public class FileUtils {
* to a file of the same name in the specified destination directory.
* The destination directory is created if it does not exist.
* If the destination file exists, then this method will overwrite it.
+ * </p>
* <p>
* <strong>Note:</strong> This method tries to preserve the file's last
* modified date/times using {@link File#setLastModified(long)}, however
* it is not guaranteed that the operation will succeed.
* If the modification operation fails, no indication is provided.
+ * </p>
*
* @param srcFile an existing file to copy, must not be {@code null}
* @param destDir the directory to place the copy in, must not be {@code null}
@@ -974,12 +998,14 @@ public class FileUtils {
* to a file of the same name in the specified destination directory.
* The destination directory is created if it does not exist.
* If the destination file exists, then this method will overwrite it.
+ * </p>
* <p>
* <strong>Note:</strong> Setting <code>preserveFileDate</code> to
* {@code true} tries to preserve the file's last modified
* date/times using {@link File#setLastModified(long)}, however it is
* not guaranteed that the operation will succeed.
* If the modification operation fails, no indication is provided.
+ * </p>
*
* @param srcFile an existing file to copy, must not be {@code null}
* @param destDir the directory to place the copy in, must not be {@code null}
@@ -1013,11 +1039,13 @@ public class FileUtils {
* specified destination file. The directory holding the destination file is
* created if it does not exist. If the destination file exists, then this
* method will overwrite it.
+ * </p>
* <p>
* <strong>Note:</strong> This method tries to preserve the file's last
* modified date/times using {@link File#setLastModified(long)}, however
* it is not guaranteed that the operation will succeed.
* If the modification operation fails, no indication is provided.
+ * </p>
*
* @param srcFile an existing file to copy, must not be {@code null}
* @param destFile the new file, must not be {@code null}
@@ -1041,12 +1069,14 @@ public class FileUtils {
* to the specified destination file.
* The directory holding the destination file is created if it does not exist.
* If the destination file exists, then this method will overwrite it.
+ * </p>
* <p>
* <strong>Note:</strong> Setting <code>preserveFileDate</code> to
* {@code true} tries to preserve the file's last modified
* date/times using {@link File#setLastModified(long)}, however it is
* not guaranteed that the operation will succeed.
* If the modification operation fails, no indication is provided.
+ * </p>
*
* @param srcFile an existing file to copy, must not be {@code null}
* @param destFile the new file, must not be {@code null}
@@ -1160,15 +1190,18 @@ public class FileUtils {
* <p>
* This method copies the source directory and all its contents to a
* directory of the same name in the specified destination directory.
+ * </p>
* <p>
* The destination directory is created if it does not exist.
* If the destination directory did exist, then this method merges
* the source with the destination, with the source taking precedence.
+ * </p>
* <p>
* <strong>Note:</strong> This method tries to preserve the files' last
* modified date/times using {@link File#setLastModified(long)}, however
* it is not guaranteed that those operations will succeed.
* If the modification operation fails, no indication is provided.
+ * </p>
*
* @param srcDir an existing directory to copy, must not be {@code null}
* @param destDir the directory to place the copy in, must not be {@code null}
@@ -1200,15 +1233,18 @@ public class FileUtils {
* This method copies the specified directory and all its child
* directories and files to the specified destination.
* The destination is the new location and name of the directory.
+ * </p>
* <p>
* The destination directory is created if it does not exist.
* If the destination directory did exist, then this method merges
* the source with the destination, with the source taking precedence.
+ * </p>
* <p>
* <strong>Note:</strong> This method tries to preserve the files' last
* modified date/times using {@link File#setLastModified(long)}, however
* it is not guaranteed that those operations will succeed.
* If the modification operation fails, no indication is provided.
+ * </p>
*
* @param srcDir an existing directory to copy, must not be {@code null}
* @param destDir the new directory, must not be {@code null}
@@ -1227,16 +1263,19 @@ public class FileUtils {
* <p>
* This method copies the contents of the specified source directory
* to within the specified destination directory.
+ * </p>
* <p>
* The destination directory is created if it does not exist.
* If the destination directory did exist, then this method merges
* the source with the destination, with the source taking precedence.
+ * </p>
* <p>
* <strong>Note:</strong> Setting <code>preserveFileDate</code> to
* {@code true} tries to preserve the files' last modified
* date/times using {@link File#setLastModified(long)}, however it is
* not guaranteed that those operations will succeed.
* If the modification operation fails, no indication is provided.
+ * </p>
*
* @param srcDir an existing directory to copy, must not be {@code null}
* @param destDir the new directory, must not be {@code null}
@@ -1258,10 +1297,12 @@ public class FileUtils {
* <p>
* This method copies the contents of the specified source directory
* to within the specified destination directory.
+ * </p>
* <p>
* The destination directory is created if it does not exist.
* If the destination directory did exist, then this method merges
* the source with the destination, with the source taking precedence.
+ * </p>
* <p>
* <strong>Note:</strong> This method tries to preserve the files' last
* modified date/times using {@link File#setLastModified(long)}, however
@@ -1307,10 +1348,12 @@ public class FileUtils {
* <p>
* This method copies the contents of the specified source directory
* to within the specified destination directory.
+ * </p>
* <p>
* The destination directory is created if it does not exist.
* If the destination directory did exist, then this method merges
* the source with the destination, with the source taking precedence.
+ * </p>
* <p>
* <strong>Note:</strong> Setting <code>preserveFileDate</code> to
* {@code true} tries to preserve the files' last modified
@@ -1374,7 +1417,8 @@ public class FileUtils {
}
/**
- * checks requirements for file copy
+ * Checks requirements for file copy.
+ *
* @param src the source file
* @param dest the destination
* @throws FileNotFoundException if the destination does not exist
@@ -1449,6 +1493,7 @@ public class FileUtils {
* Warning: this method does not set a connection or read timeout and thus
* might block forever. Use {@link #copyURLToFile(URL, File, int, int)}
* with reasonable timeouts to prevent this.
+ * </p>
*
* @param source the <code>URL</code> to copy bytes from, must not be {@code null}
* @param destination the non-directory <code>File</code> to write bytes to
@@ -1542,15 +1587,18 @@ public class FileUtils {
* <p>
* This method copies the source file or directory, along all its contents, to a
* directory of the same name in the specified destination directory.
+ * </p>
* <p>
* The destination directory is created if it does not exist.
* If the destination directory did exist, then this method merges
* the source with the destination, with the source taking precedence.
+ * </p>
* <p>
* <strong>Note:</strong> This method tries to preserve the files' last
* modified date/times using {@link File#setLastModified(long)}, however
* it is not guaranteed that those operations will succeed.
* If the modification operation fails, no indication is provided.
+ * </p>
*
* @param src an existing file or directory to copy, must not be {@code null}
* @param destDir the directory to place the copy in, must not be {@code null}
@@ -1582,11 +1630,13 @@ public class FileUtils {
* to a file of the same name in the specified destination directory.
* The destination directory is created if it does not exist.
* If the destination file exists, then this method will overwrite it.
+ * </p>
* <p>
* <strong>Note:</strong> This method tries to preserve the file's last
* modified date/times using {@link File#setLastModified(long)}, however
* it is not guaranteed that the operation will succeed.
* If the modification operation fails, no indication is provided.
+ * </p>
*
* @param srcs a existing files to copy, must not be {@code null}
* @param destDir the directory to place the copy in, must not be {@code null}
@@ -1634,6 +1684,7 @@ public class FileUtils {
* Deletes a file, never throwing an exception. If file is a directory, delete it and all sub-directories.
* <p>
* The difference between File.delete() and this method are:
+ * </p>
* <ul>
* <li>A directory to be deleted does not have to be empty.</li>
* <li>No exceptions are thrown when a file or directory cannot be deleted.</li>
@@ -1737,7 +1788,8 @@ public class FileUtils {
}
/**
- * Lists files in a directory, asserting that the supplied directory satisfies exists and is a directory
+ * Lists files in a directory, asserting that the supplied directory satisfies exists and is a directory.
+ *
* @param directory The directory to list
* @return The files in the directory, never null.
* @throws IOException if an I/O error occurs
@@ -1766,6 +1818,7 @@ public class FileUtils {
* <p>
* This method repeatedly tests {@link File#exists()} until it returns
* true up to the maximum time specified in seconds.
+ * </p>
*
* @param file the file to check, must not be {@code null}
* @param seconds the maximum time in seconds to wait
@@ -1916,8 +1969,10 @@ public class FileUtils {
* to free internal resources. This can be done by calling the
* {@link LineIterator#close()} or
* {@link LineIterator#closeQuietly(LineIterator)} method.
+ * </p>
* <p>
* The recommended usage pattern is:
+ * </p>
* <pre>
* LineIterator it = FileUtils.lineIterator(file, "UTF-8");
* try {
@@ -1932,6 +1987,7 @@ public class FileUtils {
* <p>
* If an exception occurs during the creation of the iterator, the
* underlying stream is closed.
+ * </p>
*
* @param file the file to open for input, must not be {@code null}
* @param encoding the encoding to use, {@code null} means platform default
@@ -1977,6 +2033,7 @@ public class FileUtils {
* <p>
* NOTE: As from v1.3, the parent directories of the file will be created
* if they do not exist.
+ * </p>
*
* @param file the file to write
* @param data the content to write to the file
@@ -1995,6 +2052,7 @@ public class FileUtils {
* <p>
* NOTE: As from v1.3, the parent directories of the file will be created
* if they do not exist.
+ * </p>
*
* @param file the file to write
* @param data the content to write to the file
@@ -2168,6 +2226,7 @@ public class FileUtils {
* <p>
* NOTE: As from v1.3, the parent directories of the file will be created
* if they do not exist.
+ * </p>
*
* @param file the file to write to
* @param data the content to write to the file
@@ -2238,6 +2297,7 @@ public class FileUtils {
* <p>
* NOTE: As from v1.3, the parent directories of the file will be created
* if they do not exist.
+ * </p>
*
* @param file the file to write to
* @param encoding the encoding to use, {@code null} means platform default
@@ -2307,6 +2367,7 @@ public class FileUtils {
* <p>
* NOTE: As from v1.3, the parent directories of the file will be created
* if they do not exist.
+ * </p>
*
* @param file the file to write to
* @param encoding the encoding to use, {@code null} means platform default
@@ -2382,6 +2443,7 @@ public class FileUtils {
* Deletes a file. If file is a directory, delete it and all sub-directories.
* <p>
* The difference between File.delete() and this method are:
+ * </p>
* <ul>
* <li>A directory to be deleted does not have to be empty.</li>
* <li>You get exceptions when a file or directory cannot be deleted.
@@ -2529,6 +2591,7 @@ public class FileUtils {
* Note that overflow is not detected, and the return value may be negative if
* overflow occurs. See {@link #sizeOfAsBigInteger(File)} for an alternative
* method that does not overflow.
+ * </p>
*
* @param file the regular file or directory to return the size
* of (must not be {@code null}).
@@ -2593,6 +2656,7 @@ public class FileUtils {
* Note that overflow is not detected, and the return value may be negative if
* overflow occurs. See {@link #sizeOfDirectoryAsBigInteger(File)} for an alternative
* method that does not overflow.
+ * </p>
*
* @param directory directory to inspect, must not be {@code null}
* @return size of directory in bytes, 0 if directory is security restricted, a negative number when the real total
@@ -2900,6 +2964,7 @@ public class FileUtils {
* Moves a directory.
* <p>
* When the destination directory is on another file system, do a "copy and delete".
+ * </p>
*
* @param srcDir the directory to be moved
* @param destDir the destination directory
@@ -2964,6 +3029,7 @@ public class FileUtils {
* Moves a file.
* <p>
* When the destination file is on another file system, do a "copy and delete".
+ * </p>
*
* @param srcFile the file to be moved
* @param destFile the destination file
@@ -3028,6 +3094,7 @@ public class FileUtils {
* Moves a file or directory to the destination directory.
* <p>
* When the destination is on another file system, do a "copy and delete".
+ * </p>
*
* @param src the file or directory to be moved
* @param destDir the destination directory
@@ -3078,14 +3145,19 @@ public class FileUtils {
* <p>
* Will not return true if there is a Symbolic Link anywhere in the path,
* only if the specific file is.
+ * </p>
* <p>
* When using jdk1.7, this method delegates to {@code boolean java.nio.file.Files.isSymbolicLink(Path path)}
+ * </p>
*
+ * <p>
* <b>Note:</b> the current implementation always returns {@code false} if running on
* jkd1.6 and the system is detected as Windows using {@link FilenameUtils#isSystemWindows()}
+ * </p>
* <p>
* For code that runs on Java 1.7 or later, use the following method instead:
- * <br>
+ * </p>
+ *
* {@code boolean java.nio.file.Files.isSymbolicLink(Path path)}
* @param file the file to check
* @return true if the file is a Symbolic Link