# 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>:<scheme-specific-part>` Many "hierarchical" URI schemes use this syntax: `<scheme>://<authority><path>?<query>` 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 Summary

Constructors
Constructor
Description
`HtsPath(HtsPath htsPath)`
Create an HtsPath from an existing HtsPath.
`HtsPath(String rawInputString)`
Create an HtsPath from a raw input path string.

## Method Summary

Modifier and Type
Method
Description
`boolean`
`equals(Object o)`
`protected Path`
`getCachedPath()`
`InputStream`
`getInputStream()`
Get a `InputStream` for this URI if a provider is for the URI's scheme is available.
`OutputStream`
`getOutputStream()`
Get an `OutputStream` for this URI if a provider is for the URI's scheme.
`String`
`getRawInputString()`
Return the raw input string provided to the constructor.
`String`
`getToPathFailureReason()`
Return a string message describing why this URI cannot be converted to a `java.nio.file.Path` (`#isPath()` returns false).
`URI`
`getURI()`
Get a `java.net.URI` object for this `IOPath`.
`String`
`getURIString()`
Returns the string from which this `IOPath` was originally created.
`boolean`
`hasFileSystemProvider()`
`int`
`hashCode()`
`boolean`
`isPath()`
Return true if this {code IOPath} can be resolved to an `java.nio` Path.
`protected void`
`setCachedPath(Path path)`
`Path`
`toPath()`
Resolve the URI to a `Path` object.
`String`
`toString()`

### Methods inherited from class Object

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

### Methods inherited from interface IOPath

`getBaseName, getExtension, getScheme, hasExtension, isBam, isCram, isFasta, isSam`

## 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 `java.nio` File System still can't be turned into a `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`