Package htsjdk.io

Class HtsPath

java.lang.Object
htsjdk.io.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 no 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: :<scheme-specific-part> 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:

  • Constructor Details

    • 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 Details

    • 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)

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object