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 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 installedjava.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
-
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description boolean
equals(Object o)
protected Path
getCachedPath()
InputStream
getInputStream()
Get aInputStream
for this URI if a provider is for the URI's scheme is available.OutputStream
getOutputStream()
Get anOutputStream
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 ajava.nio.file.Path
(#isPath()
returns false).URI
getURI()
Get ajava.net.URI
object for thisIOPath
.String
getURIString()
Returns the string from which thisIOPath
was originally created.boolean
hasFileSystemProvider()
int
hashCode()
boolean
isPath()
Return true if this {code IOPath} can be resolved to anjava.nio
Path.protected void
setCachedPath(Path path)
Path
toPath()
Resolve the URI to aPath
object.String
toString()
-
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
-
Methods inherited from interface htsjdk.io.IOPath
getBaseName, getExtension, getScheme, hasExtension, isBam, isCram, isFasta, isSam
-
-
-
-
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 ajava.net.URI
object for thisIOPath
. Will not be null.
-
getURIString
public String getURIString()
Description copied from interface:IOPath
Returns the string from which thisIOPath
was originally created. This string may differ from the normalized string returned from ajava.nio.file.Path
that has been object resolved from thisIOPath
.- Specified by:
getURIString
in interfaceIOPath
- 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 interfaceIOPath
-
hasFileSystemProvider
public boolean hasFileSystemProvider()
- Specified by:
hasFileSystemProvider
in interfaceIOPath
- 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 ajava.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 anjava.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).
-
toPath
public Path toPath()
Resolve the URI to aPath
object.- Specified by:
toPath
in interfaceIOPath
- 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 ajava.nio.file.Path
(#isPath()
returns false).- Specified by:
getToPathFailureReason
in interfaceIOPath
- Returns:
- Message explaining toPath failure reason, since it can fail for various reasons.
-
getInputStream
public InputStream getInputStream()
Description copied from interface:IOPath
Get aInputStream
for this URI if a provider is for the URI's scheme is available.- Specified by:
getInputStream
in interfaceIOPath
- Returns:
InputStream
for this URI.
-
getOutputStream
public OutputStream getOutputStream()
Description copied from interface:IOPath
Get anOutputStream
for this URI if a provider is for the URI's scheme.- Specified by:
getOutputStream
in interfaceIOPath
- Returns:
OutputStream
for this URI.
-
getCachedPath
protected Path getCachedPath()
-
setCachedPath
protected void setCachedPath(Path path)
-
-