Package htsjdk.io

Class HtsPath

  • All Implemented Interfaces:
    IOPath, Serializable

    public class HtsPath
    extends Object
    implements IOPath, Serializable
    Default implementation for IOPath. This class takes a raw string that is to be interpreted as a path specifier, and converts it internally to a URI and/or Path object. If no scheme is provided as part of the raw string used in the constructor(s), the input is assumed to represent a file on the local file system, and will be backed by a URI with a "file:/" scheme and a path part that is automatically encoded/escaped to ensure it is a valid URI. If the raw string contains a scheme, it will be backed by a URI formed from the raw string as presented, with no further encoding/escaping. For example, a URI that contains a scheme and has an embedded "#" in the path will be treated as a URI having a fragment delimiter. If the URI contains an scheme, the "#" will be escaped and the encoded "#" will be interpreted as part of the URI path. There are 3 succeeding levels of input validation/conversion: 1) HtsPath constructor: requires a syntactically valid URI, possibly containing a scheme (if no scheme is present the path part will be escaped/encoded), or a valid local file reference 2) hasFileSystemProvider: true if the input string is an identifier that is syntactically valid, and is backed by an installed java.nio file system provider that matches the URI scheme 3) isPath: syntactically valid URI that can be resolved to a java.io.Path by the associated provider Definitions taken from RFC 2396 "Uniform Resource Identifiers (URI): Generic Syntax" (https://www.ietf.org/rfc/rfc2396.txt): "absolute" URI - specifies a scheme "relative" URI - does not specify a scheme "opaque" URI - an "absolute" URI whose scheme-specific part does not begin with a slash character "hierarchical" URI - either an "absolute" URI whose scheme-specific part begins with a slash character, or a "relative" URI (no scheme) URIs that do not make use of the slash "/" character for separating hierarchical components are considered "opaque" by the generic URI parser. General syntax for an "absolute" URI: : Many "hierarchical" URI schemes use this syntax: ://? More specifically: absoluteURI = scheme ":" ( hier_part | opaque_part ) hier_part = ( net_path | abs_path ) [ "?" query ] net_path = "//" authority [ abs_path ] abs_path = "/" path_segments opaque_part = uric_no_slash *uric uric_no_slash = unreserved | escaped | ";" | "?" | ":" | "@" | "&" | "=" | "+" | "$" | ","
    See Also:
    Serialized Form
    • Constructor Detail

      • HtsPath

        public HtsPath​(String rawInputString)
        Create an HtsPath from a raw input path string. If the raw input string already contains a scheme (including a "file" scheme), assume its already properly escape/encoded. If no scheme component is present, assume it referencess a raw path on the local file system, so try to get a Path first, and then retrieve the URI from the resulting Path. This ensures that input strings that are local file references without a scheme component and contain embedded characters are valid in file names, but which would otherwise be interpreted as excluded URI characters (such as the URI fragment delimiter "#") are properly escape/encoded.
        Parameters:
        rawInputString - a string specifying an input path. May not be null.
      • HtsPath

        public HtsPath​(HtsPath htsPath)
        Create an HtsPath from an existing HtsPath.
        Parameters:
        htsPath - an existing PathSpecifier. May not be null.
    • Method Detail

      • getURI

        public URI getURI()
        Description copied from interface: IOPath
        Get a java.net.URI object for this IOPath. Will not be null.
        Specified by:
        getURI in interface IOPath
        Returns:
        The URI object for this IOPath.
      • getURIString

        public String getURIString()
        Description copied from interface: IOPath
        Returns the string from which this IOPath was originally created. This string may differ from the normalized string returned from a java.nio.file.Path that has been object resolved from this IOPath.
        Specified by:
        getURIString in interface IOPath
        Returns:
        string from which this URI as originally created. Will not be null.
      • getRawInputString

        public String getRawInputString()
        Return the raw input string provided to the constructor.
        Specified by:
        getRawInputString in interface IOPath
      • hasFileSystemProvider

        public boolean hasFileSystemProvider()
        Specified by:
        hasFileSystemProvider in interface IOPath
        Returns:
        true if this URI has a scheme that has an installed java.nio file system provider (). This does not guarantee the URI can be converted into a java.nio.file.Path, since the URI can be syntactically valid, and specify a valid file system provider, but still fail to be semantically meaningful.
      • isPath

        public boolean isPath()
        Description copied from interface: IOPath
        Return true if this {code IOPath} can be resolved to an java.nio Path. If true, #toPath() can be safely called. There are cases where a valid URI with a valid scheme backed by an installed {@code java.nio File System still can't be turned into a {@code java.nio.file.Path}, i.e., the following specifies an invalid authority "namenode": hdfs://namenode/to/file The current implementation returns false for these cases (toPath will fail, getInvalidPathReason returns the reason code).
        Specified by:
        isPath in interface IOPath
      • toPath

        public Path toPath()
        Resolve the URI to a Path object.
        Specified by:
        toPath in interface IOPath
        Returns:
        the resulting Path
        Throws:
        RuntimeException - if an I/O error occurs when creating the file system
      • getToPathFailureReason

        public String getToPathFailureReason()
        Description copied from interface: IOPath
        Return a string message describing why this URI cannot be converted to a java.nio.file.Path (#isPath() returns false).
        Specified by:
        getToPathFailureReason in interface IOPath
        Returns:
        Message explaining toPath failure reason, since it can fail for various reasons.
      • getInputStream

        public InputStream getInputStream()
        Description copied from interface: IOPath
        Get a InputStream for this URI if a provider is for the URI's scheme is available.
        Specified by:
        getInputStream in interface IOPath
        Returns:
        InputStream for this URI.
      • getOutputStream

        public OutputStream getOutputStream()
        Description copied from interface: IOPath
        Get an OutputStream for this URI if a provider is for the URI's scheme.
        Specified by:
        getOutputStream in interface IOPath
        Returns:
        OutputStream for this URI.
      • getCachedPath

        protected Path getCachedPath()
      • setCachedPath

        protected void setCachedPath​(Path path)
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object