Package com.azure.storage.blob.nio

Class AzurePath

java.lang.Object

com.azure.storage.blob.nio.AzurePath

All Implemented Interfaces:

Comparable<Path>, Iterable<Path>, Path, Watchable

public final class AzurePath
extends Object
implements Path

An object that may be used to locate a file in a file system.

The root component, if it is present, is the first element of the path and is denoted by a ':' as the last character. Hence, only one instance of ':' may appear in a path string, and it may only be the last character of the first element in the path. The root component is used to identify which container a path belongs to. All other path elements, including separators, are considered as the blob name. fromBlobUrl(com.azure.storage.blob.nio.AzureFileSystemProvider, java.lang.String) may be used to convert a typical http url pointing to a blob into an AzurePath object pointing to the same resource.

Constructing a syntactically valid path does not ensure a resource exists at the given path. An error will not be thrown until trying to access an invalid resource, e.g. trying to access a resource that does not exist.

Path names are case-sensitive.

If a resource is accessed via a relative path, it will be resolved against the default directory of the file system. The default directory is as defined in the AzureFileSystem docs.

Leading and trailing separators will be stripped from each component passed to AzureFileSystem.getPath(String, String...). This has the effect of treating "foo/" as though it were simply "foo".

Method Summary

Modifier and Type	Method	Description
int	compareTo(Path path)	Compares two abstract paths lexicographically.
boolean	endsWith(String path)	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(Path path)	Tests if this path ends with the given path.
boolean	equals(Object o)	A path is considered equal to another path if it is associated with the same file system instance and if the path strings are equivalent.
static AzurePath	fromBlobUrl(AzureFileSystemProvider provider, String url)	A utility method to conveniently convert from a URL to a storage resource to an AzurePath pointing to the same resource.
Path	getFileName()	Returns the name of the file or directory denoted by this path as a Path object.
FileSystem	getFileSystem()	Returns the file system that created this object.
Path	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.
Path	getParent()	Returns the parent path, or null if this path does not have a parent.
Path	getRoot()	Returns the root component of this path as a Path object, or null if this path does not have a root component.
int	hashCode()
boolean	isAbsolute()	Tells whether this path is absolute.
Iterator<Path>	iterator()	Returns an iterator over the name elements of this path.
Path	normalize()	Returns a path that is this path with redundant name elements eliminated.
WatchKey	register(WatchService watchService, WatchEvent.Kind<?>... kinds)	Unsupported.
WatchKey	register(WatchService watchService, WatchEvent.Kind<?>[] kinds, WatchEvent.Modifier... modifiers)	Unsupported.
Path	relativize(Path path)	Constructs a relative path between this path and a given path.
Path	resolve(String path)	Converts a given path string to a Path and resolves it against this Path in exactly the manner specified by the resolve method.
Path	resolve(Path path)	Resolve the given path against this path.
Path	resolveSibling(String path)	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.
Path	resolveSibling(Path path)	Resolves the given path against this path's parent path.
boolean	startsWith(String path)	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(Path path)	Tests if this path starts with the given path.
Path	subpath(int begin, int end)	Returns a relative Path that is a subsequence of the name elements of this path.
Path	toAbsolutePath()	Returns a Path object representing the absolute path of this path.
BlobClient	toBlobClient()	Returns a BlobClient which references a blob pointed to by this path.
File	toFile()	Unsupported.
Path	toRealPath(LinkOption... linkOptions)	Unsupported.
String	toString()	Returns the string representation of this path.
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

getFileSystem

public FileSystem getFileSystem()

Returns the file system that created this object.

Specified by:

getFileSystem in interface Path

Returns:

the file system that created this object

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. A path is considered absolute in this file system if it contains a root component.

Specified by:

isAbsolute in interface Path

Returns:

whether the path is absolute

getRoot

public Path getRoot()

Returns the root component of this path as a Path object, or null if this path does not have a root component.

The root component of this path also identifies the Azure Storage Container in which the file is stored. This method will not validate that the root component corresponds to an actual file store/container in this file system. It will simply return the root component of the path if one is present and syntactically valid.

