IO-383 FileUtils.doCopyFile caches the file size; needs to be documented

sebbASF · sebbASF · commit 7f15b0e5cdb5 · 2013-06-02T13:17:02.000Z
git-svn-id: https://svn.apache.org/repos/asf/commons/proper/io/trunk@1488708 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/src/changes/changes.xml b/src/changes/changes.xml
@@ -47,6 +47,10 @@ The <action> type attribute can be add,update,fix,remove.
   <body>
     <!-- The release date is the date RC is cut -->
     <release version="2.5" date="2013-??-??" description="New features and bug fixes.">    
+      <action issue="IO-383" dev="sebb" type="fix">
+         FileUtils.doCopyFile caches the file size; needs to be documented
+         Added Javadoc; show file lengths in exception message
+      </action>
       <action issue="IO-239" dev="sebb" type="update">
          Convert IOCase to a Java 1.5+ Enumeration
          [N.B. this is binary compatible]
diff --git a/src/main/java/org/apache/commons/io/FileUtils.java b/src/main/java/org/apache/commons/io/FileUtils.java
@@ -996,6 +996,7 @@ public static void copyFileToDirectory(final File srcFile, final File destDir) t
      * @throws NullPointerException if source or destination is {@code null}
      * @throws IOException if source or destination is invalid
      * @throws IOException if an IO error occurs during copying
+     * @throws IOException if the output file length is not the same as the input file length after the copy completes
      * @see #copyFile(File, File, boolean)
      * @since 1.3
      */
@@ -1029,7 +1030,9 @@ public static void copyFileToDirectory(final File srcFile, final File destDir, f
      * @throws NullPointerException if source or destination is {@code null}
      * @throws IOException if source or destination is invalid
      * @throws IOException if an IO error occurs during copying
+     * @throws IOException if the output file length is not the same as the input file length after the copy completes
      * @see #copyFileToDirectory(File, File)
+     * @see #copyFile(File, File, boolean)
      */
     public static void copyFile(final File srcFile, final File destFile) throws IOException {
         copyFile(srcFile, destFile, true);
@@ -1057,7 +1060,9 @@ public static void copyFile(final File srcFile, final File destFile) throws IOEx
      * @throws NullPointerException if source or destination is {@code null}
      * @throws IOException if source or destination is invalid
      * @throws IOException if an IO error occurs during copying
+     * @throws IOException if the output file length is not the same as the input file length after the copy completes
      * @see #copyFileToDirectory(File, File, boolean)
+     * @see #doCopyFile(File, File, boolean)
      */
     public static void copyFile(final File srcFile, final File destFile,
             final boolean preserveFileDate) throws IOException {
@@ -1116,11 +1121,15 @@ public static long copyFile(final File input, final OutputStream output) throws
 
     /**
      * Internal copy file method.
+     * This caches the original file length, and throws an IOException 
+     * if the output file length is different from the current input file length.
+     * So it may fail if the file changes size. 
      *
      * @param srcFile  the validated source file, must not be {@code null}
      * @param destFile  the validated destination file, must not be {@code null}
      * @param preserveFileDate  whether to preserve the file date
      * @throws IOException if an error occurs
+     * @throws IOException if the output file length is not the same as the input file length after the copy completes
      */
     private static void doCopyFile(final File srcFile, final File destFile, final boolean preserveFileDate) throws IOException {
         if (destFile.exists() && destFile.isDirectory()) {
@@ -1150,9 +1159,11 @@ private static void doCopyFile(final File srcFile, final File destFile, final bo
             IOUtils.closeQuietly(fis);
         }
 
-        if (srcFile.length() != destFile.length()) {
+        final long srcLen = srcFile.length();
+        final long dstLen = destFile.length();
+        if (srcLen != dstLen) {
             throw new IOException("Failed to copy full contents from '" +
-                    srcFile + "' to '" + destFile + "'");
+                    srcFile + "' to '" + destFile + "' Expected length: " + srcLen +" Actual: " + dstLen);
         }
         if (preserveFileDate) {
             destFile.setLastModified(srcFile.lastModified());
