org.das2.util.filesystem

Class FileSystem

java.lang.Object

org.das2.util.filesystem.FileSystem

Direct Known Subclasses:

LocalFileSystem, SubFileSystem, VFSFileSystem, WebFileSystem, ZipFileSystem, ZipFileSystem

public abstract class FileSystem
extends java.lang.Object

Filesystems provide an abstraction layer so that clients can access any hierarchy of files in a implementation-independent way. For example, remote filesystems accessible via HTTP are accessible through the same interface as a local filesystem.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	FileSystem.DirectoryEntry DirectoryEntry defines a structure for containing directory entry data.
static class	FileSystem.FileSystemOfflineException Exception indicating the file system is off-line.

Field Summary

Fields

Modifier and Type	Field and Description
protected static java.util.logging.Logger	logger
protected static java.util.logging.Logger	loggerUrl this logger is for opening connections to remote sites.
static FileSystem.DirectoryEntry	NULL result from failed listing, etc.
static java.lang.String	PROP_CASE_INSENSITIVE Boolean.TRUE if the filesystem ignores case, such as Windows local filesystem.
protected java.util.HashMap	properties

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	FileSystem(java.net.URI root)

Method Summary

Modifier and Type	Method and Description
static FileSystem	create(java.lang.String s) convenient method that converts string like "http://das2.org/" into a URI.
static FileSystem	create(java.lang.String s, ProgressMonitor mon) convenient method that converts string like "http://das2.org/" into a URI.
static FileSystem	create(java.net.URI root) Creates a FileSystem by parsing the URI and creating the correct FS type.
static FileSystem	create(java.net.URI root, ProgressMonitor mon) Creates a FileSystem by parsing the URI and creating the correct FS type.
static FileSystem	create(java.net.URL root) Deprecated. use create( URI root ) instead.
static FileSystem	create(java.net.URL root, ProgressMonitor mon) Deprecated. use create( URI root, ProgressMonitor mon ) instead.
FileSystem	createFileSystem(java.lang.String directory) create a new filesystem that is a part of this filesystem, rooted at directory.
static ExceptionHandler	getExceptionHandler() return the exception handler.
abstract FileObject	getFileObject(java.lang.String filename) return the FileObject that corresponds to the name.
static java.lang.String[]	getListing(FileSystem.DirectoryEntry[] des) part of the refactoring to cache time stamps as well, this convenience method returns the old string.
static java.lang.String[]	getListing(java.util.Map<java.lang.String,FileSystem.DirectoryEntry> des) part of the refactoring to cache time stamps as well, this convenience method returns the old string.
abstract java.io.File	getLocalRoot() return the folder that is a local copy of the filesystem.
java.lang.Object	getProperty(java.lang.String name) return a filesystem property, such as PROP_CASE_INSENSITIVE.
java.net.URI	getRootURI() return the URI identifying the root of the filesystem.
abstract boolean	isDirectory(java.lang.String filename) return true if the name is a directory.
abstract java.lang.String[]	listDirectory(java.lang.String directory) returns a list of the names of the files in a directory.
java.lang.String[]	listDirectory(java.lang.String directory, ProgressMonitor monitor) returns a list of the names of the files in a directory.
abstract java.lang.String[]	listDirectory(java.lang.String directory, java.lang.String regex) returns a list of the names of the files in a directory that match regex.
java.lang.String[]	listDirectory(java.lang.String directory, java.lang.String regex, ProgressMonitor monitor) returns a list of the names of the files in a directory that match regex.
java.lang.String[]	listDirectoryDeep(java.lang.String directory, java.lang.String regex) do a deep listing of directories, resolving wildcards along the way.
static FileSystem	peek(java.net.URI root) allow factories to peek, so they can see if there is a parent that is offline.
static FileSystem[]	peekInstances() return a copy of all cached filesystems
static FileSystem	recreate(java.net.URI root) creates a FileSystem, removing and recreating it if it was in the cache.
static FileSystem	recreate(java.net.URI root, ProgressMonitor mon) creates a FileSystem, removing and recreating it if it was in the cache.
static void	registerFileSystemFactory(java.lang.String proto, FileSystemFactory factory) register a code for handling a filesystem type.
static void	reset() remove all the cached FileSystem instances.
static void	reset(FileSystem fs) remove all the cached FileSystem instances.
static void	setExceptionHandler(ExceptionHandler eh) set the exception handler that is called when exceptions occur.
static FileSystemSettings	settings() access the file system settings.
static java.lang.String[]	splitUrl(java.lang.String surl) returns a String[5]:
static java.lang.String	toCanonicalFilename(java.lang.String filename) returns the canonical name /a/b/c.dat of a string that may contain backslashes and might not have the leading / and trailing slashes.
static java.lang.String	toCanonicalFolderName(java.lang.String name) returns the canonical name (/a/b/) of a string that may contain backslashes and might not have the leading / and trailing slashes.
protected static java.net.URI	toCanonicalFolderName(java.net.URI name)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

