Package software.amazon.nio.spi.s3

Class S3FileSystemProvider

  • Direct Known Subclasses:
    S3XFileSystemProvider
    public class S3FileSystemProvider
extends java.nio.file.spi.FileSystemProvider
    Service-provider class for S3 when represented as an NIO filesystem. The methods defined by the Files class will delegate to an instance of this class when referring to an object in S3. This class will in turn make calls to the S3 service.
    This class should never be used directly. It is invoked by the service loader when, for example, the java.nio.file.Files class is used to address an object beginning with the scheme "s3".

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void checkAccess​(java.nio.file.Path path, java.nio.file.AccessMode... modes)
      Checks the existence, and optionally the accessibility, of a file.
      void copy​(java.nio.file.Path source, java.nio.file.Path target, java.nio.file.CopyOption... options)
      Copy a file to a target file.
      void createDirectory​(java.nio.file.Path dir, java.nio.file.attribute.FileAttribute<?>... attrs)
      Creates a new directory.
      void delete​(java.nio.file.Path path)
      Deletes a file.
      <V extends java.nio.file.attribute.FileAttributeView>
      V      		 getFileAttributeView​(java.nio.file.Path path, java.lang.Class<V> type, java.nio.file.LinkOption... options)
      Returns a file attribute view of a given type.
      java.nio.file.FileStore getFileStore​(java.nio.file.Path path)
      S3 buckets don't have partitions or volumes so there are no file stores
      java.nio.file.FileSystem getFileSystem​(java.net.URI uri)
      Returns an existing FileSystem created by this provider.
      protected java.util.Map<java.lang.String,​S3FileSystem> getFsCache()
      Get an unmodifiable copy of the Filesystem Cache.
      java.nio.file.Path getPath​(java.net.URI uri)
      Return a Path object by converting the given URI.
      java.lang.String getScheme()
      Returns the URI scheme that identifies this provider.
      boolean isHidden​(java.nio.file.Path path)
      There are no hidden files in S3
      boolean isSameFile​(java.nio.file.Path path, java.nio.file.Path path2)
      Tests if two paths locate the same file.
      void move​(java.nio.file.Path source, java.nio.file.Path target, java.nio.file.CopyOption... options)
      Move or rename a file to a target file.
      java.nio.channels.AsynchronousFileChannel newAsynchronousFileChannel​(java.nio.file.Path path, java.util.Set<? extends java.nio.file.OpenOption> options, java.util.concurrent.ExecutorService executor, java.nio.file.attribute.FileAttribute<?>... attrs)
      Create an AsynchronousFileChannel to the specified path
      java.nio.channels.SeekableByteChannel newByteChannel​(java.nio.file.Path path, java.util.Set<? extends java.nio.file.OpenOption> options, java.nio.file.attribute.FileAttribute<?>... attrs)
      Opens or creates a file, returning a seekable byte channel to access the file.
      java.nio.file.DirectoryStream<java.nio.file.Path> newDirectoryStream​(java.nio.file.Path dir, java.nio.file.DirectoryStream.Filter<? super java.nio.file.Path> filter)
      Opens a directory, returning a DirectoryStream to iterate over the entries in the directory.
      java.nio.channels.FileChannel newFileChannel​(java.nio.file.Path path, java.util.Set<? extends java.nio.file.OpenOption> options, java.nio.file.attribute.FileAttribute<?>... attrs)  
      java.nio.file.FileSystem newFileSystem​(java.net.URI uri, java.util.Map<java.lang.String,​?> env)
      Experimental.
      <A extends java.nio.file.attribute.BasicFileAttributes>
      A      		 readAttributes​(java.nio.file.Path path, java.lang.Class<A> type, java.nio.file.LinkOption... options)
      Reads a file's attributes as a bulk operation.
      java.util.Map<java.lang.String,​java.lang.Object> readAttributes​(java.nio.file.Path path, java.lang.String attributes, java.nio.file.LinkOption... options)
      Reads a set of file attributes as a bulk operation.
      void setAttribute​(java.nio.file.Path path, java.lang.String attribute, java.lang.Object value, java.nio.file.LinkOption... options)
      File attributes of S3 objects cannot be set other than by creating a new object
      void setConfiguration​(S3NioSpiConfiguration configuration)
      Set custom configuration.

      • Methods inherited from class java.nio.file.spi.FileSystemProvider

        createLink, createSymbolicLink, deleteIfExists, installedProviders, newFileSystem, newInputStream, newOutputStream, readSymbolicLink

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • S3FileSystemProvider

        public S3FileSystemProvider()

    • Method Detail

      • getFsCache

        protected java.util.Map<java.lang.String,​S3FileSystem> getFsCache()
        Get an unmodifiable copy of the Filesystem Cache. Mainly used for testing purposes.
        Returns:
        An immutable copy of the filesystem cache.

      • getScheme

        public java.lang.String getScheme()
        Returns the URI scheme that identifies this provider.
        Specified by:
        getScheme in class java.nio.file.spi.FileSystemProvider
        Returns:
        The URI scheme (s3)

      • newFileSystem

        public java.nio.file.FileSystem newFileSystem​(java.net.URI uri,
                                              java.util.Map<java.lang.String,​?> env)
                                       throws java.io.IOException
        Experimental. Attempts to create a new S3 bucket based on the "authority" part of the URI and returns the FileSystem object identified by the URI.
        Specified by:
        newFileSystem in class java.nio.file.spi.FileSystemProvider
        Parameters:
        uri - The URI to identify the file system
        env - The environment to be used when creating the file system. May be null or empty. The following keys are supported:
        • acl
        • grantFullControl
        • grantRead
        • grantReadACP
        • grantWrite
        • grantWriteACP
        • locationConstraint
        The values should be @code{String}s or may be objects if the @code{toString()} method of those objects produce @code{String}s that would be accepted by the associated S3 create bucket builders. All other keys are currently ignored but future implementations may support additional keys and may also throw an @link{IllegalArgumentException} if they are not recognized.
        Returns:
        The new file system
        Throws:
        java.io.IOException - If an exception occurs. In all cases the exception will wrap a causal exception which could be an SDKException thrown by the underlying S3 service or may be one of: ExecutionException, InterruptedException, or TimeoutException if a problem occurs with the asynchronous call to the service.
        java.lang.IllegalArgumentException - if the URI scheme is not "s3".
        Since:
        2.0.0, the current implementation is experimental and may change in the future.

      • getFileSystem

        public java.nio.file.FileSystem getFileSystem​(java.net.URI uri)
        Returns an existing FileSystem created by this provider.

        This method returns a reference to a FileSystem that was created by invoking the newFileSystem(URI,Map) method. File systems created the newFileSystem(Path,Map) method are not returned by this method. The file system is identified by its URI. Its exact form is highly provider dependent. In the case of the default provider the URI's path component is "/" and the authority, query and fragment components are undefined (Undefined components are represented by null).

        Once a file system created by this provider is closed it is provider-dependent if this method returns a reference to the closed file system or throws FileSystemNotFoundException. If the provider allows a new file system to be created with the same URI as a file system it previously created then this method throws the exception if invoked after the file system is closed (and before a new instance is created by the newFileSystem method).

        If a security manager is installed then a provider implementation may require to check a permission before returning a reference to an existing file system. In the case of the default file system, no permission check is required.

        Specified by:
        getFileSystem in class java.nio.file.spi.FileSystemProvider
        Parameters:
        uri - URI reference
        Returns:
        The file system
        Throws:
        java.lang.IllegalArgumentException - If the pre-conditions for the uri parameter aren't met
        java.nio.file.FileSystemNotFoundException - If the file system does not exist
        java.lang.SecurityException - If a security manager is installed, and it denies an unspecified permission.

      • getPath

        public java.nio.file.Path getPath​(java.net.URI uri)
                           throws java.lang.IllegalArgumentException,
                                  java.nio.file.FileSystemNotFoundException,
                                  java.lang.SecurityException
        Return a Path object by converting the given URI. The resulting Path is associated with a FileSystem that already exists or is constructed automatically.

        The exact form of the URI is file system provider dependent. In the case of the default provider, the URI scheme is "file" and the given URI has a non-empty path component, and undefined query, and fragment components. The resulting Path is associated with the default default FileSystem.

        If a security manager is installed then a provider implementation may require to check a permission. In the case of the default file system, no permission check is required.

        Specified by:
        getPath in class java.nio.file.spi.FileSystemProvider
        Parameters:
        uri - The URI to convert. Must not be null.
        Returns:
        The resulting Path
        Throws:
        java.lang.IllegalArgumentException - If the URI scheme does not identify this provider or other preconditions on the uri parameter do not hold
        java.nio.file.FileSystemNotFoundException - The file system, identified by the URI, does not exist and cannot be created automatically
        java.lang.SecurityException - If a security manager is installed, and it denies an unspecified permission.

      • newByteChannel

        public java.nio.channels.SeekableByteChannel newByteChannel​(java.nio.file.Path path,
                                                            java.util.Set<? extends java.nio.file.OpenOption> options,
                                                            java.nio.file.attribute.FileAttribute<?>... attrs)
                                                     throws java.io.IOException
        Opens or creates a file, returning a seekable byte channel to access the file. This method works in exactly the manner specified by the Files.newByteChannel(Path, Set, FileAttribute[]) method.
        Specified by:
        newByteChannel in class java.nio.file.spi.FileSystemProvider
        Parameters:
        path - the path to the file to open or create
        options - options specifying how the file is opened
        attrs - an optional list of file attributes to set atomically when creating the file
        Returns:
        a new seekable byte channel
        Throws:
        java.lang.IllegalArgumentException - if the set contains an invalid combination of options
        java.lang.UnsupportedOperationException - if an unsupported open option is specified or the array contains attributes that cannot be set atomically when creating the file
        java.nio.file.FileAlreadyExistsException - if a file of that name already exists and the CREATE_NEW option is specified (optional specific exception)
        java.io.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 the path if the file is opened for reading. The checkWrite method is invoked to check write access to the path if the file is opened for writing. The checkDelete method is invoked to check delete access if the file is opened with the DELETE_ON_CLOSE option.

      • newDirectoryStream

        public java.nio.file.DirectoryStream<java.nio.file.Path> newDirectoryStream​(java.nio.file.Path dir,
                                                                            java.nio.file.DirectoryStream.Filter<? super java.nio.file.Path> filter)
                                                                     throws java.io.IOException
        Opens a directory, returning a DirectoryStream to iterate over the entries in the directory. This method works in exactly the manner specified by the Files.newDirectoryStream(Path, DirectoryStream.Filter) method.
        Specified by:
        newDirectoryStream in class java.nio.file.spi.FileSystemProvider
        Parameters:
        dir - the path to the directory
        filter - the directory stream filter
        Returns:
        a new and open DirectoryStream object
        Throws:
        java.io.IOException

      • createDirectory

        public void createDirectory​(java.nio.file.Path dir,
                            java.nio.file.attribute.FileAttribute<?>... attrs)
                     throws java.io.IOException
        Creates a new directory. This method works in exactly the manner specified by the Files.createDirectory(java.nio.file.Path, java.nio.file.attribute.FileAttribute<?>...) method.
        Specified by:
        createDirectory in class java.nio.file.spi.FileSystemProvider
        Parameters:
        dir - the directory to create
        attrs - an optional list of file attributes to set atomically when creating the directory
        Throws:
        java.io.IOException

      • delete

        public void delete​(java.nio.file.Path path)
            throws java.io.IOException
        Deletes a file. This method works in exactly the manner specified by the Files.delete(java.nio.file.Path) method.
        Specified by:
        delete in class java.nio.file.spi.FileSystemProvider
        Parameters:
        path - the path to the file to delete
        Throws:
        java.io.IOException

      • copy

        public void copy​(java.nio.file.Path source,
                 java.nio.file.Path target,
                 java.nio.file.CopyOption... options)
          throws java.io.IOException
        Copy a file to a target file. This method works in exactly the manner specified by the Files.copy(Path, Path, CopyOption[]) method except that both the source and target paths must be associated with this provider.
        Our implementation will also copy the content of the directory via batched copy operations. This is a variance from some other implementations such as `UnixFileSystemProvider` where directory contents are not copied and the use of the walkFileTree is suggested to perform deep copies. In S3 this could result in an explosion of API calls which would be both expensive in time and possibly money.
        Specified by:
        copy in class java.nio.file.spi.FileSystemProvider
        Parameters:
        source - the path to the file to copy
        target - the path to the target file
        options - options specifying how the copy should be done
        Throws:
        java.io.IOException

      • move

        public void move​(java.nio.file.Path source,
                 java.nio.file.Path target,
                 java.nio.file.CopyOption... options)
          throws java.io.IOException
        Move or rename a file to a target file. This method works in exactly the manner specified by the Files.move(java.nio.file.Path, java.nio.file.Path, java.nio.file.CopyOption...) method except that both the source and target paths must be associated with this provider.
        Specified by:
        move in class java.nio.file.spi.FileSystemProvider
        Parameters:
        source - the path to the file to move
        target - the path to the target file
        options - options specifying how the move should be done
        Throws:
        java.io.IOException

      • isSameFile

        public boolean isSameFile​(java.nio.file.Path path,
                          java.nio.file.Path path2)
                   throws java.io.IOException
        Tests if two paths locate the same file. This method works in exactly the manner specified by the Files.isSameFile(java.nio.file.Path, java.nio.file.Path) method.
        Specified by:
        isSameFile in class java.nio.file.spi.FileSystemProvider
        Parameters:
        path - one path to the file
        path2 - the other path
        Returns:
        true if, and only if, the two paths locate the same file
        Throws:
        java.io.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.

      • isHidden

        public boolean isHidden​(java.nio.file.Path path)
        There are no hidden files in S3
        Specified by:
        isHidden in class java.nio.file.spi.FileSystemProvider
        Parameters:
        path - the path to the file to test
        Returns:
        false always

      • getFileStore

        public java.nio.file.FileStore getFileStore​(java.nio.file.Path path)
        S3 buckets don't have partitions or volumes so there are no file stores
        Specified by:
        getFileStore in class java.nio.file.spi.FileSystemProvider
        Parameters:
        path - the path to the file
        Returns:
        null always

      • checkAccess

        public void checkAccess​(java.nio.file.Path path,
                        java.nio.file.AccessMode... modes)
                 throws java.io.IOException
        Checks the existence, and optionally the accessibility, of a file.

        This method may be used by the isReadable, isWritable and isExecutable methods to check the accessibility of a file.

        This method checks the existence of a file and that this Java virtual machine has appropriate privileges that would allow it to access the file according to all the access modes specified in the modes parameter as follows:

        Access Modes
        Value Description
        READ Checks that the file exists and that the Java virtual machine has permission to read the file.
        WRITE Checks that the file exists and that the Java virtual machine has permission to write to the file,
        EXECUTE Checks that the file exists and that the Java virtual machine has permission to execute the file. The semantics may differ when checking access to a directory. For example, on UNIX systems, checking for EXECUTE access checks that the Java virtual machine has permission to search the directory in order to access file or subdirectories.

        If the modes parameter is of length zero, then the existence of the file is checked.

        This method follows symbolic links if the file referenced by this object is a symbolic link. Depending on the implementation, this method may require reading file permissions, access control lists, or other file attributes in order to check the effective access to the file. To determine the effective access to a file may require access to several attributes and so in some implementations this method may not be atomic with respect to other file system operations.

        Specified by:
        checkAccess in class java.nio.file.spi.FileSystemProvider
        Parameters:
        path - the path to the file to check
        modes - The access modes to check; may have zero elements
        Throws:
        java.lang.UnsupportedOperationException - an implementation is required to support checking for READ, WRITE, and EXECUTE access. This exception is specified to allow for the Access enum to be extended in future releases.
        java.nio.file.NoSuchFileException - if a file does not exist (optional specific exception)
        java.nio.file.AccessDeniedException - the requested access would be denied or the access cannot be determined because the Java virtual machine has insufficient privileges or other reasons. (optional specific exception)
        java.io.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 is invoked when checking read access to the file or only the existence of the file, the checkWrite is invoked when checking write access to the file, and checkExec is invoked when checking execute access.

      • getFileAttributeView

        public <V extends java.nio.file.attribute.FileAttributeView> V getFileAttributeView​(java.nio.file.Path path,
                                                                                    java.lang.Class<V> type,
                                                                                    java.nio.file.LinkOption... options)
        Returns a file attribute view of a given type. This method works in exactly the manner specified by the Files.getFileAttributeView(java.nio.file.Path, java.lang.Class<V>, java.nio.file.LinkOption...) method.
        Specified by:
        getFileAttributeView in class java.nio.file.spi.FileSystemProvider
        Type Parameters:
        V - type of FileAttributeView, see type
        Parameters:
        path - the path to the file
        type - the Class object corresponding to the file attribute view. Must be BasicFileAttributeView.class
        options - ignored as there are no links in S3
        Returns:
        a file attribute view of the specified type, or null if the attribute view type is not available

      • readAttributes

        public <A extends java.nio.file.attribute.BasicFileAttributes> A readAttributes​(java.nio.file.Path path,
                                                                                java.lang.Class<A> type,
                                                                                java.nio.file.LinkOption... options)
                                                                         throws java.io.IOException
        Reads a file's attributes as a bulk operation. This method works in exactly the manner specified by the Files.readAttributes(Path, Class, LinkOption[]) method.
        Specified by:
        readAttributes in class java.nio.file.spi.FileSystemProvider
        Parameters:
        path - the path to the file
        type - the Class of the file attributes required to read. Supported types are BasicFileAttributes
        options - options indicating how symbolic links are handled
        Returns:
        the file attributes or null if path is inferred to be a directory.
        Throws:
        java.io.IOException

      • readAttributes

        public java.util.Map<java.lang.String,​java.lang.Object> readAttributes​(java.nio.file.Path path,
                                                                             java.lang.String attributes,
                                                                             java.nio.file.LinkOption... options)
                                                                      throws java.io.IOException
        Reads a set of file attributes as a bulk operation. Largely equivalent to readAttributes(Path path, Class<A> type, LinkOption... options) where the returned object is a map of method names (attributes) to values, filtered on the comma separated attributes.
        Specified by:
        readAttributes in class java.nio.file.spi.FileSystemProvider
        Parameters:
        path - the path to the file
        attributes - the comma separated attributes to read. May be prefixed with "s3:"
        options - ignored, S3 has no links
        Returns:
        a map of the attributes returned; may be empty. The map's keys are the attribute names, its values are the attribute values. Returns an empty map if attributes is empty, or if path is inferred to be a directory.
        Throws:
        java.lang.UnsupportedOperationException - if the attribute view is not available
        java.lang.IllegalArgumentException - if no attributes are specified or an unrecognized attributes is specified
        java.lang.SecurityException - In the case of the default provider, and a security manager is installed, its checkRead method denies 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.
        java.io.IOException

      • setAttribute

        public void setAttribute​(java.nio.file.Path path,
                         java.lang.String attribute,
                         java.lang.Object value,
                         java.nio.file.LinkOption... options)
                  throws java.lang.UnsupportedOperationException
        File attributes of S3 objects cannot be set other than by creating a new object
        Specified by:
        setAttribute in class java.nio.file.spi.FileSystemProvider
        Throws:
        java.lang.UnsupportedOperationException - always

      • setConfiguration

        public void setConfiguration​(S3NioSpiConfiguration configuration)
        Set custom configuration. This configuration is referred to for API timeouts
        Parameters:
        configuration - The new configuration containing the timeout info

      • newFileChannel

        public java.nio.channels.FileChannel newFileChannel​(java.nio.file.Path path,
                                                    java.util.Set<? extends java.nio.file.OpenOption> options,
                                                    java.nio.file.attribute.FileAttribute<?>... attrs)
                                             throws java.io.IOException
        Overrides:
        newFileChannel in class java.nio.file.spi.FileSystemProvider
        Parameters:
        path - the path of the file to open or create
        options - options specifying how the file is opened
        attrs - an optional list of file attributes to set atomically when creating the file. Currently, ignored.
        Returns:
        a new FileChannel object representing the specified file
        Throws:
        java.io.IOException - if an I/O error occurs

      • newAsynchronousFileChannel

        public java.nio.channels.AsynchronousFileChannel newAsynchronousFileChannel​(java.nio.file.Path path,
                                                                            java.util.Set<? extends java.nio.file.OpenOption> options,
                                                                            java.util.concurrent.ExecutorService executor,
                                                                            java.nio.file.attribute.FileAttribute<?>... attrs)
                                                                     throws java.io.IOException
        Create an AsynchronousFileChannel to the specified path
        Overrides:
        newAsynchronousFileChannel in class java.nio.file.spi.FileSystemProvider
        Parameters:
        path - the path of the file to open or create
        options - options specifying how the file is opened
        executor - the thread pool or null to associate the channel with the default thread pool
        attrs - an optional list of file attributes to set atomically when creating the file
        Returns:
        a new AsynchronousFileChannel object representing the specified file
        Throws:
        java.io.IOException - if a problem occurs while creating the channel