Specified by:

getRoot in interface Path

Returns:

a path representing the root component of this path, or null

getFileName

public Path 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 Path

Returns:

a path representing the name of the file or directory, or null if this path has zero elements

getParent

public Path 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 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 Path

Returns:

the number of elements in the path, or 0 if this path only represents a root component

getName

public Path 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 index 0. The element that is farthest from the root has index count-1.

Specified by:

getName in interface Path

Parameters:

index - the index of the element

Returns:

the name element

Throws:

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 Path subpath(int begin,
                    int end)

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 index 0. The name that is farthest from the root has 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 Path

Parameters:

begin - the index of the first element, inclusive

end - the index of the last element, exclusive

Returns:

a new Path object that is a subsequence of the name elements in this Path

startsWith

public boolean startsWith(Path path)

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 to this path then false is returned.

In this implementation, a root component starts with another root component if the two root components are equivalent strings. In other words, if the files are stored in the same container.

Specified by:

startsWith in interface Path

Parameters:

path - the given path

Returns:

true if this path starts with the given path; otherwise false

startsWith

public boolean startsWith(String path)

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 Path

Parameters:

path - the given path string

Returns:

true if this path starts with the given path; otherwise false

Throws:

InvalidPathException - If the path string cannot be converted to a Path.

endsWith

public boolean endsWith(Path path)

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 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.

In this implementation, a root component ends with another root component if the two root components are equivalent strings. In other words, if the files are stored in the same container.

Specified by:

endsWith in interface Path

Parameters:

path - the given path

Returns:

true if this path ends with the given path; otherwise false

endsWith

public boolean endsWith(String path)

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.

Specified by:

endsWith in interface Path

Parameters:

path - the given path string

Returns:

true if this path starts with the given path; otherwise false

Throws:

InvalidPathException - If the path string cannot be converted to a Path.

normalize

public Path normalize()

Returns a path that is this path with redundant name elements eliminated.

It derives from this path, a path that does not contain redundant name elements. The "." and ".." are special names used to indicate the current directory and parent directory. 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 is it 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

Specified by:

normalize in interface 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

resolve

public Path resolve(Path path)

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. In the simplest case, the given path does not have a root component, in which case this method joins the given path to this path and returns a resulting path that ends with the given path. Where the given path has a root component then resolution is highly implementation dependent and therefore unspecified.

Specified by:

resolve in interface Path

Parameters:

path - the path to resolve against this path

Returns:

the resulting path

resolve

public Path resolve(String path)

Converts a given path string to a Path and resolves it against this Path in exactly the manner specified by the resolve method.

Specified by:

resolve in interface Path

Parameters:

path - the path string to resolve against this path

Returns:

the resulting path

Throws:

InvalidPathException - if the path string cannot be converted to a Path.

resolveSibling

public Path resolveSibling(Path path)

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 Path

Parameters:

path - the path to resolve against this path's parent

Returns:

the resulting path

resolveSibling

public Path resolveSibling(String path)

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 Path

Parameters:

path - the path string to resolve against this path's parent

Returns:

the resulting path

Throws:

InvalidPathException - if the path string cannot be converted to a Path.

relativize

public Path relativize(Path path)

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.

A relative path cannot be constructed if only one of the paths have a root component. If both paths have a root component, it is still possible to relativize one against the other. If this path and the given path are equal then an empty path is returned.

For any two normalized paths p and q, where q does not have a root component, p.relativize(p.resolve(q)).equals(q)

Specified by:

relativize in interface Path

Parameters:

path - the path to relativize against this path

Returns:

the resulting relative path, or an empty path if both paths are equal

Throws:

IllegalArgumentException - if other is not a Path that can be relativized against this path

toUri

public URI toUri()

Returns a URI to represent this path.

This method constructs an absolute URI with a scheme equal to the URI scheme that identifies the provider.

No authority component is defined for the URI returned by this method. This implementation offers the same equivalence guarantee as the default provider.

Specified by:

toUri in interface Path

Returns:

the URI representing this path

Throws:

SecurityException - never

toAbsolutePath

public Path 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 against the default directory.

Specified by:

toAbsolutePath in interface Path

Returns:

a Path object representing the absolute path

Throws:

SecurityException - never

toRealPath

public Path toRealPath(LinkOption... linkOptions)
                throws IOException

Unsupported.

Specified by:

toRealPath in interface Path

Parameters:

linkOptions - options

Returns:

the real path

Throws:

UnsupportedOperationException - operation not supported.

IOException

toFile

public File toFile()

Unsupported.

Specified by:

toFile in interface Path

Returns:

the file

Throws:

UnsupportedOperationException - operation not supported.

register

public WatchKey register(WatchService watchService,
                         WatchEvent.Kind<?>[] kinds,
                         WatchEvent.Modifier... modifiers)
                  throws IOException

Unsupported.

Specified by:

register in interface Path

Specified by:

register in interface Watchable

Parameters:

watchService - watchService

kinds - kinds

modifiers - modifiers

Returns:

the watch key

Throws:

UnsupportedOperationException - operation not supported.

IOException

register

public WatchKey register(WatchService watchService,
                         WatchEvent.Kind<?>... kinds)
                  throws IOException

Unsupported.

Specified by:

register in interface Path

Specified by:

register in interface Watchable

Parameters:

watchService - watchService

kinds - kinds

Returns:

the watch key

Throws:

UnsupportedOperationException - operation not supported.

IOException

iterator

public Iterator<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 Iterable<Path>

Specified by:

iterator in interface Path

Returns:

an iterator over the name elements of this path.

compareTo

public int compareTo(Path path)

Compares two abstract paths lexicographically. 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.

This result of this method is identical to a string comparison on the underlying path strings.

Specified by:

compareTo in interface Comparable<Path>

Specified by:

compareTo in interface 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:

ClassCastException - if the paths are associated with different providers

toString

public String toString()

Returns the string representation of this path.

If this path was created by converting a path string using the getPath method then the path string returned by this method may differ from the original String used to create the path.

The returned path string uses the default name separator to separate names in the path.

Specified by:

toString in interface Path

Overrides:

toString in class Object

Returns:

the string representation of this path

equals

public boolean equals(Object o)

A path is considered equal to another path if it is associated with the same file system instance and if the path strings are equivalent.

Specified by:

equals in interface Path

Overrides:

equals in class Object

Returns:

true if, and only if, the given object is a Path that is identical to this Path

hashCode

public int hashCode()

Specified by:

hashCode in interface Path

Overrides:

hashCode in class Object

toBlobClient

public BlobClient toBlobClient()
                        throws IOException

Returns a BlobClient which references a blob pointed to by this path. Note that this does not guarantee the existence of the blob at this location.

Returns:

a BlobClient.

Throws:

IOException - If the path only contains a root component or is empty

fromBlobUrl

public static AzurePath fromBlobUrl(AzureFileSystemProvider provider,
                                    String url)
                             throws URISyntaxException

A utility method to conveniently convert from a URL to a storage resource to an AzurePath pointing to the same resource. The url must be well formatted. There must be an open filesystem corresponding to the account which contains the blob. Otherwise, a FileSystemNotFoundException will be thrown. The url may point to either an account, container, or blob. If it points to an account, the path will be empty, but it will have an internal reference to the file system containing it, meaning instance methods may be performed on the path to construct a reference to another object. If it points to a container, there will be one element, which is the root element. Everything after the container, that is the blob name, will then be appended after the root element. IP style urls are not currently supported. The AzureFileSystemProvider can typically be obtained via AzureFileSystem.provider().

Parameters:

provider - The installed AzureFileSystemProvider that manages open file systems for this jvm.

url - The url to the desired resource.

Returns:

An AzurePath which points to the resource identified by the url.

Throws:

URISyntaxException - If the url contains elements which are not well formatted.