edu.sdsc.grid.io
Class RemoteFile

java.lang.Object
  edu.sdsc.grid.io.GeneralFile
      edu.sdsc.grid.io.RemoteFile

All Implemented Interfaces:

java.lang.Comparable

Direct Known Subclasses:

IRODSFile, SRBFile

public abstract class RemoteFile
extends GeneralFile

An abstract representation of file and directory pathnames on a remote server. This abstract class can be subclassed to create a file object for refering to a remote file on a particular kind fo remote server.

Shares many similarities with the java.io.File class: User interfaces and operating systems use system-dependent pathname strings to name files and directories. This class presents an abstract, system-independent view of hierarchical pathnames. An abstract pathname has two components:

An optional system-dependent prefix string, such as a disk-drive specifier, "/" for the UNIX root directory, or "\\" for a Microsoft Windows UNC pathname, and
A sequence of zero or more string names. Each name in an abstract pathname except for the last denotes a directory; the last name may denote either a directory or a file. The empty abstract pathname has no prefix and an empty name sequence. The conversion of a pathname string to or from an abstract pathname is inherently system-dependent. When an abstract pathname is converted into a pathname string, each name is separated from the next by a single copy of the default separator character. The default name-separator character is defined by the system property file.separator, and is made available in the public static fields separator and separatorChar of this class. When a pathname string is converted into an abstract pathname, the names within it may be separated by the default name-separator character or by any other name-separator character that is supported by the underlying system.

A pathname, whether abstract or in string form, may be either absolute or relative. An absolute pathname is complete in that no other information is required in order to locate the file that it denotes. A relative pathname, in contrast, must be interpreted in terms of information taken from some other pathname. By default the classes in this package always resolve relative pathnames against the current user directory. This directory is named by the system property user.dir, and is typically the directory in which the Java virtual machine was invoked.

The prefix concept is used to handle root directories on UNIX platforms, and drive specifiers, root directories and UNC pathnames on Microsoft Windows platforms, as follows:

For UNIX platforms, the prefix of an absolute pathname is always "/". Relative pathnames have no prefix. The abstract pathname denoting the root directory has the prefix "/" and an empty name sequence.

For Microsoft Windows platforms, the prefix of a pathname that contains a drive specifier consists of the drive letter followed by ":" and possibly followed by "\" if the pathname is absolute. The prefix of a UNC pathname is "\\"; the hostname and the share name are the first two names in the name sequence. A relative pathname that does not specify a drive has no prefix.

Instances of the RemoteFile class are immutable; that is, once created, the abstract pathname represented by a RemoteFile object will never change.

See Also:

File, GeneralFile

Field Summary

Fields inherited from class edu.sdsc.grid.io.GeneralFile

BUFFER_MAX_SIZE, directory, fileName, fileSystem, PATH_SEPARATOR, PATH_SEPARATOR_CHAR, pathSeparator, pathSeparatorChar, separator, separatorChar

Constructor Summary

RemoteFile(RemoteFile parent, java.lang.String child)
Creates a new RemoteFile instance from a parent abstract pathname and a child pathname string.

RemoteFile(RemoteFileSystem fileSystem, java.lang.String filePath)
Creates a new RemoteFile instance by converting the given pathname string into an abstract pathname.

RemoteFile(RemoteFileSystem fileSystem, java.lang.String parent, java.lang.String child)
Creates a new RemoteFile instance from a parent pathname string and a child pathname string.

RemoteFile(java.net.URI uri)
Creates a new RemoteFile instance by converting the given file: URI into an abstract pathname.

Method Summary

abstract java.lang.String	getResource()
abstract void	replicate(java.lang.String newResource) Replicates this RemoteFile to a new resource.

Methods inherited from class edu.sdsc.grid.io.GeneralFile

canRead, canWrite, checksum, compareTo, compareTo, copyFrom, copyFrom, copyTo, copyTo, createNewFile, createTempFile, createTempFile, delete, deleteOnExit, equals, exists, finalize, firstQueryResult, getAbsoluteFile, getAbsolutePath, getCanonicalFile, getCanonicalPath, getFileSystem, getName, getParent, getParentFile, getPath, getPathSeparator, getPathSeparatorChar, isAbsolute, isDirectory, isFile, isHidden, lastModified, length, list, list, listFiles, listRoots, listRoots, mkdir, mkdirs, modifyMetaData, query, query, query, renameTo, setDirectory, setFileName, setFileSystem, setLastModified, setReadOnly, toString, toURI, toURL