logger

protected static final java.util.logging.Logger logger

loggerUrl

protected static final java.util.logging.Logger loggerUrl

this logger is for opening connections to remote sites.

PROP_CASE_INSENSITIVE

public static final java.lang.String PROP_CASE_INSENSITIVE

Boolean.TRUE if the filesystem ignores case, such as Windows local filesystem.

See Also:

Constant Field Values

properties

protected java.util.HashMap properties

NULL

public static final FileSystem.DirectoryEntry NULL

result from failed listing, etc.

Constructor Detail

FileSystem

protected FileSystem(java.net.URI root)

Method Detail

create

public static FileSystem create(java.net.URL root)
                         throws FileSystem.FileSystemOfflineException,
                                java.net.UnknownHostException,
                                java.io.FileNotFoundException

Deprecated. use create( URI root ) instead.

Parameters:

root -

Returns:

the FileSystem

Throws:

java.net.UnknownHostException

java.io.FileNotFoundException

FileSystem.FileSystemOfflineException

java.lang.IllegalArgumentException - if the url cannot be converted to a URI.

create

public static FileSystem create(java.lang.String s)
                         throws FileSystem.FileSystemOfflineException,
                                java.net.UnknownHostException,
                                java.io.FileNotFoundException

convenient method that converts string like "http://das2.org/" into a URI.

Parameters:

s - string representation of URI, like "http://das2.org/" or "file:///tmp/"

Returns:

FileSystem object.

Throws:

FileSystem.FileSystemOfflineException

java.net.UnknownHostException

java.io.FileNotFoundException

create

public static FileSystem create(java.lang.String s,
                                ProgressMonitor mon)
                         throws FileSystem.FileSystemOfflineException,
                                java.net.UnknownHostException,
                                java.io.FileNotFoundException

convenient method that converts string like "http://das2.org/" into a URI. See http://stackoverflow.com/questions/573184/java-convert-string-to-valid-uri-object , about halfway down for Feb 21 '09 answer.

Parameters:

s - string representation of URI, like "http://das2.org/" or "file:///tmp/"

mon - monitor progress. For most FS types this is instantaneous, but for zip this can take sub-interactive time.

Returns:

FileSystem object.

Throws:

FileSystem.FileSystemOfflineException

java.net.UnknownHostException

java.io.FileNotFoundException

create

public static FileSystem create(java.net.URL root,
                                ProgressMonitor mon)
                         throws FileSystem.FileSystemOfflineException,
                                java.net.UnknownHostException,
                                java.io.FileNotFoundException

Deprecated. use create( URI root, ProgressMonitor mon ) instead.

Parameters:

root -

mon -

Returns:

Throws:

java.net.UnknownHostException

java.io.FileNotFoundException

FileSystem.FileSystemOfflineException

java.lang.IllegalArgumentException - if the url cannot be converted to a URI.

java.lang.IllegalArgumentException - if the local root does not exist.

recreate

public static FileSystem recreate(java.net.URI root)
                           throws FileSystem.FileSystemOfflineException,
                                  java.net.UnknownHostException,
                                  java.io.FileNotFoundException

creates a FileSystem, removing and recreating it if it was in the cache.

Parameters:

root -

Returns:

Throws:

FileSystem.FileSystemOfflineException

java.net.UnknownHostException

java.io.FileNotFoundException - if the remote folder is not found.

create

public static FileSystem create(java.net.URI root)
                         throws FileSystem.FileSystemOfflineException,
                                java.net.UnknownHostException,
                                java.io.FileNotFoundException

Creates a FileSystem by parsing the URI and creating the correct FS type. Presently, file, http, and ftp are supported. If the URI contains a folder ending in .zip and a FileSystemFactory is registered as handling .zip, then The zip file will be transferred and the zip file mounted.

Parameters:

root -

Returns:

