Package loci.common

Class Location

java.lang.Object
loci.common.Location
Direct Known Subclasses:
CaseInsensitiveLocation
public class Location
extends java.lang.Object
Pseudo-extension of File that supports reading over HTTP (among other things). It is strongly recommended to use this instead of java.io.File.

  • Nested Class Summary

    Nested Classes 
    Modifier and Type Class Description
    protected class  Location.ListingsResult  
    protected static class  Location.UrlType  

  • Constructor Summary

    Constructors 
    Constructor Description
    Location​(java.io.File file)
    Construct a Location using the given file on disk.
    Location​(java.lang.String pathname)
    Construct a Location using the given path.
    Location​(java.lang.String parent, java.lang.String child)
    Construct a Location using the given directory and relative path.
    Location​(Location parent, java.lang.String child)
    Construct a Location using the given directory and relative path.

  • Method Summary

    Modifier and Type Method Description
    static void cacheDirectoryListings​(boolean cache)
    Turn cacheing of directory listings on or off.
    boolean canRead()
    If the underlying location is a URL, this method will return true if the URL exists.
    boolean canWrite()
    If the underlying location is a URL, this method will always return false.
    static void checkValidId​(java.lang.String id)
    Checks that the given id points at a valid data stream.
    static void cleanStaleCacheEntries()
    Remove any cached directory listings that have expired.
    static void clearDirectoryListingsCache()
    Clear the directory listings cache.
    boolean createNewFile()
    Creates a new empty file named by this Location's path name iff a file with this name does not already exist.
    boolean delete()
    Deletes this file.
    void deleteOnExit()
    Request that this file be deleted when the JVM terminates.
    boolean equals​(java.lang.Object obj)  
    boolean exists()
    Returns whether or not the pathname exists.
    Location getAbsoluteFile()
    Return the absolute form of this abstract location.
    java.lang.String getAbsolutePath()
    Return the absolute form of this abstract location.
    Location getCanonicalFile()
    Returns the canonical path to this file.
    java.lang.String getCanonicalPath()
    Returns the canonical path to this file.
    static IRandomAccess getHandle​(java.lang.String id)
    Gets an IRandomAccess object that can read from the given file.
    static IRandomAccess getHandle​(java.lang.String id, boolean writable)
    Gets an IRandomAccess object that can read from or write to the given file.
    static IRandomAccess getHandle​(java.lang.String id, boolean writable, boolean allowArchiveHandles)
    Gets an IRandomAccess object that can read from or write to the given file.
    static IRandomAccess getHandle​(java.lang.String id, boolean writable, boolean allowArchiveHandles, int bufferSize)
    Gets an IRandomAccess object that can read from or write to the given file.
    static java.util.HashMap<java.lang.String,​java.lang.Object> getIdMap()
    Return the id mapping.
    static IRandomAccess getMappedFile​(java.lang.String id)
    Gets the random access handle for the given id.
    static java.lang.String getMappedId​(java.lang.String id)
    Gets the actual filename on disk for the given id.
    java.lang.String getName()
    Returns the name of this file, i.e.
    java.lang.String getParent()
    Returns the pathname string of this abstract pathname's parent, or null if this pathname does not have a parent directory.
    Location getParentFile()
    Returns the abstract pathname of this abstract pathname's parent, or null if this pathname does not name a parent directory.
    java.lang.String getPath()
    Returns the file's path.
    int hashCode()  
    boolean isAbsolute()
    Returns whether or not this file's path is absolute.
    boolean isDirectory()
    Returns whether or not this file is a directory.
    boolean isFile()
    Returns whether or not this file is a regular file (i.e.
    boolean isHidden()
    Returns whether or not this file is marked hidden by the filesystem.
    long lastModified()
    Return the last modification time of the file.
    long length()
    Return the file length in bytes.
    java.lang.String[] list()
    Return a list of relative file names in this directory, or null if this file is not a directory.
    java.lang.String[] list​(boolean noHiddenFiles)
    Return a list of all of the files in this directory.
    Location[] listFiles()
    Return a list of files in this directory, or null if this file is not a directory.
    static void mapFile​(java.lang.String id, IRandomAccess ira)
    Maps the given id to the given IRandomAccess object.
    static void mapId​(java.lang.String id, java.lang.String filename)
    Maps the given id to an actual filename on disk.
    boolean mkdirs()
    Creates a directory structures described by this Location's internal File instance.
    static void reset()
    Clear all caches and reset cache-related bookkeeping variables to their original values.
    static void setCacheDirectoryTimeout​(double sec)
    Cache directory listings for this many seconds before relisting.
    static void setIdMap​(java.util.HashMap<java.lang.String,​java.lang.Object> map)
    Set the id mapping using the given HashMap.
    java.lang.String toString()  
    java.net.URL toURL()
    Return a URL corresponding to this file.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • Location

      public Location​(java.lang.String pathname)
      Construct a Location using the given path.
      Parameters:
      pathname - a URL, a file on disk, or a mapped name
      See Also:
      getMappedId(String), getMappedFile(String)

    • Location

      public Location​(java.io.File file)
      Construct a Location using the given file on disk.
      Parameters:
      file - a file on disk

    • Location

      public Location​(java.lang.String parent, java.lang.String child)
      Construct a Location using the given directory and relative path. The two parameters are joined with a file separator and passed to #Location(String)
      Parameters:
      parent - the directory path name
      child - the relative path name

    • Location

      public Location​(Location parent, java.lang.String child)
      Construct a Location using the given directory and relative path.
      Parameters:
      parent - a Location representing the directory name
      child - the relative path name
      See Also:
      Location(String, String)

  • Method Details

    • reset

      public static void reset()
      Clear all caches and reset cache-related bookkeeping variables to their original values.

    • cacheDirectoryListings

      public static void cacheDirectoryListings​(boolean cache)
      Turn cacheing of directory listings on or off. Cacheing is turned off by default. Reasons to cache - directory listings over network shares can be very expensive, especially in HCS experiments with thousands of files in the same directory. Technically, if you use a directory listing and then go and access the file, you are using stale information. Unlike a database, there's no transactional integrity to file system operations, so the directory could change by the time you access the file. Reasons not to cache - the contents of the directories might change during the program invocation.
      Parameters:
      cache - - true to turn cacheing on, false to leave it off.

    • setCacheDirectoryTimeout

      public static void setCacheDirectoryTimeout​(double sec)
      Cache directory listings for this many seconds before relisting.
      Parameters:
      sec - - use the cache if a directory list was done within this many seconds.

    • clearDirectoryListingsCache

      public static void clearDirectoryListingsCache()
      Clear the directory listings cache. Do this if directory contents might have changed in a significant way.

    • cleanStaleCacheEntries

      public static void cleanStaleCacheEntries()
      Remove any cached directory listings that have expired.

    • mapId

      public static void mapId​(java.lang.String id, java.lang.String filename)
      Maps the given id to an actual filename on disk. Typically actual filenames are used for ids, making this step unnecessary, but in some cases it is useful; e.g., if the file has been renamed to conform to a standard naming scheme and the original file extension is lost, then using the original filename as the id assists format handlers with type identification and pattern matching, and the id can be mapped to the actual filename for reading the file's contents.
      Parameters:
      id - the mapped name
      filename - the actual filename on disk. If null, any existing mapping for id will be cleared.
      See Also:
      getMappedId(String)

    • mapFile

      public static void mapFile​(java.lang.String id, IRandomAccess ira)
      Maps the given id to the given IRandomAccess object.
      Parameters:
      id - the mapped name
      ira - the IRandomAccess object that will be referenced by id. If null, any existing mapping for id will be cleared.
      See Also:
      getMappedFile(String)

    • getMappedId

      public static java.lang.String getMappedId​(java.lang.String id)
      Gets the actual filename on disk for the given id. Typically the id itself is the filename, but in some cases may not be; e.g., if OMEIS has renamed a file from its original name to a standard location such as Files/101, the original filename is useful for checking the file extension and doing pattern matching, but the renamed filename is required to read its contents.
      Parameters:
      id - the mapped name
      Returns:
      the corresponding file name on disk, or null if there is no mapping
      See Also:
      mapId(String, String)

    • getMappedFile

      public static IRandomAccess getMappedFile​(java.lang.String id)
      Gets the random access handle for the given id.
      Parameters:
      id - the mapped name
      Returns:
      the corresponding IRandomAccess, or null if there is no mapping
      See Also:
      mapFile(String, IRandomAccess)

    • getIdMap

      public static java.util.HashMap<java.lang.String,​java.lang.Object> getIdMap()
      Return the id mapping.
      Returns:
      the map from names to filesystem paths and IRandomAccess objects
      See Also:
      mapId(String, String), mapFile(String, IRandomAccess)

    • setIdMap

      public static void setIdMap​(java.util.HashMap<java.lang.String,​java.lang.Object> map)
      Set the id mapping using the given HashMap.
      Parameters:
      map - the new mapping from names to filesystem paths and IRandomAccess objects
      Throws:
      java.lang.IllegalArgumentException - if the given HashMap is null.

    • getHandle

      public static IRandomAccess getHandle​(java.lang.String id) throws java.io.IOException
      Gets an IRandomAccess object that can read from the given file.
      Parameters:
      id - the name for which to locate an IRandomAccess
      Returns:
      a previously mapped IRandomAccess, or a new IRandomAccess according to the name's type (URL, filesystem path, etc.)
      Throws:
      java.io.IOException - if a valid IRandomAccess cannot be created
      See Also:
      getHandle(String, boolean, boolean, int), IRandomAccess

    • getHandle

      public static IRandomAccess getHandle​(java.lang.String id, boolean writable) throws java.io.IOException
      Gets an IRandomAccess object that can read from or write to the given file.
      Parameters:
      id - the name for which to locate an IRandomAccess
      writable - true if the returned IRandomAccess should have write permission
      Returns:
      a previously mapped IRandomAccess, or a new IRandomAccess according to the name's type (URL, filesystem path, etc.)
      Throws:
      java.io.IOException - if a valid IRandomAccess cannot be created
      See Also:
      getHandle(String, boolean, boolean, int), IRandomAccess

    • getHandle

      public static IRandomAccess getHandle​(java.lang.String id, boolean writable, boolean allowArchiveHandles) throws java.io.IOException
      Gets an IRandomAccess object that can read from or write to the given file.
      Parameters:
      id - the name for which to locate an IRandomAccess
      writable - true if the returned IRandomAccess should have write permission
      allowArchiveHandles - true if checks for compressed/archive file types (e.g. Zip, GZip, BZip2) should be enabled
      Returns:
      a previously mapped IRandomAccess, or a new IRandomAccess according to the name's type (URL, filesystem path, etc.)
      Throws:
      java.io.IOException - if a valid IRandomAccess cannot be created
      See Also:
      getHandle(String, boolean, boolean, int), IRandomAccess

    • getHandle

      public static IRandomAccess getHandle​(java.lang.String id, boolean writable, boolean allowArchiveHandles, int bufferSize) throws java.io.IOException
      Gets an IRandomAccess object that can read from or write to the given file.
      Parameters:
      id - the name for which to locate an IRandomAccess
      writable - true if the returned IRandomAccess should have write permission
      allowArchiveHandles - true if checks for compressed/archive file types (e.g. Zip, GZip, BZip2) should be enabled
      bufferSize - the buffer size to use when constructing a NIOFileHandle. Ignored when non-positive.
      Returns:
      a previously mapped IRandomAccess, or a new IRandomAccess according to the name's type (URL, filesystem path, etc.)
      Throws:
      java.io.IOException - if a valid IRandomAccess cannot be created
      See Also:
      IRandomAccess

    • checkValidId

      public static void checkValidId​(java.lang.String id) throws java.io.IOException
      Checks that the given id points at a valid data stream.
      Parameters:
      id - The id string to validate.
      Throws:
      java.io.IOException - if the id is not valid.

    • list

      public java.lang.String[] list​(boolean noHiddenFiles)
      Return a list of all of the files in this directory. If 'noHiddenFiles' is set to true, then hidden files are omitted.
      Parameters:
      noHiddenFiles - true if hidden files should be omitted
      Returns:
      an unsorted list of all relative files in the directory represented by this Location
      See Also:
      File.list()

    • canRead

      public boolean canRead()
      If the underlying location is a URL, this method will return true if the URL exists. Otherwise, it will return true iff the file exists and is readable.
      Returns:
      see above
      See Also:
      File.canRead()

    • canWrite

      public boolean canWrite()
      If the underlying location is a URL, this method will always return false. Otherwise, it will return true iff the file exists and is writable.
      Returns:
      see above
      See Also:
      File.canWrite()

    • createNewFile

      public boolean createNewFile() throws java.io.IOException
      Creates a new empty file named by this Location's path name iff a file with this name does not already exist. Note that this operation is only supported if the path name can be interpreted as a path to a file on disk (i.e. is not a URL).
      Returns:
      true if the file was created successfully
      Throws:
      java.io.IOException - if an I/O error occurred, or the abstract pathname is a URL
      See Also:
      File.createNewFile()

    • mkdirs

      public boolean mkdirs()
      Creates a directory structures described by this Location's internal File instance.
      Returns:
      true if the directory structure was created successfully.
      See Also:
      File.mkdirs()

    • delete

      public boolean delete()
      Deletes this file. If isDirectory() returns true, then the directory must be empty in order to be deleted. URLs cannot be deleted.
      Returns:
      true if the file was successfully deleted
      See Also:
      File.delete()

    • deleteOnExit

      public void deleteOnExit()
      Request that this file be deleted when the JVM terminates. This method will do nothing if the pathname represents a URL.
      See Also:
      File.deleteOnExit()

    • equals

      public boolean equals​(java.lang.Object obj)
      Overrides:
      equals in class java.lang.Object
      See Also:
      File.equals(Object), URL.equals(Object)

    • hashCode

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

    • exists

      public boolean exists()
      Returns whether or not the pathname exists. If the pathname is a URL, then existence is determined based on whether or not we can successfully read content from the URL.
      Returns:
      true if there is a way to read bytes from this Location's name
      See Also:
      File.exists()

    • getAbsoluteFile

      public Location getAbsoluteFile()
      Return the absolute form of this abstract location.
      Returns:
      a Location representing @see #getAbsolutePath
      See Also:
      File.getAbsoluteFile()

    • getAbsolutePath

      public java.lang.String getAbsolutePath()
      Return the absolute form of this abstract location.
      Returns:
      a string representing the absolute path
      See Also:
      File.getAbsolutePath()

    • getCanonicalFile

      public Location getCanonicalFile() throws java.io.IOException
      Returns the canonical path to this file. If the file is a URL, then the canonical path is equivalent to the absolute file (getAbsoluteFile()). Otherwise, this method will delegate to File.getCanonicalFile().
      Returns:
      see above
      Throws:
      java.io.IOException - if the canonical path cannot be constructed
      See Also:
      File.getCanonicalFile()

    • getCanonicalPath

      public java.lang.String getCanonicalPath() throws java.io.IOException
      Returns the canonical path to this file. If the file is a URL, then the canonical path is equivalent to the absolute path (getAbsolutePath()). Otherwise, this method will delegate to File.getCanonicalPath().
      Returns:
      see above
      Throws:
      java.io.IOException - if the path cannot be retrieved

    • getName

      public java.lang.String getName()
      Returns the name of this file, i.e. the last name in the path name sequence.
      Returns:
      the relative path name
      See Also:
      File.getName()

    • getParent

      public java.lang.String getParent()
      Returns the pathname string of this abstract pathname's parent, or null if this pathname does not have a parent directory. The parent of an abstract pathname consists of the pathname's prefix, if any, and each name in the pathname's name sequence except for the last. If the name sequence is empty then the pathname does not name a parent directory.
      Returns:
      see above
      See Also:
      File.getParent()

    • getParentFile

      public Location getParentFile()
      Returns the abstract pathname of this abstract pathname's parent, or null if this pathname does not name a parent directory. The parent of an abstract pathname consists of the pathname's prefix, if any, and each name in the pathname's name sequence except for the last. If the name sequence is empty then the pathname does not name a parent directory.
      Returns:
      The abstract pathname of the parent directory named by this abstract pathname, or null if this pathname does not name a parent
      See Also:
      File.getParentFile()

    • getPath

      public java.lang.String getPath()
      Returns the file's path.
      Returns:
      this file's path name
      See Also:
      File.getPath()

    • isAbsolute

      public boolean isAbsolute()
      Returns whether or not this file's path is absolute.
      Returns:
      true if this path name is absolute. If the path name is a URL, this method will always return true.
      See Also:
      File.isAbsolute()

    • isDirectory

      public boolean isDirectory()
      Returns whether or not this file is a directory.
      Returns:
      true if this pathname exists and represents a directory.
      See Also:
      File.isDirectory()

    • isFile

      public boolean isFile()
      Returns whether or not this file is a regular file (i.e. not a directory).
      Returns:
      true if this pathname exists and represents a regular file.
      See Also:
      File.exists()

    • isHidden

      public boolean isHidden()
      Returns whether or not this file is marked hidden by the filesystem.
      Returns:
      true if the pathname is 'hidden'. This method will always return false if the pathname corresponds to a URL.
      See Also:
      File.isHidden()

    • lastModified

      public long lastModified()
      Return the last modification time of the file.
      Returns:
      the last modification time of this file, in milliseconds since the UNIX epoch. If the file does not exist, 0 is returned.
      See Also:
      File.lastModified(), URLConnection.getLastModified()

    • length

      public long length()
      Return the file length in bytes.
      Returns:
      the length of the file or stream in bytes
      See Also:
      File.length(), URLConnection.getContentLength()

    • list

      public java.lang.String[] list()
      Return a list of relative file names in this directory, or null if this file is not a directory.
      Returns:
      a list of file names in this directory. Hidden files will be included in the list. If this is not a directory, return null.
      See Also:
      list(boolean)

    • listFiles

      public Location[] listFiles()
      Return a list of files in this directory, or null if this file is not a directory.
      Returns:
      a list of absolute files in this directory. Hidden files will be included in the list. If this is not a directory, return null.
      See Also:
      list()

    • toURL

      public java.net.URL toURL() throws java.net.MalformedURLException
      Return a URL corresponding to this file.
      Returns:
      the URL corresponding to this pathname.
      Throws:
      java.net.MalformedURLException - if the pathname is not a valid URL
      See Also:
      File.toURL()

    • toString

      public java.lang.String toString()
      Overrides:
      toString in class java.lang.Object
      See Also:
      File.toString(), URL.toString()