(fs) New Files.mismatch method for comparing files

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