loci.common

Class Location

java.lang.Object

loci.common.Location

Direct Known Subclasses:

CaseInsensitiveLocation

public class Location
extends java.lang.Object

Pseudo-extension of java.io.File that supports reading over HTTP (among other things). It is strongly recommended to use this instead of java.io.File.

Source code:

Trac, Gitweb

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected class	Location.ListingsResult

Constructor Summary

Constructors

Constructor and Description
Location(java.io.File file)
Location(Location parent, java.lang.String child)
Location(java.lang.String pathname)
Location(java.lang.String parent, java.lang.String child)

Method Summary

Methods

Modifier and Type	Method and 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()
java.lang.String	getAbsolutePath()
Location	getCanonicalFile()
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)
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 name of this file's parent directory, i.e.
Location	getParentFile()
java.lang.String	getPath()
int	hashCode()
boolean	isAbsolute() Tests whether or not this path name is absolute.
boolean	isDirectory() Returns true if this pathname exists and represents a directory.
boolean	isFile() Returns true if this pathname exists and represents a regular file.
boolean	isHidden() Returns true if the pathname is 'hidden'.
long	lastModified() Return the last modification time of this file, in milliseconds since the UNIX epoch.
long	length()
java.lang.String[]	list() Return a list of file names in this directory.
java.lang.String[]	list(boolean noHiddenFiles) Return a list of all of the files in this directory.
Location[]	listFiles() Return a list of absolute files in this 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 the URL corresponding to this pathname.

Methods inherited from class java.lang.Object

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

Constructor Detail

Location

public Location(java.lang.String pathname)

Location

public Location(java.io.File file)

Location

public Location(java.lang.String parent,
        java.lang.String child)

Location

public Location(Location parent,
        java.lang.String child)

Method Detail

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.

See Also:

getMappedId(String)

mapFile

public static void mapFile(java.lang.String id,
           IRandomAccess ira)

Maps the given id to the given IRandomAccess object.

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.

See Also:

mapId(String, String)

getMappedFile

public static IRandomAccess getMappedFile(java.lang.String id)

Gets the random access handle for the given id.

getIdMap

public static java.util.HashMap<java.lang.String,java.lang.Object> getIdMap()

Return the id mapping.

setIdMap

public static void setIdMap(java.util.HashMap<java.lang.String,java.lang.Object> map)

Set the id mapping using the given HashMap.

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.

Throws:

java.io.IOException

See Also:

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.

Throws:

java.io.IOException

See Also:

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.

Throws:

java.io.IOException

See Also:

IRandomAccess

getHandle

public static IRandomAccess getHandle(java.lang.String id,
                      boolean writable,
                      boolean allowArchiveHandles,
                      int bufferSize)
                               throws java.io.IOException

Throws:

java.io.IOException

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.

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.

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.

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.

See Also:

File.exists()

getAbsoluteFile

public Location getAbsoluteFile()

getAbsolutePath

public java.lang.String getAbsolutePath()

getCanonicalFile

public Location getCanonicalFile()
                          throws java.io.IOException

Throws:

java.io.IOException

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().

Throws:

java.io.IOException

getName

public java.lang.String getName()

Returns the name of this file, i.e. the last name in the path name sequence.

See Also:

File.getName()

getParent

public java.lang.String getParent()

Returns the name of this file's parent directory, i.e. the path name prefix and every name in the path name sequence except for the last. If this file does not have a parent directory, then null is returned.

See Also:

File.getParent()

getParentFile

public Location getParentFile()

getPath

public java.lang.String getPath()

isAbsolute

public boolean isAbsolute()

Tests whether or not 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 true if this pathname exists and represents a directory.

See Also:

File.isDirectory()

isFile

public boolean isFile()

Returns true if this pathname exists and represents a regular file.

See Also:

File.exists()

isHidden

public boolean isHidden()

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 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()

See Also:

File.length(), URLConnection.getContentLength()

list

public java.lang.String[] list()

Return a list of file names in this directory. Hidden files will be included in the list. If this is not a directory, return null.

listFiles

public Location[] listFiles()

Return a list of absolute files in this directory. Hidden files will be included in the list. If this is not a directory, return null.

toURL

public java.net.URL toURL()
                   throws java.net.MalformedURLException

Return the URL corresponding to this pathname.

Throws:

java.net.MalformedURLException

See Also:

File.toURL()

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

See Also:

File.toString(), URL.toString()