Throws:

FileSystem.FileSystemOfflineException

java.net.UnknownHostException

java.io.FileNotFoundException

java.lang.IllegalArgumentException - if the URI must be converted to a URL, but cannot.

java.lang.IllegalArgumentException - if the local root does not exist.

recreate

public static FileSystem recreate(java.net.URI root,
                                  ProgressMonitor mon)
                           throws FileSystem.FileSystemOfflineException,
                                  java.net.UnknownHostException,
                                  java.io.FileNotFoundException

creates a FileSystem, removing and recreating it if it was in the cache.

Parameters:

root -

mon -

Returns:

Throws:

FileSystem.FileSystemOfflineException

java.net.UnknownHostException

java.io.FileNotFoundException - if the file is not found on the remote host.

peek

public static FileSystem peek(java.net.URI root)

allow factories to peek, so they can see if there is a parent that is offline.

Parameters:

root - the URI

Returns:

null if not existing, or the filesystem for the URI.

reset

public static void reset()

remove all the cached FileSystem instances.

reset

public static void reset(FileSystem fs)

remove all the cached FileSystem instances.

Parameters:

fs - the filesystem

create

public static FileSystem create(java.net.URI root,
                                ProgressMonitor mon)
                         throws FileSystem.FileSystemOfflineException,
                                java.net.UnknownHostException,
                                java.io.FileNotFoundException

Creates a FileSystem by parsing the URI and creating the correct FS type. Presently, file, http, and ftp are supported. If the URI contains a folder ending in .zip and a FileSystemFactory is registered as handling .zip, then The zip file will be transferred and the zip file mounted. Note "user" is a special placeholder in http://user@das2.org.

Parameters:

root - the URI, like URI("http://das2.org/") or URI("file:///tmp/")

mon - monitor progress. For most FS types this is instantaneous, but for zip this can take sub-interactive time.

Returns:

the FileSystem implementation

Throws:

FileSystem.FileSystemOfflineException

java.net.UnknownHostException

java.io.FileNotFoundException

java.lang.IllegalArgumentException - if the URI must be converted to a URL, but cannot.

java.lang.IllegalArgumentException - if the local root does not exist.

settings

public static FileSystemSettings settings()

access the file system settings.

Returns:

the single settings object.

registerFileSystemFactory

public static void registerFileSystemFactory(java.lang.String proto,
                                             FileSystemFactory factory)

register a code for handling a filesystem type. For example, an FTP implementation can be registered to handle URIs like "ftp://autoplot.org/"

Parameters:

proto - protocol identifier, like "ftp" "http" or "sftp"

factory - the factory which will handle the URI.

getRootURI

public java.net.URI getRootURI()

return the URI identifying the root of the filesystem.

Returns:

toCanonicalFilename

public static java.lang.String toCanonicalFilename(java.lang.String filename)

