You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by sc...@apache.org on 2006/01/01 17:59:00 UTC
svn commit: r360497 -
/jakarta/commons/proper/io/trunk/src/java/org/apache/commons/io/FileUtils.java
Author: scolebourne
Date: Sun Jan 1 08:58:56 2006
New Revision: 360497
URL: http://svn.apache.org/viewcvs?rev=360497&view=rev
Log:
Stylistic change only to make the whole file have one style
Modified:
jakarta/commons/proper/io/trunk/src/java/org/apache/commons/io/FileUtils.java
Modified: jakarta/commons/proper/io/trunk/src/java/org/apache/commons/io/FileUtils.java
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/io/trunk/src/java/org/apache/commons/io/FileUtils.java?rev=360497&r1=360496&r2=360497&view=diff
==============================================================================
--- jakarta/commons/proper/io/trunk/src/java/org/apache/commons/io/FileUtils.java (original)
+++ jakarta/commons/proper/io/trunk/src/java/org/apache/commons/io/FileUtils.java Sun Jan 1 08:58:56 2006
@@ -98,13 +98,13 @@
*/
public static final File[] EMPTY_FILE_ARRAY = new File[0];
+ //-----------------------------------------------------------------------
/**
- * Returns a human-readable version of the file size (original is in
- * bytes).
+ * Returns a human-readable version of the file size, where the input
+ * represents a specific number of bytes.
*
- * @param size The number of bytes.
- * @return A human-readable display value (includes units).
- * @todo need for I18N?
+ * @param size the number of bytes
+ * @return a human-readable display value (includes units)
*/
public static String byteCountToDisplaySize(long size) {
String displaySize;
@@ -118,16 +118,16 @@
} else {
displaySize = String.valueOf(size) + " bytes";
}
-
return displaySize;
}
-
+ //-----------------------------------------------------------------------
/**
* Implements the same behaviour as the "touch" utility on Unix. It creates
* a new file with size 0 or, if the file exists already, it is opened and
* closed without modifying it, but updating the file date and time.
- * @param file the File to touch
+ *
+ * @param file the File to touch
* @throws IOException If an I/O problem occurs
*/
public static void touch(File file) throws IOException {
@@ -138,10 +138,24 @@
file.setLastModified(System.currentTimeMillis());
}
+ //-----------------------------------------------------------------------
+ /**
+ * Converts a Collection containing java.io.File instanced into array
+ * representation. This is to account for the difference between
+ * File.listFiles() and FileUtils.listFiles().
+ *
+ * @param files a Collection containing java.io.File instances
+ * @return an array of java.io.File
+ */
+ public static File[] convertFileCollectionToFileArray(Collection files) {
+ return (File[]) files.toArray(new File[files.size()]);
+ }
+ //-----------------------------------------------------------------------
/**
- * <p>Finds files within a given directory (and optionally its
- * subdirectories). All files found are filtered by an IOFileFilter.</p>
+ * Finds files within a given directory (and optionally its
+ * subdirectories). All files found are filtered by an IOFileFilter.
+ *
* @param files the collection of files found.
* @param directory the directory to search in.
* @param filter the filter to apply to files and directories.
@@ -160,46 +174,33 @@
}
}
-
/**
- * Converts a Collection containing java.io.File instanced into array
- * representation. This is to account for the difference between
- * File.listFiles() and FileUtils.listFiles().
- * @param files a Collection containing java.io.File instances
- * @return an array of java.io.File
- */
- public static File[] convertFileCollectionToFileArray(Collection files) {
- return (File[]) files.toArray(new File[files.size()]);
- }
-
-
- /**
- * <p>Finds files within a given directory (and optionally its
+ * Finds files within a given directory (and optionally its
* subdirectories). All files found are filtered by an IOFileFilter.
- * </p>
- * <p>If your search should recurse into subdirectories you can pass in
+ * <p>
+ * If your search should recurse into subdirectories you can pass in
* 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
+ * <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
+ * <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.
- * @param dirFilter optional filter to apply when finding subdirectories.
+ *
+ * @param directory the directory to search in
+ * @param fileFilter filter to apply when finding files.
+ * @param dirFilter optional filter to apply when finding subdirectories.
* If this parameter is null, subdirectories will not be included in the
* search. Use TrueFileFilter.INSTANCE to match all directories.
* @return an collection of java.io.File with the matching files
* @see org.apache.commons.io.filefilter.FileFilterUtils
* @see org.apache.commons.io.filefilter.NameFileFilter
*/
- public static Collection listFiles(File directory, IOFileFilter fileFilter,
- IOFileFilter dirFilter) {
+ public static Collection listFiles(
+ File directory, IOFileFilter fileFilter, IOFileFilter dirFilter) {
if (!directory.isDirectory()) {
throw new IllegalArgumentException(
"Parameter 'directory' is not a directory");
@@ -229,10 +230,11 @@
}
/**
- * <p>Allows iteration over the files in given directory (and optionally
- * its subdirectories). All files found are filtered by an IOFileFilter.
- * This method is based on {@link #listFiles(File, IOFileFilter, IOFileFilter)}.
- * </p>
+ * Allows iteration over the files in given directory (and optionally
+ * its subdirectories).
+ * <p>
+ * All files found are filtered by an IOFileFilter. This method is
+ * based on {@link #listFiles(File, IOFileFilter, IOFileFilter)}.
*
* @param directory the directory to search in
* @param fileFilter filter to apply when finding files.
@@ -249,10 +251,12 @@
return listFiles(directory, fileFilter, dirFilter).iterator();
}
+ //-----------------------------------------------------------------------
/**
* Converts an array of file extensions to suffixes for use
* with IOFileFilters.
- * @param extensions an array of extensions. Format: {"java", "xml"}
+ *
+ * @param extensions an array of extensions. Format: {"java", "xml"}
* @return an array of suffixes. Format: {".java", ".xml"}
*/
private static String[] toSuffixes(String[] extensions) {
@@ -267,10 +271,11 @@
/**
* Finds files within a given directory (and optionally its subdirectories)
* which match an array of extensions.
- * @param directory the directory to search in
- * @param extensions an array of extensions, ex. {"java","xml"}. If this
+ *
+ * @param directory the directory to search in
+ * @param extensions an array of extensions, ex. {"java","xml"}. If this
* parameter is null, all files are returned.
- * @param recursive If true all subdirectories are searched, too.
+ * @param recursive if true all subdirectories are searched as well
* @return an collection of java.io.File with the matching files
*/
public static Collection listFiles(
@@ -303,24 +308,23 @@
return listFiles(directory, extensions, recursive).iterator();
}
+ //-----------------------------------------------------------------------
/**
- * <p>Compare the contents of two files to determine if they are equal or
- * not.</p>
- *
- * <p>This method checks to see if the two files are different lengths
+ * Compare the contents of two files to determine if they are equal or not.
+ * <p>
+ * 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>
+ * comparison of the contents.
+ * <p>
+ * Code origin: Avalon
*
- * @param file1 the first file
- * @param file2 the second file
+ * @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 IOException in case of an I/O error
*/
- public static boolean contentEquals(File file1, File file2)
- throws IOException {
+ public static boolean contentEquals(File file1, File file2) throws IOException {
boolean file1Exists = file1.exists();
if (file1Exists != file2.exists()) {
return false;
@@ -690,8 +694,7 @@
* <li>an IO error occurs during copying</li>
* </ul>
*/
- public static void copyURLToFile(URL source, File destination)
- throws IOException {
+ public static void copyURLToFile(URL source, File destination) throws IOException {
//does destination directory exist ?
if (destination.getParentFile() != null
&& !destination.getParentFile().exists()) {
@@ -721,7 +724,8 @@
//-----------------------------------------------------------------------
/**
* Recursively delete a directory.
- * @param directory directory to delete
+ *
+ * @param directory directory to delete
* @throws IOException in case deletion is unsuccessful
*/
public static void deleteDirectory(File directory)
@@ -740,6 +744,7 @@
/**
* Clean a directory without deleting it.
+ *
* @param directory directory to clean
* @throws IOException in case cleaning is unsuccessful
*/
@@ -774,14 +779,17 @@
}
}
+ //-----------------------------------------------------------------------
/**
* Waits for NFS to propagate a file creation, imposing a timeout.
+ * <p>
+ * This method repeatedly tests {@link File#exists()} until it returns
+ * true up to the maximum time specified in seconds.
*
- * @param file The file
- * @param seconds The maximum time in seconds to wait.
- * @return True if file exists.
- * @todo Needs a clearer javadoc to see its real purpose for someone without
- * NFS-knowledge.
+ * @param file the file to check, not null
+ * @param seconds the maximum time in seconds to wait
+ * @return true if file exists
+ * @throws NullPointerException if the file is null
*/
public static boolean waitFor(File file, int seconds) {
int timeout = 0;
@@ -806,18 +814,15 @@
//-----------------------------------------------------------------------
/**
- * <p>
* Reads the contents of a file into a String.
- * </p>
* <p>
* There is no readFileToString method without encoding parameter because
* the default encoding can differ between platforms and therefore results
* in inconsistent results.
- * </p>
*
* @param file the file to read
* @param encoding the encoding to use, null means platform default
- * @return The file contents or null if read failed.
+ * @return the file contents or null if read failed
* @throws IOException in case of an I/O error
* @throws UnsupportedEncodingException if the encoding is not supported by the VM
*/
@@ -832,12 +837,10 @@
}
/**
- * <p>
* Reads the contents of a file into a byte array.
- * </p>
*
* @param file the file to read
- * @return The file contents or null if read failed.
+ * @return the file contents or null if read failed
* @throws IOException in case of an I/O error
* @since Commons IO 1.1
*/
@@ -851,14 +854,11 @@
}
/**
- * <p>
* Reads the contents of a file line by line to a List of Strings.
- * </p>
* <p>
* There is no readLines method without encoding parameter because
* the default encoding can differ between platforms and therefore results
* in inconsistent results.
- * </p>
*
* @param file the file to read
* @param encoding the encoding to use, null means platform default
@@ -878,14 +878,11 @@
//-----------------------------------------------------------------------
/**
- * <p>
* Writes a String to a file creating the file if it does not exist.
- * </p>
* <p>
* There is no writeStringToFile method without encoding parameter because
* the default encoding can differ between platforms and therefore results
* in inconsistent results.
- * </p>
*
* @param file the file to write
* @param data the content to write to the file
@@ -904,9 +901,7 @@
}
/**
- * <p>
* Writes a byte array to a file creating the file if it does not exist.
- * </p>
*
* @param file the file to write to
* @param data the content to write to the file
@@ -924,16 +919,13 @@
}
/**
- * <p>
* Writes the <code>toString()</code> value of each item in a collection to
* the specified <code>File</code> line by line.
* The specified character encoding and the default line ending will be used.
- * </p>
* <p>
* There is no writeLines method without encoding parameter because
* the default encoding can differ between platforms and therefore results
* in inconsistent results.
- * </p>
*
* @param file the file to write to
* @param encoding the encoding to use, null means platform default
@@ -947,16 +939,13 @@
}
/**
- * <p>
* Writes the <code>toString()</code> value of each item in a collection to
* the specified <code>File</code> line by line.
* The specified character encoding and the line ending will be used.
- * </p>
* <p>
* There is no writeLines method without encoding parameter because
* the default encoding can differ between platforms and therefore results
* in inconsistent results.
- * </p>
*
* @param file the file to write to
* @param encoding the encoding to use, null means platform default
@@ -977,18 +966,17 @@
//-----------------------------------------------------------------------
/**
- * <p>
* Delete a file. If file is a directory, delete it and all sub-directories.
- * </p>
* <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.
* (java.io.File methods returns a boolean)</li>
* </ul>
- * @param file file or directory to delete.
+ *
+ * @param file file or directory to delete, not null
+ * @throws NullPointerException if the directory is null
* @throws IOException in case deletion is unsuccessful
*/
public static void forceDelete(File file) throws IOException {
@@ -1009,7 +997,9 @@
/**
* Schedule a file to be deleted when JVM exits.
* If file is directory delete it and all sub-directories.
- * @param file file or directory to delete.
+ *
+ * @param file file or directory to delete, not null
+ * @throws NullPointerException if the file is null
* @throws IOException in case deletion is unsuccessful
*/
public static void forceDeleteOnExit(File file) throws IOException {
@@ -1022,11 +1012,12 @@
/**
* Recursively schedule directory for deletion on JVM exit.
- * @param directory directory to delete.
+ *
+ * @param directory directory to delete, not null
+ * @throws NullPointerException if the directory is null
* @throws IOException in case deletion is unsuccessful
*/
- private static void deleteDirectoryOnExit(File directory)
- throws IOException {
+ private static void deleteDirectoryOnExit(File directory) throws IOException {
if (!directory.exists()) {
return;
}
@@ -1037,7 +1028,9 @@
/**
* Clean a directory without deleting it.
- * @param directory directory to clean.
+ *
+ * @param directory directory to clean, not null
+ * @throws NullPointerException if the directory is null
* @throws IOException in case cleaning is unsuccessful
*/
private static void cleanDirectoryOnExit(File directory) throws IOException {
@@ -1071,14 +1064,14 @@
}
}
-
/**
* Make a directory, including any necessary but nonexistent parent
* directories. If there already exists a file with specified name or
* the directory cannot be created then an exception is thrown.
*
- * @param directory directory to create
- * @throws IOException if the directory cannot be created.
+ * @param directory directory to create, not null
+ * @throws NullPointerException if the directory is null
+ * @throws IOException if the directory cannot be created
*/
public static void forceMkdir(File directory) throws IOException {
if (directory.exists()) {
@@ -1099,11 +1092,13 @@
}
}
+ //-----------------------------------------------------------------------
/**
* Recursively count size of a directory (sum of the length of all files).
*
- * @param directory directory to inspect
+ * @param directory directory to inspect, not null
* @return size of directory in bytes, 0 if directory is security restricted
+ * @throws NullPointerException if the directory is null
*/
public static long sizeOfDirectory(File directory) {
if (!directory.exists()) {
@@ -1135,66 +1130,70 @@
return size;
}
- /**
- * Tests if the specified <code>File</code> is newer than the reference
- * <code>File</code>.
- *
- * @param file the <code>File</code> of which the modification date must
- * be compared.
- * @param reference the <code>File</code> of which the modification date
- * is used.
- * @return true if the <code>File</code> exists and has been modified more
- * recently than the reference <code>File</code>.
- */
+ //-----------------------------------------------------------------------
+ /**
+ * Tests if the specified <code>File</code> is newer than the reference
+ * <code>File</code>.
+ *
+ * @param file the <code>File</code> of which the modification date must
+ * be compared, not null
+ * @param reference the <code>File</code> of which the modification date
+ * is used, not null
+ * @return true if the <code>File</code> exists and has been modified more
+ * recently than the reference <code>File</code>
+ * @throws IllegalArgumentException if the file is null
+ * @throws IllegalArgumentException if the reference file is null or doesn't exist
+ */
public static boolean isFileNewer(File file, File reference) {
- if (reference == null) {
- throw new IllegalArgumentException("No specified reference file");
- }
- if (!reference.exists()) {
- throw new IllegalArgumentException(
- "The reference file '" + file + "' doesn't exist");
- }
-
- return isFileNewer(file, reference.lastModified());
- }
-
- /**
- * Tests if the specified <code>File</code> is newer than the specified
- * <code>Date</code>.
- *
- * @param file the <code>File</code> of which the modification date must be
- * compared.
- * @param date the date reference
- * @return true if the <code>File</code> exists and has been modified after
- * the given <code>Date</code>.
- */
- public static boolean isFileNewer(File file, Date date) {
- if (date == null) {
- throw new IllegalArgumentException("No specified date");
- }
- return isFileNewer(file, date.getTime());
- }
-
- /**
- * Tests if the specified <code>File</code> is newer than the specified
- * time reference.
- *
- * @param file the <code>File</code> of which the modification date must
- * be compared.
- * @param timeMillis the time reference measured in milliseconds since the
- * epoch (00:00:00 GMT, January 1, 1970)
- * @return true if the <code>File</code> exists and has been modified after
- * the given time reference.
- */
- public static boolean isFileNewer(File file, long timeMillis) {
- if (file == null) {
- throw new IllegalArgumentException("No specified file");
- }
- if (!file.exists()) {
- return false;
- }
+ if (reference == null) {
+ throw new IllegalArgumentException("No specified reference file");
+ }
+ if (!reference.exists()) {
+ throw new IllegalArgumentException("The reference file '"
+ + file + "' doesn't exist");
+ }
+ return isFileNewer(file, reference.lastModified());
+ }
- return file.lastModified() > timeMillis;
+ /**
+ * Tests if the specified <code>File</code> is newer than the specified
+ * <code>Date</code>.
+ *
+ * @param file the <code>File</code> of which the modification date
+ * must be compared, not null
+ * @param date the date reference, not null
+ * @return true if the <code>File</code> exists and has been modified
+ * after the given <code>Date</code>.
+ * @throws IllegalArgumentException if the file is null
+ * @throws IllegalArgumentException if the date is null
+ */
+ public static boolean isFileNewer(File file, Date date) {
+ if (date == null) {
+ throw new IllegalArgumentException("No specified date");
+ }
+ return isFileNewer(file, date.getTime());
+ }
+
+ /**
+ * Tests if the specified <code>File</code> is newer than the specified
+ * time reference.
+ *
+ * @param file the <code>File</code> of which the modification date must
+ * be compared, not null
+ * @param timeMillis the time reference measured in milliseconds since the
+ * epoch (00:00:00 GMT, January 1, 1970)
+ * @return true if the <code>File</code> exists and has been modified after
+ * the given time reference.
+ * @throws IllegalArgumentException if the file is null
+ */
+ public static boolean isFileNewer(File file, long timeMillis) {
+ if (file == null) {
+ throw new IllegalArgumentException("No specified file");
+ }
+ if (!file.exists()) {
+ return false;
+ }
+ return file.lastModified() > timeMillis;
}
}
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org