Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8202302

(fs) New Files.mismatch method for comparing files

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P4
    • Resolution: Approved
    • Fix Version/s: 12
    • Component/s: core-libs
    • Labels:
      None
    • Subcomponent:
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      No compatibility risk. The proposed change defines a new static method.
    • Interface Kind:
      Java API
    • Scope:
      SE

      Description

      Summary

      Add a mismatch method to java.nio.file.Files for comparing two files.

      Problem

      NIO Files contains a method isSameFile for testing whether two files are the same object or locate the same file. However, the question about whether two files are equal requires a comparison of their contents.

      Solution

      Add a mismatch method to compare the contents of two files to determine whether there is a mismatch between them. The method is similar (and consistent) with the Arrays.mismatch and Buffer.mismatch methods.

      Specification

      Below is a summary of the proposed changes. The specdiff is attached, and can also be viewed at: http://cr.openjdk.java.net/~joehw/jdk12/8202285/specdiff_v04/java/nio/file/Files.html

      • java.nio.file.Files

      public static long mismatch(Path path, Path path2) throws IOException

      Finds and returns the position of the first mismatched byte in the content of two files, or -1L if there is no mismatch. The position will be in the inclusive range of 0L up to the size (in bytes) of the smaller file.

      Two files are considered to match if they satisfy one of the following conditions:

      • The two paths locate the same file, even if two equal paths locate a file does not exist, or
      • The two files are the same size, and every byte in the first file is identical to the corresponding byte in the second file.

      Otherwise there is a mismatch between the two files and the value returned by this method is:

      • The position of the first mismatched byte, or
      • The size of the smaller file (in bytes) when the files are different sizes and every byte of the smaller file is identical to the corresponding byte of the larger file.

      This method may not be atomic with respect to other file system operations. This method is always reflexive (for Path f , mismatch(f,f) returns -1L). If the file system and files remain static, then this method is symmetric (for two Paths f and g, mismatch(f,g) will return the same value as mismatch(g,f)).

      Parameters:

      path - the path to the first file
      path2 - the path to the second file

      Returns:

      the position of the first mismatch or -1L if no mismatch

      Throws:

      IOException - if an I/O error occurs
      java.lang.SecurityException - In the case of the default provider, and a security manager is installed, the checkRead method is invoked to check read access to both files.

      Since: 12

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                joehw Joe Wang
                Reporter:
                joehw Joe Wang
                Reviewed By:
                Alan Bateman, Roger Riggs, Stuart Marks
              • Votes:
                0 Vote for this issue
                Watchers:
                3 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: