Package software.amazon.nio.spi.s3

Class S3Path

  • All Implemented Interfaces:
    java.lang.Comparable<java.nio.file.Path>, java.lang.Iterable<java.nio.file.Path>, java.nio.file.Path, java.nio.file.Watchable
    public class S3Path
extends java.lang.Object
implements java.nio.file.Path

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String PATH_SEPARATOR  

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.lang.String bucketName()
      The name of the S3 bucket that represents the root ("/") of this Path
      int compareTo​(java.nio.file.Path other)
      Compares two abstract paths lexicographically.
      boolean endsWith​(java.lang.String other)
      Tests if this path ends with a Path, constructed by converting the given path string, in exactly the manner specified by the endsWith(Path) method.
      boolean endsWith​(java.nio.file.Path other)
      Tests if this path ends with the given path.
      boolean equals​(java.lang.Object other)
      Tests this path for equality with the given object.
      S3Path getFileName()
      Returns the name of the file or directory denoted by this path as a Path object.
      S3FileSystem getFileSystem()
      Returns the file system that created this object.
      java.lang.String getKey()
      The key of the object for S3.
      S3Path getName​(int index)
      Returns a name element of this path as a Path object.
      int getNameCount()
      Returns the number of name elements in the path.
      S3Path getParent()
      Returns the parent path, or null if this path does not have a parent.
      static S3Path getPath​(S3FileSystem fsForBucket, java.lang.String first, java.lang.String... more)
      Construct a Path in the parent FileSystem using the POSIX style.
      static S3Path getPath​(S3FileSystem fs, software.amazon.awssdk.services.s3.model.S3Object s3Object)
      Construct a path from an S3 object in the bucket represented by the filesystem
      S3Path getRoot()
      If the path is absolute then returns the root of the path (e.g.
      int hashCode()
      Computes a hash code for this path.
      boolean isAbsolute()
      Tells whether this path is absolute.
      boolean isDirectory()
      Is the path inferred to be an S3 directory?
      java.util.Iterator<java.nio.file.Path> iterator()
      Returns an iterator over the name elements of this path.
      S3Path normalize()
      Returns a path that is this path with redundant name elements eliminated.
      java.nio.file.WatchKey register​(java.nio.file.WatchService watcher, java.nio.file.WatchEvent.Kind<?>... events)
      Currently not implemented
      java.nio.file.WatchKey register​(java.nio.file.WatchService watcher, java.nio.file.WatchEvent.Kind<?>[] events, java.nio.file.WatchEvent.Modifier... modifiers)
      Currently not implemented
      S3Path relativize​(java.nio.file.Path other)
      Constructs a relative path between this path and a given path.
      S3Path resolve​(java.lang.String other)
      Converts a given path string to a S3Path and resolves it against this S3Path in exactly the manner specified by the resolve method.
      S3Path resolve​(java.nio.file.Path other)
      Resolve the given path against this path.
      S3Path resolveSibling​(java.lang.String other)
      Converts a given path string to a Path and resolves it against this path's parent path in exactly the manner specified by the resolveSibling method.
      S3Path resolveSibling​(java.nio.file.Path other)
      Resolves the given path against this path's parent path.
      boolean startsWith​(java.lang.String other)
      Tests if this path starts with a Path, constructed by converting the given path string, in exactly the manner specified by the startsWith(Path) method.
      boolean startsWith​(java.nio.file.Path other)
      Tests if this path starts with the given path.
      S3Path subpath​(int beginIndex, int endIndex)
      Returns a relative Path that is a subsequence of the name elements of this path.
      S3Path toAbsolutePath()
      Returns a Path object representing the absolute path of this path.
      java.io.File toFile()
      S3 Objects cannot be represented in the local file system
      S3Path toRealPath​(java.nio.file.LinkOption... options)
      Returns the real path of an existing file.
      java.lang.String toString()
      Returns the string representation of this path.
      java.net.URI toUri()
      Returns a URI to represent this path.

      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait

      • Methods inherited from interface java.lang.Iterable

        forEach, spliterator

    • Method Detail

      • getPath

        public static S3Path getPath​(S3FileSystem fs,
                             software.amazon.awssdk.services.s3.model.S3Object s3Object)
        Construct a path from an S3 object in the bucket represented by the filesystem
        Parameters:
        fs - the filesystem that holds (or will hold) the object represented by s3Object
        s3Object - the object
        Returns:
        a new S3Path

      • getPath

        public static S3Path getPath​(S3FileSystem fsForBucket,
                             java.lang.String first,
                             java.lang.String... more)
        Construct a Path in the parent FileSystem using the POSIX style. The path string is assumed to follow the POSIX form with the "root" of the bucket being represented by "/". The supplied path should not be a URI. It should not start with the string "s3:". For example, if this S3FileSystem represents "s3://my-bucket" then "s3://my-bucket/foo.txt" should be addressed by the path "/foo.txt" or by a path relative to the current working directory following POSIX conventions. Further, although folders or directories don't technically exist in S3 the presence of a directory is implicit if "s3://my-bucket/someFolder/" contains objects and the Path to this folder is therefore valid.

        This library DOES NOT support S3 Paths that are not compliant with POSIX conventions. For example, the URI s3://my-bucket/../foo.txt is legal in S3 but due to POSIX conventions it will be unreachable through this API due to the special meaning of the .. directory alias in POSIX.

        Parameters:
        fsForBucket - the filesystem for the bucket that holds this path
        first - the path string or initial part of the path string, may not be null. It may not be empty unless more is also null has zero length
        more - additional strings to be joined to form the path string
        Returns:
        a new S3Path
        Throws:
        java.nio.file.InvalidPathException - if the Path cannot be constructed

      • getFileSystem

        public S3FileSystem getFileSystem()
        Returns the file system that created this object.
        Specified by:
        getFileSystem in interface java.nio.file.Path
        Returns:
        the file system that created this object

      • bucketName

        public java.lang.String bucketName()
        The name of the S3 bucket that represents the root ("/") of this Path
        Returns:
        the bucketName, equivalent to getFileSystem().bucketName()

      • isAbsolute

        public boolean isAbsolute()
        Tells whether this path is absolute.

        An absolute path is complete in that it doesn't need to be combined with other path information in order to locate a file.

        Specified by:
        isAbsolute in interface java.nio.file.Path
        Returns:
        true if, and only if, this path is absolute

      • isDirectory

        public boolean isDirectory()
        Is the path inferred to be an S3 directory?
        Returns:
        true if the path can be inferrred to be a directory

      • getRoot

        public S3Path getRoot()
        If the path is absolute then returns the root of the path (e.g. "/") otherwise null
        Specified by:
        getRoot in interface java.nio.file.Path
        Returns:
        a path representing the root component of this path, or null

      • getFileName

        public S3Path getFileName()
        Returns the name of the file or directory denoted by this path as a Path object. The file name is the farthest element from the root in the directory hierarchy.
        Specified by:
        getFileName in interface java.nio.file.Path
        Returns:
        a path representing the name of the file or directory, or null if this path has zero elements

      • getParent

        public S3Path getParent()
        Returns the parent path, or null if this path does not have a parent.

        The parent of this path object consists of this path's root component, if any, and each element in the path except for the farthest from the root in the directory hierarchy. This method does not access the file system; the path or its parent may not exist. Furthermore, this method does not eliminate special names such as "." and ".." that may be used in some implementations. On UNIX for example, the parent of "/a/b/c" is "/a/b", and the parent of "x/y/." is "x/y". This method may be used with the normalize method, to eliminate redundant names, for cases where shell-like navigation is required.

        If this path has one or more elements, and no root component, then this method is equivalent to evaluating the expression: 

         subpath(0, getNameCount()-1);
        Specified by:
        getParent in interface java.nio.file.Path
        Returns:
        a path representing the path's parent

      • getNameCount

        public int getNameCount()
        Returns the number of name elements in the path.
        Specified by:
        getNameCount in interface java.nio.file.Path
        Returns:
        the number of elements in the path, or 0 if this path only represents a root component

      • getName

        public S3Path getName​(int index)
        Returns a name element of this path as a Path object.

        The index parameter is the index of the name element to return. The element that is closest to the root in the directory hierarchy has the index 0. The element that is farthest from the root has the index count-1.

        Specified by:
        getName in interface java.nio.file.Path
        Parameters:
        index - the index of the element
        Returns:
        the name element
        Throws:
        java.lang.IllegalArgumentException - if index is negative, index is greater than or equal to the number of elements, or this path has zero name elements

      • subpath

        public S3Path subpath​(int beginIndex,
                      int endIndex)
        Returns a relative Path that is a subsequence of the name elements of this path.

        The beginIndex and endIndex parameters specify the subsequence of name elements. The name that is closest to the root in the directory hierarchy has the index 0. The name that is farthest from the root has the index count-1. The returned Path object has the name elements that begin at beginIndex and extend to the element at index endIndex-1.

        Specified by:
        subpath in interface java.nio.file.Path
        Parameters:
        beginIndex - the index of the first element, inclusive
        endIndex - the index of the last element, exclusive
        Returns:
        a new Path object that is a subsequence of the name elements in this Path
        Throws:
        java.lang.IllegalArgumentException - if beginIndex is negative, or greater than or equal to the number of elements. If endIndex is less than or equal to beginIndex, or larger than the number of elements.

      • startsWith

        public boolean startsWith​(java.nio.file.Path other)
        Tests if this path starts with the given path.

        This path starts with the given path if this path's root component starts with the root component of the given path, and this path starts with the same name elements as the given path. If the given path has more name elements than this path then false is returned.

        If this path does not have a root component and the given path has a root component then this path does not start with the given path.

        If the given path is associated with a different FileSystem (s3 bucket) to this path then false is returned.

        Specified by:
        startsWith in interface java.nio.file.Path
        Parameters:
        other - the given path
        Returns:
        true if this path starts with the given path; otherwise false

      • startsWith

        public boolean startsWith​(java.lang.String other)
        Tests if this path starts with a Path, constructed by converting the given path string, in exactly the manner specified by the startsWith(Path) method.
        Specified by:
        startsWith in interface java.nio.file.Path
        Parameters:
        other - the given path string
        Returns:
        true if this path starts with the given path; otherwise false
        Throws:
        java.nio.file.InvalidPathException - If the path string cannot be converted to a Path.

      • endsWith

        public boolean endsWith​(java.nio.file.Path other)
        Tests if this path ends with the given path.

        If the given path has N elements, and no root component, and this path has N or more elements, then this path ends with the given path if the last N elements of each path, starting at the element farthest from the root, are equal.

        If the given path has a root component then this path ends with the given path if the root component of this path ends with the root component of the given path, and the corresponding elements of both paths are equal. If the two paths are equal then they can be said to end with each other. If this path does not have a root component and the given path has a root component then this path does not end with the given path.

        If the given path is associated with a different FileSystem to this path then false is returned.

        Specified by:
        endsWith in interface java.nio.file.Path
        Parameters:
        other - the given path
        Returns:
        true if this path ends with the given path; otherwise false

      • endsWith

        public boolean endsWith​(java.lang.String other)
        Tests if this path ends with a Path, constructed by converting the given path string, in exactly the manner specified by the endsWith(Path) method. On UNIX for example, the path "foo/bar" ends with "foo/bar" and "bar". It does not end with "r" or "/bar". Note that trailing separators are not taken into account, and so invoking this method on the Path"foo/bar" with the String "bar/" returns true.
        Specified by:
        endsWith in interface java.nio.file.Path
        Parameters:
        other - the given path string
        Returns:
        true if this path ends with the given path; otherwise false
        Throws:
        java.nio.file.InvalidPathException - If the path string cannot be converted to a Path.

      • normalize

        public S3Path normalize()
        Returns a path that is this path with redundant name elements eliminated. All occurrences of "." are considered redundant. If a ".." is preceded by a non-".." name then both names are considered redundant (the process to identify such names is repeated until it is no longer applicable).

        This method does not access the file system; the path may not locate a file that exists. Eliminating ".." and a preceding name from a path may result in the path that locates a different file than the original path. This can arise when the preceding name is a symbolic link.

        Specified by:
        normalize in interface java.nio.file.Path
        Returns:
        the resulting path or this path if it does not contain redundant name elements; an empty path is returned if this path does have a root component and all name elements are redundant
        See Also:
        getParent(), toRealPath(java.nio.file.LinkOption...)

      • resolve

        public S3Path resolve​(java.nio.file.Path other)
        Resolve the given path against this path.

        If the other parameter is an absolute path then this method trivially returns other. If other is an empty path then this method trivially returns this path. Otherwise, this method considers this path to be a directory and resolves the given path against this path by joining the given path to this path with the addition of a separator ('/') and returns a resulting path that ends with the given (other) path.

        Specified by:
        resolve in interface java.nio.file.Path
        Parameters:
        other - the path to resolve against this path
        Returns:
        the resulting path
        Throws:
        java.nio.file.ProviderMismatchException - if other is null or if it is not an instance of S3Path
        java.lang.IllegalArgumentException - if other is NOT and instance of an S3Path
        See Also:
        relativize(java.nio.file.Path)

      • resolve

        public S3Path resolve​(java.lang.String other)
        Converts a given path string to a S3Path and resolves it against this S3Path in exactly the manner specified by the resolve method.
        Specified by:
        resolve in interface java.nio.file.Path
        Parameters:
        other - the path string to resolve against this path
        Returns:
        the resulting path
        Throws:
        java.nio.file.InvalidPathException - if the path string cannot be converted to a Path.
        See Also:
        FileSystem.getPath(java.lang.String, java.lang.String...)

      • resolveSibling

        public S3Path resolveSibling​(java.nio.file.Path other)
        Resolves the given path against this path's parent path. This is useful where a file name needs to be replaced with another file name. For example, suppose that the name separator is "/" and a path represents "dir1/dir2/foo", then invoking this method with the Path "bar" will result in the Path "dir1/dir2/bar". If this path does not have a parent path, or other is absolute, then this method returns other. If other is an empty path then this method returns this path's parent, or where this path doesn't have a parent, the empty path.
        Specified by:
        resolveSibling in interface java.nio.file.Path
        Parameters:
        other - the path to resolve against this path's parent
        Returns:
        the resulting path
        See Also:
        resolve(Path)

      • resolveSibling

        public S3Path resolveSibling​(java.lang.String other)
        Converts a given path string to a Path and resolves it against this path's parent path in exactly the manner specified by the resolveSibling method.
        Specified by:
        resolveSibling in interface java.nio.file.Path
        Parameters:
        other - the path string to resolve against this path's parent
        Returns:
        the resulting path
        Throws:
        java.nio.file.InvalidPathException - if the path string cannot be converted to a Path.
        See Also:
        FileSystem.getPath(java.lang.String, java.lang.String...)

      • relativize

        public S3Path relativize​(java.nio.file.Path other)
        Constructs a relative path between this path and a given path.

        Relativization is the inverse of resolution. This method attempts to construct a relative path that when resolved against this path, yields a path that locates the same file as the given path. For example, on UNIX, if this path is "/a/b" and the given path is "/a/b/c/d" then the resulting relative path would be "c/d". Where this path and the given path do not have a root component, then a relative path can be constructed. A relative path cannot be constructed if only one of the paths have a root component. Where both paths have a root component then it is implementation dependent if a relative path can be constructed. If this path and the given path are equal then an empty path is returned.

        Specified by:
        relativize in interface java.nio.file.Path
        Parameters:
        other - the path to relativize against this path
        Returns:
        the resulting relative path, or an empty path if both paths are equal
        Throws:
        java.lang.IllegalArgumentException - if other is not a Path that can be relativized against this path

      • toUri

        public java.net.URI toUri()
        Returns a URI to represent this path.

        This method constructs an absolute and normalized URI with a scheme equal to the URI scheme that identifies the provider (s3).

        Specified by:
        toUri in interface java.nio.file.Path
        Returns:
        the URI representing this path
        Throws:
        java.io.IOError - if an I/O error occurs obtaining the absolute path, or where a file system is constructed to access the contents of a file as a file system, and the URI of the enclosing file system cannot be obtained
        java.lang.SecurityException - In the case of the default provider, and a security manager is installed, the toAbsolutePath method throws a security exception.

      • toAbsolutePath

        public S3Path toAbsolutePath()
        Returns a Path object representing the absolute path of this path.

        If this path is already absolute then this method simply returns this path. Otherwise, this method resolves the path by resolving the path against the root (the top level of the bucket). The resulting path may contain redundancies and may point to a non-existent location.

        Specified by:
        toAbsolutePath in interface java.nio.file.Path
        Returns:
        a Path object representing the absolute path

      • toRealPath

        public S3Path toRealPath​(java.nio.file.LinkOption... options)
        Returns the real path of an existing file.

        If this path is relative then its absolute path is first obtained, as if by invoking the toAbsolutePath method. When deriving the real path, and a ".." (or equivalent) is preceded by a non-".." name then an implementation will cause both names to be removed.

        Specified by:
        toRealPath in interface java.nio.file.Path
        Parameters:
        options - options indicating how symbolic links are handled. S3 has no links so this will be ignored.
        Returns:
        an absolute path represent the real path of the file located by this object

      • toFile

        public java.io.File toFile()
        S3 Objects cannot be represented in the local file system
        Specified by:
        toFile in interface java.nio.file.Path
        Throws:
        java.lang.UnsupportedOperationException - always

      • register

        public java.nio.file.WatchKey register​(java.nio.file.WatchService watcher,
                                       java.nio.file.WatchEvent.Kind<?>[] events,
                                       java.nio.file.WatchEvent.Modifier... modifiers)
                                throws java.lang.UnsupportedOperationException
        Currently not implemented
        Specified by:
        register in interface java.nio.file.Path
        Specified by:
        register in interface java.nio.file.Watchable
        Throws:
        java.lang.UnsupportedOperationException - always

      • register

        public java.nio.file.WatchKey register​(java.nio.file.WatchService watcher,
                                       java.nio.file.WatchEvent.Kind<?>... events)
                                throws java.lang.UnsupportedOperationException
        Currently not implemented
        Specified by:
        register in interface java.nio.file.Path
        Specified by:
        register in interface java.nio.file.Watchable
        Throws:
        java.lang.UnsupportedOperationException - always

      • iterator

        public java.util.Iterator<java.nio.file.Path> iterator()
        Returns an iterator over the name elements of this path.

        The first element returned by the iterator represents the name element that is closest to the root in the directory hierarchy, the second element is the next closest, and so on. The last element returned is the name of the file or directory denoted by this path. The root component, if present, is not returned by the iterator.

        Specified by:
        iterator in interface java.lang.Iterable<java.nio.file.Path>
        Specified by:
        iterator in interface java.nio.file.Path
        Returns:
        an iterator over the name elements of this path.

      • compareTo

        public int compareTo​(java.nio.file.Path other)
        Compares two abstract paths lexicographically. The ordering defined by this method is provider specific, and in the case of the default provider, platform specific. This method does not access the file system and neither file is required to exist.

        This method may not be used to compare paths that are associated with different file system providers.

        Specified by:
        compareTo in interface java.lang.Comparable<java.nio.file.Path>
        Specified by:
        compareTo in interface java.nio.file.Path
        Parameters:
        other - the path compared to this path.
        Returns:
        zero if the argument is equal to this path, a value less than zero if this path is lexicographically less than the argument, or a value greater than zero if this path is lexicographically greater than the argument
        Throws:
        java.lang.ClassCastException - if the paths are associated with different providers

      • equals

        public boolean equals​(java.lang.Object other)
        Tests this path for equality with the given object.

        true if other is also an S3Path from the same bucket and the two paths have the same real path.

        Specified by:
        equals in interface java.nio.file.Path
        Overrides:
        equals in class java.lang.Object
        Parameters:
        other - the object to which this object is to be compared
        Returns:
        true if, and only if, the given object is a Path that is identical to this Path

      • hashCode

        public int hashCode()
        Computes a hash code for this path.

        The hash code is based upon the components of the path, and satisfies the general contract of the Object.hashCode method.

        Specified by:
        hashCode in interface java.nio.file.Path
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        the hash-code value for this path

      • toString

        public java.lang.String toString()
        Returns the string representation of this path.
        Specified by:
        toString in interface java.nio.file.Path
        Overrides:
        toString in class java.lang.Object
        Returns:
        the string representation of this path

      • getKey

        public java.lang.String getKey()
        The key of the object for S3. Essentially the "real path" with the "/" prefix and bucket name removed.
        Returns:
        the key