Methods inherited from class java.lang.Object

clone, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

RemoteFile

public RemoteFile(RemoteFileSystem fileSystem,
                  java.lang.String filePath)
           throws java.lang.NullPointerException

Creates a new RemoteFile instance by converting the given pathname string into an abstract pathname.

Parameters:

fileSystem - The connection to the remote server

filePath - A pathname string

Throws:

java.lang.NullPointerException

RemoteFile

public RemoteFile(RemoteFileSystem fileSystem,
                  java.lang.String parent,
                  java.lang.String child)
           throws java.lang.NullPointerException

Creates a new RemoteFile instance from a parent pathname string and a child pathname string.

If parent is null then the new RemoteFile instance is created as if by invoking the single-argument RemoteFile constructor on the given child pathname string.

Otherwise the parent pathname string is taken to denote a directory, and the child pathname string is taken to denote either a directory or a file. If the child pathname string is absolute then it is converted into a relative pathname in a system-dependent way. If parent is the empty string then the new RemoteFile instance is created by converting child into an abstract pathname and resolving the result against a system-dependent default directory. Otherwise each pathname string is converted into an abstract pathname and the child abstract pathname is resolved against the parent.

Parameters:

fileSystem - The connection to the remote server

parent - The parent pathname string

child - The child pathname string

Throws:

java.lang.NullPointerException

RemoteFile

public RemoteFile(RemoteFile parent,
                  java.lang.String child)
           throws java.lang.NullPointerException

Creates a new RemoteFile instance from a parent abstract pathname and a child pathname string.

If parent is null then the new RemoteFile instance is created as if by invoking the single-argument RemoteFile constructor on the given child pathname string.

Otherwise the parent abstract pathname is taken to denote a directory, and the child pathname string is taken to denote either a directory or a file. If the child pathname string is absolute then it is converted into a relative pathname in a system-dependent way. If parent is the empty abstract pathname then the new RemoteFile instance is created by converting child into an abstract pathname and resolving the result against a system-dependent default directory. Otherwise each pathname string is converted into an abstract pathname and the child abstract pathname is resolved against the parent.

Parameters:

parent - The parent abstract pathname

child - The child pathname string

Throws:

java.lang.NullPointerException

RemoteFile

public RemoteFile(java.net.URI uri)
           throws java.lang.NullPointerException,
                  java.lang.IllegalArgumentException

Creates a new RemoteFile instance by converting the given file: URI into an abstract pathname.

The exact form of a file: URI is system-dependent, hence the transformation performed by this constructor is also system-dependent.

For a given abstract pathname f it is guaranteed that

new RemoteFile( f.toURI()).equals( f)

so long as the original abstract pathname, the URI, and the new abstract pathname are all created in (possibly different invocations of) the same Java virtual machine. This relationship typically does not hold, however, when a file: URI that is created in a virtual machine on one operating system is converted into an abstract pathname in a virtual machine on a different operating system.

Parameters:

uri - An absolute, hierarchical URI using a supported scheme.

Throws:

java.lang.NullPointerException - if uri is null.

java.lang.IllegalArgumentException - If the preconditions on the parameter do not hold.

Method Detail

getResource

public abstract java.lang.String getResource()
                                      throws java.io.IOException

Returns:

resource the physical resource where this RemoteFile is stored. Returns null if this abstract pathname is a directory or does not exist.

Throws:

java.io.IOException - If an IOException occurs during the system query.

replicate

public abstract void replicate(java.lang.String newResource)
                        throws java.io.IOException

Replicates this RemoteFile to a new resource. Directories/collections will be recursively replicated.

In some remote systems, one can make copies of a data set and store the copies in different locations. But, all these copies are considered to be identifiable by the same identifier. That is, each copy is considered to be equivalent to each other.

When a user reads a replicated data set, the remote system cycles through all the copies of the datset and reads the one that is accessible at that time.

Parameters:

newResource - The storage resource name of the new copy.

Throws:

java.io.IOException - If an IOException occurs.