returns the canonical name /a/b/c.dat of a string that may contain backslashes and might not have the leading / and trailing slashes. Also, double slashes (//) are removed. Even for Windows files, forward slashes are used.

Parameters:

filename - name

Returns:

name with \ converted to /, etc.

toCanonicalFolderName

public static java.lang.String toCanonicalFolderName(java.lang.String name)

returns the canonical name (/a/b/) of a string that may contain backslashes and might not have the leading / and trailing slashes. Also, double slashes (//) are removed. Note this is the name of the FileObject within the FileSystem.

Parameters:

name - folder name

Returns:

name with \ converted to /, etc.

toCanonicalFolderName

protected static java.net.URI toCanonicalFolderName(java.net.URI name)

getFileObject

public abstract FileObject getFileObject(java.lang.String filename)

return the FileObject that corresponds to the name.

Parameters:

filename - the file name within the filesystem

Returns:

the FileObject

isDirectory

public abstract boolean isDirectory(java.lang.String filename)
                             throws java.io.IOException

return true if the name is a directory.

Parameters:

filename - the name

Returns:

true if the name is a directory.

Throws:

java.io.IOException

listDirectory

public abstract java.lang.String[] listDirectory(java.lang.String directory)
                                          throws java.io.IOException

returns a list of the names of the files in a directory. Names ending in "/" are themselves directories, and the "/" is not part of the name. This is optional, and a directory may or may not be tagged with the trailing slash.

Parameters:

directory - the directory name within the filesystem.

Returns:

list of files and folders within the filesystem.

Throws:

java.io.IOException

listDirectory

public java.lang.String[] listDirectory(java.lang.String directory,
                                        ProgressMonitor monitor)
                                 throws java.io.IOException

returns a list of the names of the files in a directory. Names ending in "/" are themselves directories, and the "/" is not part of the name. This is optional, and a directory may or may not be tagged with the trailing slash. (REALLY? This needs to be fixed...)

Parameters:

directory - the directory name within the filesystem.

monitor - a progress monitor for the task.

Returns:

list of files and folders within the filesystem.

Throws:

java.io.IOException

listDirectory

public abstract java.lang.String[] listDirectory(java.lang.String directory,
                                                 java.lang.String regex)
                                          throws java.io.IOException

returns a list of the names of the files in a directory that match regex. Trailing slashes on directory names are not part of the name and need not be part of the regex. Note regex is a regular expression (.*\.dat), not a glob (*.dat)

Parameters:

directory - the directory

regex - regular expression

Returns:

Throws:

java.io.IOException

listDirectory

public java.lang.String[] listDirectory(java.lang.String directory,
                                        java.lang.String regex,
                                        ProgressMonitor monitor)
                                 throws java.io.IOException

returns a list of the names of the files in a directory that match regex. Trailing slashes on directory names are not part of the name and need not be part of the regex. Note regex is a regular expression (.*\.dat), not a glob (*.dat)

Parameters:

directory -

regex - regular expression that must be matched, or null.

monitor - progress monitor for the task.

Returns:

names of files within the directory which match the regex.

Throws:

java.io.IOException

listDirectoryDeep

public java.lang.String[] listDirectoryDeep(java.lang.String directory,
                                            java.lang.String regex)
                                     throws java.io.IOException

do a deep listing of directories, resolving wildcards along the way. Note this can be quite expensive, so be careful when levels are too deep.

Parameters:

directory - location within the filesystem.

regex - regular expression (.*\.dat) (not a glob like *.dat).

Returns:

the entire path of each matching name, including the directory within the filesystem.

Throws:

java.io.IOException

getProperty

public java.lang.Object getProperty(java.lang.String name)

return a filesystem property, such as PROP_CASE_INSENSITIVE.

Parameters:

name - property name, e.g. PROP_CASE_INSENSITIVE

Returns:

the property value, e.g. Boolean.TRUE

getLocalRoot

public abstract java.io.File getLocalRoot()

return the folder that is a local copy of the filesystem. For LocalFilesystem, this is the same as the filesystem. For remote filesystems, this is a folder within their home directory. Note File.getAbsolutePath() returns the string representation of this root.

Returns:

the folder that is a local copy of the filesystem.

createFileSystem

public FileSystem createFileSystem(java.lang.String directory)
                            throws java.net.URISyntaxException

create a new filesystem that is a part of this filesystem, rooted at directory.

Parameters:

directory - subdirectory within the filesystem.

Returns:

the new FileSystem

Throws:

java.net.URISyntaxException

splitUrl

public static java.lang.String[] splitUrl(java.lang.String surl)

returns a String[5]:

   [0] is proto "http://"
   [1] will be the host
   [2] is proto + path
   [3] is proto + path + file
   [4] is file ext
   [5] is params, not including ?.
 

The URL must start with one of file:, ftp://, http://, https://, sftp:// and "c:" is interpreted as "file:///c:..."

Parameters:

surl - a URL string to parse.

Returns:

the parsed URL.

getExceptionHandler

public static ExceptionHandler getExceptionHandler()

return the exception handler.

Returns:

the exception handler.

setExceptionHandler

public static void setExceptionHandler(ExceptionHandler eh)

set the exception handler that is called when exceptions occur.

Parameters:

eh - the exception handler.

getListing

public static java.lang.String[] getListing(FileSystem.DirectoryEntry[] des)

part of the refactoring to cache time stamps as well, this convenience method returns the old string. This returns des.name, plus '/' if it's a directory.

Parameters:

des - array of directory entries.

Returns:

des.name, and

getListing

public static java.lang.String[] getListing(java.util.Map<java.lang.String,FileSystem.DirectoryEntry> des)

part of the refactoring to cache time stamps as well, this convenience method returns the old string. This returns des.name, plus '/' if it's a directory.

Parameters:

des - Map of directory entries.

Returns:

des.name, and

peekInstances

public static FileSystem[] peekInstances()

return a copy of all cached filesystems

Returns: