JDK-8283336 : Add exists and readAttributesIfExists methods to FileSystemProvider
  • Type: CSR
  • Component: core-libs
  • Sub-Component: java.nio
  • Priority: P4
  • Status: Closed
  • Resolution: Approved
  • Fix Versions: 20
  • Submitted: 2022-03-17
  • Updated: 2022-06-24
  • Resolved: 2022-06-24
Related Reports
CSR :  
Description
Summary
-------

Enhance the java.nio.file.spi.FileSystemProvider abstract class to include the methods 

 - `public boolean exists(Path path, LinkOption... options)`
 - `public <A extends BasicFileAttributes> A readAttributesIfExists(Path path,
                                                                    Class<A> type,
                                                                    LinkOption... options)`

Problem
-------
AbstractFileSystemProvider includes the methods exists(Path), isDirectory(Path), and isRegularFile(Path) which are used by some FilesystemProviders (for example UnixFilesystemProvider) to improve performance by avoid reading a file's attributes when not needed.

As AbstractFileSystemProvider includes methods that are not needed by every FileSystemProvider, it is not well suited to be used by every FileSystemProvider, including the ZipFileSystemProvider.

Solution
--------

Add  the following  non-abstract methods to  the FileSystemProvider abstract class:

 - public boolean exists(Path path, LinkOption... options); 
 - public <A extends BasicFileAttributes> A readAttributesIfExists(Path path,
                                                                    Class<A> type,
                                                                    LinkOption... options)

With this change,  FileSystemProviders can provide optimized implementations for the above methods and avoid reading the file's attributes when not needed and also  avoid the need to throw and catch an Exception when the specified Path does not exist.

Specification
-------------

The following javadoc will be added to FileSystemProvider:


    /**
     * Tests whether a file exists. This method works in exactly the
     * manner specified by the {@link Files#exists(Path, LinkOption...)} method.
     *
     * @implSpec
     * The default implementation of this method invokes the
     * {@link #checkAccess(Path, AccessMode...)} method when symbolic links
     * are followed. If the option {@link LinkOption#NOFOLLOW_LINKS NOFOLLOW_LINKS}
     * is present then symbolic links are not followed and the method
     *  {@link #readAttributes(Path, Class, LinkOption...)} is called
     *  to determine whether a file exists.
     *
     * @param   path
     *          the path to the file to test
     * @param   options
     *          options indicating how symbolic links are handled
     *
     * @return  {@code true} if the file exists; {@code false} if the file does
     *          not exist or its existence cannot be determined.
     *
     * @throws  SecurityException
     *          In the case of the default provider, the {@link
     *          SecurityManager#checkRead(String)} is invoked to check
     *          read access to the file.
     *
     * @since 20
     */
    public boolean exists(Path path, LinkOption... options) 


    /**
     * Reads a file's attributes as a bulk operation if it exists.
     *
     * <p> The {@code type} parameter is the type of the attributes required
     * and this method returns an instance of that type if supported. All
     * implementations support a basic set of file attributes and so invoking
     * this method with a  {@code type} parameter of {@code
     * BasicFileAttributes.class} will not throw {@code
     * UnsupportedOperationException}.
     *
     * <p> The {@code options} array may be used to indicate how symbolic links
     * are handled for the case that the file is a symbolic link. By default,
     * symbolic links are followed and the file attribute of the final target
     * of the link is read. If the option {@link LinkOption#NOFOLLOW_LINKS
     * NOFOLLOW_LINKS} is present then symbolic links are not followed.
     *
     * <p> It is implementation specific if all file attributes are read as an
     * atomic operation with respect to other file system operations.
     *
     * @implSpec
     * The default implementation of this method invokes the
     * {@link #readAttributes(Path, Class, LinkOption...)} method
     * to read the file's attributes.
     *
     * @param   <A>
     *          The {@code BasicFileAttributes} type
     * @param   path
     *          the path to the file
     * @param   type
     *          the {@code Class} of the file attributes required
     *          to read
     * @param   options
     *          options indicating how symbolic links are handled
     *
     * @return  the file attributes or null if the file does not exist
     *
     * @throws  UnsupportedOperationException
     *          if an attributes of the given type are not supported
     * @throws  IOException
     *          if an I/O error occurs
     * @throws  SecurityException
     *          In the case of the default provider, a security manager is
     *          installed, its {@link SecurityManager#checkRead(String) checkRead}
     *          method is invoked to check read access to the file. If this
     *          method is invoked to read security sensitive attributes then the
     *          security manager may be invoked to check for additional permissions.
     *
     * @since 20
     */
    public <A extends BasicFileAttributes> A readAttributesIfExists(Path path,
                                                                    Class<A> type,
                                                                    LinkOption... options)
        throws IOException
    

Comments
Moving updated request to Approved.
24-06-2022

The implSpec has been in all revisions that I've seen, and in the patch, so must have been an error when pasting it into the CSR.
23-06-2022

Not sure how the `@ImplSpec` was missing as it was there, but have been inadvertently removed in cleanup. Added it back
23-06-2022

Moving to Provisional, not Approved. Should readAttributesIfExists have an implSpec description?
23-06-2022