Class FSRL

  • Direct Known Subclasses:
    FSRLRoot

    public class FSRL
    extends java.lang.Object
    A _F_ile _S_ystem _R_esource _L_ocator, (name and string format patterned after URLs)

    Used to locate a resource (by name) on a "filesystem", in a recursively nested fashion.

    The string format of FSRLs is fstype + "://" + path + optional_MD5 [ + "|" pipe + FSRL ]*

    See fromPartString(FSRL, String) for more format info.

    Read the string format from right-to-left for easiest understanding... ie. "file://z|y://x" reads as "file x inside a filesystem y inside a container file z".

    FSRL instances are immutable and thread-safe.

    Examples (pipes shown in red since they are hard to see):

    • file://dir/subdir -- simplest example, locates a file on local computer filesystem.
    • file://dir/subdir/example.zip|zip://readme.txt -- points to a file named "readme.txt" in a zip file.
    • file://dir/subdir/example.zip|zip://dir/nested.tar|tar://file.txt -- points to a file inside a TAR archive, which is inside a ZIP archive, which is on the local filesystem.
    • file://dir/subdir/example.zip?MD5=1234567|zip://readme.txt?MD5=987654 -- points to a file named "readme.txt" (with a MD5 hash) in a zip file (that has another MD5 hash).

    See FSRLRoot for examples of how FSRL and FSRLRoot's are related.

    FSRL's can be created either piecemeal, from the bottom up, starting with a root filesystem FSRL and calling appendPath(String) or FSRLRoot.nestedFS(FSRL, String) methods to create deeper and deeper nested FSRLs,

    or

    FSRL's can be created from strings using fromString(String).

    FSRLs that have a MD5 value are "fully qualified".

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String PARAM_MD5  
      protected FSRL parent  
      protected java.lang.String path  
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected FSRL​(FSRL parent, java.lang.String path)
      Protected constructor called by static factory methods such as fromString(String) or methods that return a new instance such as withPath(String).
      protected FSRL​(FSRL parent, java.lang.String path, java.lang.String md5)
      Protected constructor called by static factory methods such as fromString(String) or methods that return a new instance such as withPath(String).
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      FSRL appendPath​(java.lang.String relPath)
      Creates a new FSRL instance, using the same FSRLRoot as this instance, combining the current path with the relPath value.
      protected void appendToStringBuilder​(java.lang.StringBuilder sb, boolean recurse, boolean includeParams, boolean includeFSRoot)  
      static FSRL convertRootToContainer​(FSRL fsrl)
      Ensures that a FSRL instance is a file type reference by converting any FSRLRoots into the container file that hosts the FSRLRoot.
      boolean equals​(java.lang.Object obj)  
      static FSRL fromString​(FSRL parent, java.lang.String fsrlStr)
      Creates a FSRL from a raw string.
      static FSRL fromString​(java.lang.String fsrlStr)
      Creates a FSRL from a raw string.
      FSRLRoot getFS()
      Returns the FSRLRoot object that represents the entire filesystem for this FSRL.
      java.lang.String getMD5()
      Returns the MD5 string associated with this file.
      java.lang.String getName()
      Returns the name portion of this FSRL's path, everything after the last '/'
      java.lang.String getName​(int nestedDepth)
      Returns the name portion of the FSRL part at parent depth nestedDepth, where 0 is ourself (equiv to just calling getName(), 1 is the parent container's name, etc.
      int getNestingDepth()
      Returns the number of FSRLRoots there are in this FSRL.
      java.lang.String getPath()
      Returns the full path/filename of this FSRL.
      int hashCode()  
      boolean isDescendantOf​(FSRL potentialParent)
      Returns true if this object is a child or descendant of the specified potentialParent parameter.
      boolean isEquivalent​(FSRL other)
      Returns true if the two FSRLs are the same, excluding any MD5 values.
      boolean isEquivalent​(java.lang.String fsrlStr)
      Returns true if the two FSRLs are the same, excluding any MD5 values.
      boolean isMD5Equal​(java.lang.String otherMD5)
      Tests specified MD5 value against MD5 in this FSRL.
      FSRLRoot makeNested​(java.lang.String fstype)
      Creates a new FSRLRoot instance that is a child of this FSRL.
      java.util.List<FSRL> split()
      Splits a FSRL into a List, with each element pointing to each level of the full FSRL.
      java.lang.String toPrettyFullpathString()
      Returns a string containing the full FSRL, without FS "fstype://" portions
      java.lang.String toPrettyString()
      Returns a string containing the full FSRL, excluding MD5 portions.
      java.lang.String toString()
      Returns a string containing the full FSRL.
      java.lang.String toStringPart()
      Returns a string containing just the current FSRL protocol and path.
      FSRL withMD5​(java.lang.String newMD5)
      Creates a new FSRL instance, using the same information as this instance, but with a new MD5 value.
      FSRL withPath​(FSRL copyPath)
      Creates a new FSRL instance using the same path and other metadata present in the copyPath instance.
      FSRL withPath​(java.lang.String newpath)
      Creates a new FSRL instance, using the same FSRLRoot as this instance, but with a new path.
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait
    • Field Detail

      • parent

        protected final FSRL parent
      • path

        protected final java.lang.String path
    • Constructor Detail

      • FSRL

        protected FSRL​(FSRL parent,
                       java.lang.String path)
        Protected constructor called by static factory methods such as fromString(String) or methods that return a new instance such as withPath(String).
        Parameters:
        parent - FSRL parent, null if this instance is root FSRLRoot
        path - String path, meaning dependent on context
      • FSRL

        protected FSRL​(FSRL parent,
                       java.lang.String path,
                       java.lang.String md5)
        Protected constructor called by static factory methods such as fromString(String) or methods that return a new instance such as withPath(String).
        Parameters:
        parent - FSRL parent, null if this instance is root FSRLRoot
        path - String path, meaning dependent on context
        md5 - hex string with the md5 hash of the file this FSRL points to, null ok.
    • Method Detail

      • fromString

        public static FSRL fromString​(java.lang.String fsrlStr)
                               throws java.net.MalformedURLException
        Creates a FSRL from a raw string. The parent portions of the FSRL are not intern()'d so will not be shared with other FSRL instances.

        See fromPartString(FSRL, String) for details of character encoding fixups.

        Parameters:
        fsrlStr - something like "fstype://path/path|fs2type://path2/path2|etc://etc/etc"
        Returns:
        new FSRL instance, never null
        Throws:
        java.net.MalformedURLException - if empty string or bad format
      • fromString

        public static FSRL fromString​(FSRL parent,
                                      java.lang.String fsrlStr)
                               throws java.net.MalformedURLException
        Creates a FSRL from a raw string.

        See fromPartString(FSRL, String) for details of character encoding fixups.

        Parameters:
        parent - Parent FSRL
        fsrlStr - something like "fstype://path/path|fs2type://path2/path2|etc://etc/etc"
        Returns:
        new FSRL instance, never null
        Throws:
        java.net.MalformedURLException - if empty string or bad format
      • convertRootToContainer

        public static FSRL convertRootToContainer​(FSRL fsrl)
        Ensures that a FSRL instance is a file type reference by converting any FSRLRoots into the container file that hosts the FSRLRoot.
        Parameters:
        fsrl - FSRL or FSRLRoot instance to possibly convert
        Returns:
        original FSRL if already a normal FSRL, or the container if it was a FSRLRoot
      • getFS

        public FSRLRoot getFS()
        Returns the FSRLRoot object that represents the entire filesystem for this FSRL.

        Never returns NULL, and calling getFS() on a FSRLRoot object returns itself.

        Returns:
        FSRLRoot instance that is the parent of this FSRL, never null.
      • getNestingDepth

        public int getNestingDepth()
        Returns the number of FSRLRoots there are in this FSRL.

        A single level FSRL such as "file://path" will return 1.
        A two level FSRL such as "file://path|subfs://path2" will return 2.
        etc.

        Returns:
        number of levels in this FSRL, min value returned is 1.
      • getPath

        public java.lang.String getPath()
        Returns the full path/filename of this FSRL. Does not include parent filesystem path or info.

        "file://path|subfs://subpath/blah" returns "/subpath/blah"

        May return null if this instance is a FSRLRoot.

        Returns:
        string path and filename of this object. Null if this FSRL is a FSRLRoot.
      • getName

        public java.lang.String getName()
        Returns the name portion of this FSRL's path, everything after the last '/'

        "file://path/name.ext" returns "name.ext"

        Returns:
        name portion of this FSRL path, or null if path is null also.
      • getName

        public java.lang.String getName​(int nestedDepth)
                                 throws java.io.IOException
        Returns the name portion of the FSRL part at parent depth nestedDepth, where 0 is ourself (equiv to just calling getName(), 1 is the parent container's name, etc.

        Parameters:
        nestedDepth - relative parent index of FSRL part to query, 0 == this instance.
        Returns:
        name portion of the path of the specified FSRL part.
        Throws:
        java.io.IOException - if nestedDepth is larger than number of FSRL parent parts.
      • getMD5

        public java.lang.String getMD5()
        Returns the MD5 string associated with this file.

        NULL if no MD5 value present.

        Returns:
        md5 string associated with this file object, or null if not present.
      • isMD5Equal

        public boolean isMD5Equal​(java.lang.String otherMD5)
        Tests specified MD5 value against MD5 in this FSRL.
        Parameters:
        otherMD5 - md5 in a hex string
        Returns:
        boolean true if equal, or that both are null, false otherwise
      • withMD5

        public FSRL withMD5​(java.lang.String newMD5)
        Creates a new FSRL instance, using the same information as this instance, but with a new MD5 value.
        Parameters:
        newMD5 - string md5
        Returns:
        new FSRL instance with the same path and the specified md5 value, or if newMD5 is same as existing, returns this
      • withPath

        public FSRL withPath​(java.lang.String newpath)
        Creates a new FSRL instance, using the same FSRLRoot as this instance, but with a new path.

        See also appendPath(String).

        Parameters:
        newpath - string path
        Returns:
        new FSRL instance with the specified path.
      • withPath

        public FSRL withPath​(FSRL copyPath)
        Creates a new FSRL instance using the same path and other metadata present in the copyPath instance.

        Used when re-root'ing a FSRL path onto another parent object (usually during intern()'ing)

        Parameters:
        copyPath - another FSRL to copy path and md5 from
        Returns:
        new FSRL instance
      • appendPath

        public FSRL appendPath​(java.lang.String relPath)
        Creates a new FSRL instance, using the same FSRLRoot as this instance, combining the current path with the relPath value.

        Parameters:
        relPath - relative path string to append, '/'s will be automatically added
        Returns:
        new FSRL instance with additional path appended.
      • toString

        public java.lang.String toString()
        Returns a string containing the full FSRL.

        Example: "file://path|subfs://blah?MD5=1234567"

        Overrides:
        toString in class java.lang.Object
        Returns:
        string with full FSRL
      • toPrettyString

        public java.lang.String toPrettyString()
        Returns a string containing the full FSRL, excluding MD5 portions.
        Returns:
        string with full FSRL, excluding MD5 portions.
      • toPrettyFullpathString

        public java.lang.String toPrettyFullpathString()
        Returns a string containing the full FSRL, without FS "fstype://" portions

        Example:

        "fsrl://path/filename?MD5=1234|subfsrl://subpath/subfile"

        will result in

        "path/filename|subpath/subfile".

        Returns:
        formatted string such as: "path/filename|subpath/subfile"
      • appendToStringBuilder

        protected void appendToStringBuilder​(java.lang.StringBuilder sb,
                                             boolean recurse,
                                             boolean includeParams,
                                             boolean includeFSRoot)
      • toStringPart

        public java.lang.String toStringPart()
        Returns a string containing just the current FSRL protocol and path.

        Example: "file://path|subfs://blah?MD5=123456" returns "subfs://blah?MD5=123456"

        Returns:
        string containing just the current FSRL protocol and path.
      • split

        public java.util.List<FSRL> split()
        Splits a FSRL into a List, with each element pointing to each level of the full FSRL.

        Example: "file://path|subfs://blah|subfs2://blah2"

        Produces a list of 3 elements:
        "file://path"
        "file://path|subfs://blah"
        "file://path|subfs://blah|subfs2://blah2"

        Returns:
        List of FSRL elements pointing to each level of this FSRL.
      • isEquivalent

        public boolean isEquivalent​(java.lang.String fsrlStr)
        Returns true if the two FSRLs are the same, excluding any MD5 values.
        Parameters:
        fsrlStr - string-ified FSRL
        Returns:
        boolean true if this instance is the same as the specified string-ified fsrl, ignoring any md5 values.
      • isEquivalent

        public boolean isEquivalent​(FSRL other)
        Returns true if the two FSRLs are the same, excluding any MD5 values.
        Parameters:
        other - FSRL to compare with
        Returns:
        boolean true if this instance is the same as the specified FSRL, ignoring any md5 values.
      • isDescendantOf

        public boolean isDescendantOf​(FSRL potentialParent)
        Returns true if this object is a child or descendant of the specified potentialParent parameter.

        Parameters:
        potentialParent - FSRL to test against
        Returns:
        boolean true if the specified FSRL is a parent (ignoring md5 hashes) of this instance.
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
      • equals

        public boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object