Package com.globalmentor.net

Class URIPath

  • public final class URIPath
extends java.lang.Object
    Represents the path of a hierarchical URI with the same encoding requirements as URIs in general.

    Note that this class does not represent what RFC 3986 Section 4.1 calls a relative reference, because such references forbid the first path segment of relative references from containing the character 58 to prevent confusion with a URI containing a scheme. RFC 3986 Section 4.2 makes this prohibition so that a specification may call for a URI reference, which may be either a URI or a relative reference. This class represents a URI path in a context in which it is known to be a URI path and not a URI, and thus allows the 58 character to appear in the first segment of a relative path.

    Author:
    Garret Wilson
    See Also:
    Uniform Resource Identifier (URI): Generic Syntax

    • Constructor Summary

      Constructors 
      Constructor Description
      URIPath​(java.lang.String path)
      Deprecated.
      To be replaced by the static factory method of(String).
      URIPath​(java.net.URI pathURI)
      Deprecated.
      Will be made private in favor of the static factory method fromURI(URI).

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static URIPath asPathURIPath​(java.net.URI uri)
      Returns a URI path based upon the path of the given URI if the given URI uses the "path" scheme.
      URIPath checkAbsolute()
      Checks to see if the path is absolute.
      URIPath checkCollection()
      Checks to see if the path represents a collection.
      URIPath checkRelative()
      Checks to see if the path is relative.
      static java.net.URI createURIPathURI​(java.lang.String path)
      Creates a path URI consisting of the given string version of the raw path.
      static java.lang.String encode​(java.lang.String path)
      Encodes the given string so that it is a valid URI path according RFC 3986, "Uniform Resource Identifiers (URI): Generic Syntax".
      static java.lang.String encodeSegment​(java.lang.String pathSegment)
      Encodes the given string so that it is a valid URI path segment according RFC 3986, "Uniform Resource Identifiers (URI): Generic Syntax".
      boolean equals​(java.lang.Object object)
      Determines if this object equals another object.
      java.util.Optional<URIPath> findRelativePath​(URIPath targetPath)
      Returns the path of a target path relative to this path, which may be a sibling path or even a child path of the other path.
      java.util.Optional<URIPath> findRelativePath​(java.lang.String targetPath)
      Returns the path of a target path relative to this path, which may be a sibling path or even a child path of the other path.
      static java.util.Optional<URIPath> findRelativePath​(java.net.URI sourceURI, java.net.URI targetURI)
      Returns the path of a target URI relative to some source URI, which may be a sibling URI or even a child URI.
      static URIPath fromURI​(java.net.URI pathURI)
      Creates a URI path from the raw path of the given path URI.
      java.util.List<URIPath> getBasePaths()
      Parses out and returns the base paths of the path.
      URIPath getCurrentLevel()
      Determines the current level of this path.
      java.lang.String getName()
      Returns the decoded name of the resource at the given path, which will be the name of the last path component.
      URIPath getParentLevel()
      Determines the parent level of this path.
      URIPath getParentPath()
      Determines the parent path of this path.
      java.lang.String getRawName()
      Returns the raw, encoded name of the resource at the given path, which will be the name of the last path component.
      int hashCode()
      Returns the hash code of this object.
      boolean isAbsolute()
      Determines whether this path is absolute.
      boolean isCollection()
      Determines whether the path is a canonical collection path.
      boolean isEmpty()
      Determines if this is an empty path.
      boolean isRelative()
      Determines whether this path is relative.
      URIPath normalize()
      Normalizes the path by removing all . and .. segments.
      static URIPath of​(java.lang.String path)
      Creates a URI path from the given string version of the raw path.
      URIPath relativize​(URIPath targetPath)
      Returns the path of a target path relative to this path, which may be a sibling path or even a child path of the other path.
      URIPath relativize​(java.lang.String targetPath)
      Returns the path of a target path relative to this path, which may be a sibling path or even a child path of the other path.
      static URIPath relativize​(java.net.URI sourceURI, java.net.URI targetURI)
      Returns the path of a target URI relative to some source URI, which may be a sibling URI or even a child URI.
      URIPath relativizeChildPath​(URIPath path)
      Relativizes the given path against this path.
      URIPath relativizeChildPath​(java.lang.String path)
      Relativizes the given path against this path.
      URIPath resolve​(URIPath path)
      Resolves the given path against this path.
      URIPath resolve​(java.lang.String path)
      Resolves the given path against this path.
      java.net.URI resolve​(java.net.URI uri)
      Resolves the given URI against this path.
      URIPath toCollectionURIPath()
      Returns a collection form of the URI path.
      java.lang.String toDecodedString()  
      java.net.URI toPathURI()  
      URIPath toRelativeURIPath()
      Returns a relative form of the URI path.
      java.lang.String toString()  
      java.net.URI toURI()  

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • EMPTY_URI_PATH

        public static final URIPath EMPTY_URI_PATH
        The empty path ("").

      • ROOT_URI_PATH

        public static final URIPath ROOT_URI_PATH
        The path to root, consisting of a single path separator ("/").

    • Constructor Detail

      • URIPath

        @Deprecated
public URIPath​(java.lang.String path)
        Deprecated.
        To be replaced by the static factory method of(String).
        Creates a URI path from the given string version of the raw path.
        Parameters:
        path - The raw, encoded path information.
        Throws:
        java.lang.NullPointerException - if the given path is null.
        java.lang.IllegalArgumentException - if the given string violates URI RFC 2396.
        java.lang.IllegalArgumentException - if the provided path specifies a URI authority, query, and/or fragment.

      • URIPath

        @Deprecated
public URIPath​(java.net.URI pathURI)
        Deprecated.
        Will be made private in favor of the static factory method fromURI(URI).
        Creates a URI path from the raw path of the given path URI.
        Parameters:
        pathURI - The URI that represents a path.
        Throws:
        java.lang.NullPointerException - if the given path URI is null.
        java.lang.IllegalArgumentException - if the provided URI specifies a URI scheme (i.e. the URI is absolute), authority, query, and/or fragment.
        java.lang.IllegalArgumentException - if the given URI is not a path.

    • Method Detail

      • of

        public static URIPath of​(@Nonnull
                         java.lang.String path)
        Creates a URI path from the given string version of the raw path.

        This method performs special processing for relative paths that begin with a segment containing 58. This method is no more than a URI factory that compensates for a path known to be a path and not a URI and that may contain a 58 in its relative first segment.

        Parameters:
        path - The raw, encoded path information.
        Returns:
        A URI path representing the given raw path string.
        Throws:
        java.lang.NullPointerException - if the given path is null.
        java.lang.IllegalArgumentException - if the given string violates URI RFC 2396.
        java.lang.IllegalArgumentException - if the provided path specifies a URI authority, query, and/or fragment.
        See Also:
        createURIPathURI(String)

      • fromURI

        public static URIPath fromURI​(java.net.URI pathURI)
        Creates a URI path from the raw path of the given path URI.
        Parameters:
        pathURI - The URI that represents a path.
        Returns:
        A URI path from the raw path of the given path URI.
        Throws:
        java.lang.NullPointerException - if the given path URI is null.
        java.lang.IllegalArgumentException - if the provided URI specifies a URI scheme (i.e. the URI is absolute), authority, query, and/or fragment.
        java.lang.IllegalArgumentException - if the given URI is not a path.
        See Also:
        URIs.checkPathURI(URI)

      • isAbsolute

        public boolean isAbsolute()
        Determines whether this path is absolute.
        Returns:
        true if the path begins with URIs.ROOT_PATH.
        See Also:
        isRelative()

      • isRelative

        public boolean isRelative()
        Determines whether this path is relative.
        Returns:
        true if the path does not begin with URIs.ROOT_PATH.
        See Also:
        isAbsolute()

      • checkAbsolute

        public URIPath checkAbsolute()
                      throws java.lang.IllegalArgumentException
        Checks to see if the path is absolute. If the path is not absolute, an exception is thrown.
        Returns:
        This path.
        Throws:
        java.lang.IllegalArgumentException - if the path is not absolute.
        See Also:
        isAbsolute()

      • isCollection

        public boolean isCollection()
        Determines whether the path is a canonical collection path.
        Returns:
        true if the path ends with a slash ('/').

      • checkCollection

        public URIPath checkCollection()
                        throws java.lang.IllegalArgumentException
        Checks to see if the path represents a collection. If the path does not represent a collection, an exception is thrown.
        Returns:
        This path.
        Throws:
        java.lang.IllegalArgumentException - if the path does not end with a slash ('/').
        See Also:
        isCollection()

      • isEmpty

        public boolean isEmpty()
        Determines if this is an empty path.
        Returns:
        true if this path is the empty path.

      • checkRelative

        public URIPath checkRelative()
                      throws java.lang.IllegalArgumentException
        Checks to see if the path is relative. If the path is not relative, an exception is thrown.
        Returns:
        This path.
        Throws:
        java.lang.IllegalArgumentException - if the path is absolute.
        See Also:
        isRelative()

      • normalize

        public URIPath normalize()
        Normalizes the path by removing all . and .. segments.

        This method works correctly with Windows UNC path URIs.

        Returns:
        A URI path equivalent to this URI path, but in normal form.
        See Also:
        URIs.normalize(URI)

      • getCurrentLevel

        public URIPath getCurrentLevel()
        Determines the current level of this path. This is equivalent to resolving the path "." to this path.
        Returns:
        A path representing the current hierarchical level this path.

      • getParentLevel

        public URIPath getParentLevel()
        Determines the parent level of this path. This is equivalent to resolving the path ".." to this path.
        Returns:
        A path representing the parent hierarchical level of a hierarchical URI; equivalent to resolving the path ".." to the URI.

      • getParentPath

        public URIPath getParentPath()
        Determines the parent path of this path.
        Returns:
        A path representing the parent collection of this path; if the path ends in '/', equivalent to resolving the path ".." to the path; if the path does not end in '/', equivalent to resolving the path "." to the path.
        Throws:
        java.lang.IllegalArgumentException - if the URI does not have a path component.
        See Also:
        isCollection(), getParentLevel(), getParentPath()

      • relativizeChildPath

        public URIPath relativizeChildPath​(java.lang.String path)
        Relativizes the given path against this path.
        Implementation Specification:
        This is a convenience method that functions by creating a new URIPath from the given string and delegating to relativizeChildPath(URIPath).
        Parameters:
        path - The path to be relativized against this path.
        Returns:
        The resulting path.
        Throws:
        java.lang.NullPointerException - if the given path is null.
        See Also:
        of(String)

      • relativizeChildPath

        public URIPath relativizeChildPath​(URIPath path)
        Relativizes the given path against this path.
        Parameters:
        path - The path to be relativized against this path.
        Returns:
        The resulting path.
        Throws:
        java.lang.NullPointerException - if the given path is null.

      • relativize

        public URIPath relativize​(@Nonnull
                          java.lang.String targetPath)
        Returns the path of a target path relative to this path, which may be a sibling path or even a child path of the other path. A path relativized against itself will return an empty path. A non-collection URI relativized against its parent will return ./. Otherwise if this path is not a parent of (or the same path as) the target path, the path will backtrack using .. path segments as appropriate.
        Implementation Specification:
        This is a convenience method that functions by creating a new URIPath from the given string and delegating to relativize(URIPath).
        Implementation Note:
        This implementation properly relativizes URIs that require backtracking, such as siblings, unlike Java URI relativization methods; see JDK-6226081., This method differs from URI.relativize(URI), which would return an empty URI when relativizing foo/bar against foo/. This method instead would return ./, compliant with browser relative resolution behavior and with RFC 3986, as discussed at Is Java's URI.resolve incompatible with RFC 3986 when the relative URI contains an empty path?.
        Parameters:
        targetPath - The path that will be relativized against this path.
        Returns:
        The relative path of the source URI to the target URI, or the given target path if the two paths have no base in common.
        Throws:
        java.lang.NullPointerException - if the given path string is null.
        See Also:
        URIs.findRelativePath(URI, URI)

      • findRelativePath

        public java.util.Optional<URIPath> findRelativePath​(@Nonnull
                                                    java.lang.String targetPath)
        Returns the path of a target path relative to this path, which may be a sibling path or even a child path of the other path. A path relativized against itself will return an empty path. A non-collection URI relativized against its parent will return ./. Otherwise if this path is not a parent of (or the same path as) the target path, the path will backtrack using .. path segments as appropriate.
        Implementation Specification:
        This is a convenience method that functions by creating a new URIPath from the given string and delegating to findRelativePath(URIPath).
        Implementation Note:
        This implementation properly relativizes URIs that require backtracking, such as siblings, unlike Java URI relativization methods; see JDK-6226081., This method differs from URI.relativize(URI), which would return an empty URI when relativizing foo/bar against foo/. This method instead would return ./, compliant with browser relative resolution behavior and with RFC 3986, as discussed at Is Java's URI.resolve incompatible with RFC 3986 when the relative URI contains an empty path?.
        Parameters:
        targetPath - The path that will be relativized against this path.
        Returns:
        The relative path of the source URI to the target URI, which will not be present if the two paths have no base in common.
        Throws:
        java.lang.NullPointerException - if the given path string is null.
        See Also:
        URIs.findRelativePath(URI, URI)

      • relativize

        public URIPath relativize​(@Nonnull
                          URIPath targetPath)
        Returns the path of a target path relative to this path, which may be a sibling path or even a child path of the other path. A path relativized against itself will return an empty path. A non-collection URI relativized against its parent will return ./. Otherwise if this path is not a parent of (or the same path as) the target path, the path will backtrack using .. path segments as appropriate.
        Implementation Note:
        This implementation properly relativizes URIs that require backtracking, such as siblings, unlike Java URI relativization methods; see JDK-6226081., This method differs from URI.relativize(URI), which would return an empty URI when relativizing foo/bar against foo/. This method instead would return ./, compliant with browser relative resolution behavior and with RFC 3986, as discussed at Is Java's URI.resolve incompatible with RFC 3986 when the relative URI contains an empty path?.
        Parameters:
        targetPath - The path that will be relativized against this path.
        Returns:
        The relative path of the source URI to the target URI, or the target path if the two paths have no base in common.
        Throws:
        java.lang.NullPointerException - if the given target path is null.
        See Also:
        URIs.findRelativePath(URI, URI)

      • findRelativePath

        public java.util.Optional<URIPath> findRelativePath​(@Nonnull
                                                    URIPath targetPath)
        Returns the path of a target path relative to this path, which may be a sibling path or even a child path of the other path. A path relativized against itself will return an empty path. A non-collection URI relativized against its parent will return ./. Otherwise if this path is not a parent of (or the same path as) the target path, the path will backtrack using .. path segments as appropriate.
        Implementation Note:
        This implementation properly relativizes URIs that require backtracking, such as siblings, unlike Java URI relativization methods; see JDK-6226081., This method differs from URI.relativize(URI), which would return an empty URI when relativizing foo/bar against foo/. This method instead would return ./, compliant with browser relative resolution behavior and with RFC 3986, as discussed at Is Java's URI.resolve incompatible with RFC 3986 when the relative URI contains an empty path?.
        Parameters:
        targetPath - The path that will be relativized against this path.
        Returns:
        The relative path of the source URI to the target URI, which will not be present if the two paths have no base in common.
        Throws:
        java.lang.NullPointerException - if the given target path is null.
        See Also:
        URIs.findRelativePath(URI, URI)

      • relativize

        public static URIPath relativize​(@Nonnull
                                 java.net.URI sourceURI,
                                 @Nonnull
                                 java.net.URI targetURI)
        Returns the path of a target URI relative to some source URI, which may be a sibling URI or even a child URI. A collection URI relativized against itself will return an empty path. A non-collection URI relativized against its parent will return ./. Otherwise if the source URI is not a parent of (or the same URI as) the target URI, the path will backtrack using .. path segments as appropriate.
        Implementation Specification:
        This implementation delegates to findRelativePath(URI, URI)
        Implementation Note:
        This implementation properly relativizes URIs that require backtracking, such as siblings, unlike Java URI relativization methods; see JDK-6226081., This method differs from URI.relativize(URI), which would return an empty URI when relativizing foo/bar against foo/. This method instead would return ./, compliant with browser relative resolution behavior and with RFC 3986, as discussed at Is Java's URI.resolve incompatible with RFC 3986 when the relative URI contains an empty path?.
        Parameters:
        sourceURI - The URI to which the other URI will be relativized.
        targetURI - The URI that will be relativized against the base URI.
        Returns:
        The relative path of the source URI to the target URI.
        Throws:
        java.lang.NullPointerException - if the given source URI and/or target URI is null.
        java.lang.IllegalArgumentException - if the given base URI is not actually a base URI of the given URI.
        See Also:
        URIs.relativizePath(URI, URI)

      • findRelativePath

        public static java.util.Optional<URIPath> findRelativePath​(@Nonnull
                                                           java.net.URI sourceURI,
                                                           @Nonnull
                                                           java.net.URI targetURI)
        Returns the path of a target URI relative to some source URI, which may be a sibling URI or even a child URI. A collection URI relativized against itself will return an empty path. A non-collection URI relativized against its parent will return ./. Otherwise if the source URI is not a parent of (or the same URI as) the target URI, the path will backtrack using .. path segments as appropriate.
        Implementation Note:
        This implementation properly relativizes URIs that require backtracking, such as siblings, unlike Java URI relativization methods; see JDK-6226081., This method differs from URI.relativize(URI), which would return an empty URI when relativizing foo/bar against foo/. This method instead would return ./, compliant with browser relative resolution behavior and with RFC 3986, as discussed at Is Java's URI.resolve incompatible with RFC 3986 when the relative URI contains an empty path?.
        Parameters:
        sourceURI - The URI to which the other URI will be relativized.
        targetURI - The URI that will be relativized against the base URI.
        Returns:
        The relative path of the source URI to the target URI, which will not be present if the two URIs have no base in common.
        Throws:
        java.lang.NullPointerException - if the given source URI and/or target URI is null.
        See Also:
        URIs.findRelativePath(URI, URI)

      • resolve

        public final URIPath resolve​(java.lang.String path)
        Resolves the given path against this path.

        This method works correctly with Windows UNC path URIs.

        Implementation Specification:
        This is a convenience method that functions by creating a new URIPath from the given string and delegating to resolve(URIPath).
        Parameters:
        path - The path to be resolved against this path.
        Returns:
        The resulting path.
        Throws:
        java.lang.NullPointerException - if the given path is null.
        java.lang.IllegalArgumentException - if the given string violates URI RFC 2396.
        java.lang.IllegalArgumentException - if the provided path specifies a URI scheme (i.e. the path represents an absolute URI) and/or authority.
        See Also:
        of(String), resolve(URIPath)

      • resolve

        public URIPath resolve​(URIPath path)
        Resolves the given path against this path.

        This method works correctly with Windows UNC path URIs.

        Parameters:
        path - The path to be resolved against this path.
        Returns:
        The resulting path.
        Throws:
        java.lang.NullPointerException - if the given path is null.
        See Also:
        URIs.resolve(URI, String)

      • resolve

        public java.net.URI resolve​(java.net.URI uri)
        Resolves the given URI against this path.

        This method works correctly with Windows UNC path URIs.

        Parameters:
        uri - The uri to be resolved against this path.
        Returns:
        The resulting URI.
        Throws:
        java.lang.NullPointerException - if the given URI is null.
        See Also:
        URIs.resolve(URI, URI)

      • getRawName

        public java.lang.String getRawName()
        Returns the raw, encoded name of the resource at the given path, which will be the name of the last path component. If the path is a collection (i.e. it ends with slash), the component before the last slash will be returned. As examples, "/path/name.ext" and "name.ext" will return "name.ext". "/path/", "path/", and "path" will all return "path".
        Returns:
        The raw name of the last last path component, the empty string if the path is the empty string, or "/" if the path is the root path.

      • getName

        public java.lang.String getName()
        Returns the decoded name of the resource at the given path, which will be the name of the last path component. If the path is a collection (i.e. it ends with slash), the component before the last slash will be returned. As examples, "/path/name.ext" and "name.ext" will return "name.ext". "/path/", "path/", and "path" will all return "path".
        Returns:
        The decoded name of the last last path component, the empty string if the path is the empty string, or "/" if the path is the root path.

      • toURI

        public java.net.URI toURI()
        Returns:
        A path-only URI containing this URI path.

      • toPathURI

        public java.net.URI toPathURI()
        Returns:
        A URI containing this URI path in the "path" scheme.
        See Also:
        URIs.PATH_SCHEME

      • asPathURIPath

        public static URIPath asPathURIPath​(java.net.URI uri)
        Returns a URI path based upon the path of the given URI if the given URI uses the "path" scheme.
        Parameters:
        uri - The URI to examine as a path URI.
        Returns:
        The path of the URI if the URI is absolute and has the "path" scheme, otherwise null.
        See Also:
        URIs.PATH_SCHEME

      • toCollectionURIPath

        public URIPath toCollectionURIPath()
        Returns a collection form of the URI path. If the URI path already is a collection path, it is returned unmodified. Otherwise, a path separator is appended to the URI path.
        Returns:
        A form of the URI path that indicates a collection.

      • toRelativeURIPath

        public URIPath toRelativeURIPath()
        Returns a relative form of the URI path. If the URI path already is already a relative path, it is returned unmodified. Otherwise, the beginning separator is removed from the URI path.
        Returns:
        A form of the URI path that is relative.

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
        Returns:
        A string representation of the raw, encoded path as it would appear in a URI.

      • toDecodedString

        public java.lang.String toDecodedString()
        Returns:
        A string representation of the path with any URI escape sequences decoded.

      • hashCode

        public int hashCode()
        Returns the hash code of this object.
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        The hash code of this object.

      • equals

        public boolean equals​(java.lang.Object object)
        Determines if this object equals another object.
        Overrides:
        equals in class java.lang.Object
        Parameters:
        object - The object to compare with this object.
        Returns:
        true if the given object is considered equal to this object.

      • createURIPathURI

        public static java.net.URI createURIPathURI​(java.lang.String path)
        Creates a path URI consisting of the given string version of the raw path. This method performs special processing for relative paths that begin with a segment containing 58. This method is no more than a URI factory that compensates for a path known to be a path and not a URI and that may contain a 58 in its relative first segment.
        Parameters:
        path - The raw, encoded path information.
        Returns:
        The path URI constructed from its given string version.
        Throws:
        java.lang.NullPointerException - if the given path is null.
        java.lang.IllegalArgumentException - if the given string violates URI RFC 2396.

      • encode

        public static java.lang.String encode​(java.lang.String path)
        Encodes the given string so that it is a valid URI path according RFC 3986, "Uniform Resource Identifiers (URI): Generic Syntax".
        Parameters:
        path - The path to URI-encode.
        Returns:
        A string containing the escaped data.

      • encodeSegment

        public static java.lang.String encodeSegment​(java.lang.String pathSegment)
        Encodes the given string so that it is a valid URI path segment according RFC 3986, "Uniform Resource Identifiers (URI): Generic Syntax".
        Parameters:
        pathSegment - The path segment to URI-encode.
        Returns:
        A string containing the escaped data.

      • getBasePaths

        public java.util.List<URIPath> getBasePaths()
        Parses out and returns the base paths of the path. Collection segments will end with the path separator 47. The returned list will never be empty.

        For example, the path one/two/three will result in the base paths one/, one/two/, and one/two/three.

        The empty URI path and the root URI path / will each return a list containing only the URI path itself.

        Returns:
        The segments of the URI path.
        See Also:
        EMPTY_URI_PATH, ROOT_URI_PATH