URI and Path specifier classes for input/output resources.

build.gradle

@@ -30,6 +30,9 @@ subprojects {
 
     dependencies {
         testCompile "org.testng:testng:6.14.3"
+        testCompile "com.google.jimfs:jimfs:1.1"
+
+        compile 'commons-io:commons-io:2.5'
     }
 
     test {

core/src/main/java/org/htsjdk/core/api/PathURI.java

@@ -0,0 +1,86 @@
+package org.htsjdk.core.api;
+
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.net.URI;
+import java.nio.file.Path;
+
+/**
+ * Interface representing htsjdk-next input/output resources as URIs.
+ */
+public interface PathURI {
+
+    /**
+     * @return true if this URI has a scheme that has an installed NIO file system provider. This does not
+     * guarantee the URI can be converted into a {@code 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.
+     */
+    boolean isNIO();
+
+    /**
+     * Return true if this {code PathURI} can be resolved to an NIO Path. If true, {@code #toPath()} can be
+     * safely called.
+     *
+     * There are cases where a valid URI with a valid scheme backed by an installed 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).
+     */
+    boolean isPath();
+
+    /**
+     * Get a {@code java.net.URI} object for this {@code PathURI}. Will not be null.
+     * @return The {@code URI} object for this PathURI.
+     */
+    URI getURI();
+
+    /**
+     * Returns the string from which this {@code PathURI} was originally created. This string may differ from
+     * the normalized string returned from a Path that has been object resolved from this PathURI.
+     * @return string from which this URI as originally created. Will not be null, and will always
+     * include a URI scheme.
+     */
+    String getURIString();
+
+    /**
+     * Return the raw input string provided to the constructor.
+     */
+    String getRawInputString();
+
+    /**
+     * Resolve this PathURI to an NIO Path. Can be safely called only if {@code #isPath()} returns true.
+     */
+    Path toPath();
+
+    /**
+     * Return a string message describing why this URI cannot be converted to a {@code java.nio.file.Path}
+     * ({@code #isPath()} returns false).
+     * @return Message explaining toPath failure reason, since it can fail for various reasons.
+     */
+    String getToPathFailureReason();
+
+    /**
+     * Return the scheme for this PathURI. For file URIs (URIs that have no explicit scheme), this will return
+     * the scheme "file".
+     * @return the scheme String or this URI, if any. May be null.
+     */
+    default String getScheme() {
+        return getURI().getScheme();
+    }
+
+    /**
+     * Get a {@code InputStream} for this URI if a provider is for the URI's scheme is available.
+     * @return {@code InputStream} for this URI.
+     */
+    InputStream getInputStream();
+
+    /**
+     * Get an {@code OutputStream} for this URI if a provider is for the URI's scheme.
+     * @return {@code OutputStream} for this URI.
+     */
+    OutputStream getOutputStream();
+}

core/src/main/java/org/htsjdk/core/utils/IOUtils.java

@@ -0,0 +1,21 @@
+package org.htsjdk.core.utils;
+
+import java.io.File;
+import java.io.IOException;
+
+public class IOUtils {
+
+    /**
+     * Create a temporary file using a given name prefix and name suffix.
+     * @param prefix
+     * @param suffix
+     * @return temp File that will be deleted on exit
+     * @throws IOException
+     */
+    public static File createTempFile(final String prefix, final String suffix) throws IOException {
+        final File tempFile = File.createTempFile("testOutputStream", ".txt");
+        tempFile.deleteOnExit();
+        return tempFile;
+    }
+
+}

core/src/main/java/org/htsjdk/core/utils/PathSpecifier.java

@@ -0,0 +1,238 @@
+package org.htsjdk.core.utils;
+
+import org.htsjdk.core.api.PathURI;
+import org.htsjdk.core.exception.HtsjdkException;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.io.Serializable;
+import java.net.URI;
+import java.net.URISyntaxException;
+import java.nio.file.*;
+import java.nio.file.spi.FileSystemProvider;
+
+/**
+ * Default implementation for PathURI.
+ *
+ * This class takes a raw string that is to be interpreted as a path specifier, and converts it internally to a URI or
+ * Path object. If no scheme is provided as part of the raw string used in the constructor(s), the URI 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 having a
+ * fragment delimiter. If the URI contains an scheme, the "#" will be escaped.
+ *
+ * There are 3 succeeding levels of validation:
+ *
+ * 1) PathSpecifier constructor - requires a syntactically valid URI, possibly containing a scheme (if no scheme
+ * is present the path part will be escaped/encoded)
+ * 2) isNio - returns true if the URI is syntactically valid, and there is an installed NIO provider that matches
+ * the URI scheme
+ * 3) isPath - syntactically valid URI that can be resolved to a java.io.Path by the provider
+ *
+ * <scheme>:<scheme-specific-part>
+ * <scheme>://<authority><path>?<query>
+ *  absoluteURI   = scheme ":" ( hier_part | opaque_part )
+ *       hier_part     = ( net_path | abs_path ) [ "?" query ]
+ *       net_path      = "//" authority [ abs_path ]
+ *       abs_path      = "/"  path_segments
+ *
+ * A URI is absolute if, and only if, it has a scheme component.
+ * A URI is opaque if, and only if, it is absolute (has a scheme) and its
+ * scheme-specific part does not begin with a slash character ('/')
+ *
+ * A relative reference that does not begin with a scheme name or a
+ * slash character is termed a relative-path reference.
+ *
+ * A relative reference beginning with a single slash character is
+ * termed an absolute-path reference, as defined by <abs_path> in
+ * Section 3.
+ *
+ * URI that do not make use of the slash "/" character for separating
+ * hierarchical components are considered opaque by the generic URI
+ * parser.
+ */
+public class PathSpecifier implements PathURI, Serializable {
+    private static final long serialVersionUID = 1L;
+
+    private final String    rawInputString;     // raw input string provided by th user; may or may not have a scheme
+    private final URI uri;                      // working URI; always has a scheme (assume "file" if not provided)
+    private String          pathFailureReason;  // cache the reason for "toPath" conversion failure
+
+    private transient Path cachedPath;         // cache the Path associated with this URI if its "Path-able"
+
+    public PathSpecifier(final String rawInputString) {
+        ParamUtils.nonNull(rawInputString);
+        this.rawInputString = rawInputString;
+
+        URI tempURI;
+        try {
+            // If the input URI already has a scheme (including a "file" scheme), we assume its already properly
+            // escaped. If no scheme component is present, then assume its a raw path on the local file system, so
+            // try to get a Path first, and then recreate the URI by retrieving it from the resulting Path. This
+            // ensures that input strings that contain embedded characters that would otherwise be interpreted as
+            // URI syntax (such as embedded fragment specifiers ("#") that are valid in file names) are properly
+            // escaped.
+            tempURI = new URI(rawInputString);
+            if (!tempURI.isAbsolute()) {
+                // NOTE: This case (no scheme) is the only one where we resolve the URI to a Path at construction time.
+                try {
+                    setCachedPath(Paths.get(rawInputString));
+                    tempURI = getCachedPath().toUri();
+                } catch (InvalidPathException e) {
+                    throw new IllegalArgumentException(e.getMessage(), e);
+                }
+            }
+            uri = tempURI;
+            if (!uri.isAbsolute()) {
+                // assert the invariant that every URI we create has a scheme, even if the raw input string does not
+                throw new HtsjdkException("URI has no scheme");
+            }
+        } catch (URISyntaxException e) {
+            final String errorMessage = String.format("%s must be a valid URI. '%s'/'%s'", rawInputString, e.getMessage(), e.getReason());
+            throw new IllegalArgumentException(errorMessage);
+        }
+    }
+
+    @Override
+    public boolean isNIO() {
+        // try to find a provider; assume that our URI always has a scheme
+        for (FileSystemProvider provider: FileSystemProvider.installedProviders()) {
+            if (provider.getScheme().equalsIgnoreCase(uri.getScheme())) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    @Override
+    public boolean isPath() {
+        try {
+            return getCachedPath() != null || toPath() != null;
+        } catch (ProviderNotFoundException |
+                FileSystemNotFoundException |
+                IllegalArgumentException |
+                HtsjdkException |
+                AssertionError e) {
+            // jimfs throws an AssertionError that wraps a URISyntaxException when trying to create path where
+            // the scheme-specific part is missing or incorrect
+            pathFailureReason = e.getMessage();
+            return false;
+        }
+    }
+
+    @Override
+    public URI getURI() {
+        return uri;
+    }
+
+    @Override
+    public String getURIString() {
+        return getURI().toString();
+    }
+
+    /**
+     * Return the raw input string as provided to the constructor.
+     */
+    @Override
+    public String getRawInputString() { return rawInputString; }
+
+    /**
+     * Resolve the URI to a {@link Path} object.
+     *
+     * @return the resulting {@code Path}
+     * @throws HtsjdkException if an I/O error occurs when creating the file system
+     */
+    @Override
+    public Path toPath() {
+        if (getCachedPath() != null) {
+            return getCachedPath();
+        } else {
+            final Path tmpPath = Paths.get(getURI());
+            setCachedPath(tmpPath);
+            return tmpPath;
+        }
+    }
+
+    @Override
+    public String getToPathFailureReason() {
+        if (pathFailureReason == null) {
+            try {
+                toPath();
+                return String.format("'%s' appears to be a valid Path", rawInputString);
+            } catch (ProviderNotFoundException e) {
+                return String.format("ProviderNotFoundException: %s", e.getMessage());
+            } catch (FileSystemNotFoundException e) {
+                return String.format("FileSystemNotFoundException: %s", e.getMessage());
+            } catch (IllegalArgumentException e) {
+                return String.format("IllegalArgumentException: %s", e.getMessage());
+            } catch (HtsjdkException e) {
+                return String.format("UserException: %s", e.getMessage());
+            }
+        }
+        return pathFailureReason;
+    }
+
+    @Override
+    public InputStream getInputStream() {
+        if (!isPath()) {
+            throw new HtsjdkException(getToPathFailureReason());
+        }
+
+        final Path resourcePath = toPath();
+        try {
+            return Files.newInputStream(resourcePath);
+        } catch (IOException e) {
+            throw new HtsjdkException(
+                    String.format("Could not create open input stream for %s (as URI %s)", getRawInputString(), getURIString()), e);
+        }
+    }
+
+    @Override
+    public OutputStream getOutputStream() {
+        if (!isPath()) {
+            throw new HtsjdkException(getToPathFailureReason());
+        }
+
+        final Path resourcePath = toPath();
+        try {
+            return Files.newOutputStream(resourcePath);
+        } catch (IOException e) {
+            throw new HtsjdkException(String.format("Could not open output stream for %s (as URI %s)", getRawInputString(), getURIString()), e);
+        }
+    }
+
+    // get the cached path associated with this URI if its already been created
+    protected Path getCachedPath() { return cachedPath; }
+
+    protected void setCachedPath(Path path) {
+        this.cachedPath = path;
+    }
+
+    @Override
+    public String toString() {
+        return rawInputString;
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) return true;
+        if (!(o instanceof PathSpecifier)) return false;
+
+        PathSpecifier that = (PathSpecifier) o;
+
+        if (!getURIString().equals(that.getURIString())) return false;
+        if (!getURI().equals(that.getURI())) return false;
+        return true;
+    }
+
+    @Override
+    public int hashCode() {
+        int result = getURIString().hashCode();
+        result = 31 * result + getURI().hashCode();
+        return result;
+    }
+
+}