com.borland.primetime.vfs
Interface Filesystem

All Known Implementing Classes:

AbstractFilesystem, NewFilesystem, ZipFilesystem, FileFilesystem

public interface Filesystem

The Filesystem interface defines a means of interacting with a particular persistant storage mechanism. The same interface is used for both read/write and read-only filesystems, with exceptions thrown as appropriate to indicate situations when writing is not allowed.

Individual files are identified by a Url which is translated by a filesystem implementation into a meaningful underlying representation. The appropriate filesystem for a given Url is determined by examining the Url's protocol. The VFS provides a registration procedure for associating a filesystem instance with a protocol string.

Three filesystem implementations are provided with JBuilder: FileFilesystem for a "file://" Url, ZipFilesystem for a "zip://" Url, and NewFilesystem for a "new://" Url.

See Also:

Url, VFS, FileFilesystem, ZipFilesystem, NewFilesystem

Field Summary

static int	TYPE_BOTH
static int	TYPE_DIRECTORY
static int	TYPE_FILE

Method Summary

void	delete(Url url) Deletes the specified resource.
boolean	exists(Url url) Tests if the specified resource actually exists.
boolean	fileEquals(Url url, Url otherUrl) Compares the file portion of two Url objects in a case sensitive manner.
int	fileHashCode(Url url) Produces a hash value for the file portion of a Url compatible with the definition of equality provided by fileEquals.
Url	getCanonicalUrl(Url url) Reports the exact Url representation of a resource.
Url	getChild(Url url, java.lang.String subpath) Creates a new Url that adds the specified subpath to an existing Url's file path.
Url[]	getChildren(Url url, RegularExpression[] patterns, int type) Retrieves a list of children within a container, such as files within a directory.
java.io.File	getFileObject(Url url) Describes a Url in terms of a java.io.File instance.
java.io.InputStream	getInputStream(Url url) Creates an InputStream that reads from the specified Url.
long	getLastModified(Url url) Reports the time at which the contents of this resource were last modified.
java.lang.String	getName(Url url) Returns a short name for the Url.
java.io.OutputStream	getOutputStream(Url url, boolean makeBackup) Creates an OutputStream that writes to the specified Url.
Url	getParent(Url url) Returns a Url with the last subpath from the supplied Url's file path removed.
java.lang.String	getProtocol()
java.lang.String	getRelativePath(Url root, Url target, boolean onlyChildren) Create a relative path from an root Url to specified target Url.
Url	getRelativeUrl(Url root, java.lang.String relativePath) Create a relative path from an root Url to specified target Url.
boolean	isDirectory(Url url) Tests if the specified resource represents a container of other resources.
boolean	isReadOnly(Url url) Tests if the specified resource is read only.
boolean	isValid(Url url) Determines whether the state of a Url instance is valid.

Field Detail

TYPE_DIRECTORY

public static final int TYPE_DIRECTORY

TYPE_FILE

public static final int TYPE_FILE

TYPE_BOTH

public static final int TYPE_BOTH

Method Detail

getProtocol

public java.lang.String getProtocol()

getInputStream

public java.io.InputStream getInputStream(Url url)
                                   throws java.io.IOException

Creates an InputStream that reads from the specified Url. If the Url specified does not exist, but could potentially be created, the implementation should throw a java.io.FileNotFoundException.

Parameters:

url - The resource to be read.

Returns:

The InputStream.

Throws:

java.io.IOException - If the Url specified a resource that could not be read.

getOutputStream

public java.io.OutputStream getOutputStream(Url url,
                                            boolean makeBackup)
                                     throws java.io.IOException

Creates an OutputStream that writes to the specified Url. If requested and appropriate for the filesystem implementation, a backup of the existing resource will be made before writing.

The filesystem should automatically take care of any necessary details to make this possible, such as creating directories on a file-based filesystem. One exception to this rule is that a filesystem should not make a read only file read/write in order to accomplish this goal. BWS: What about read only directories?

Parameters:

url - The resource to be written.

makeBackup - True if the filesystem should make a backup first.

Returns:

The OutputStream.

Throws:

java.io.IOException - If the Url specifies a resource that could not be written to.

isReadOnly

public boolean isReadOnly(Url url)

Tests if the specified resource is read only. If the Url does not refer to a valid resource, this method should return a value based on the likelihood that such a Url could be created. A read-only filesystem would return true if no such resource exists, while a read/write filesystem would return false.

Parameters:

url - The resource to be tested.

Returns:

False if the specified Url can be written to, false if it cannot.

getLastModified

public long getLastModified(Url url)

Reports the time at which the contents of this resource were last modified.

Parameters:

url - The resource to be tested.

Returns:

The timestamp, or Buffer.MODIFIED_NEVER if the resource does not exist.

exists

public boolean exists(Url url)

Tests if the specified resource actually exists.

Parameters:

url - The resource to be tested.

Returns:

True if the specified resource exists, false otherwise.

delete

public void delete(Url url)
            throws java.io.IOException

Deletes the specified resource. Attempts to delete a read-only resource should fail, but attempts to delete a non-existant resource should be silently ignored.

Parameters:

url - The resource to be deleted.

Throws:

java.io.IOException - If the Url specifies a resource that could not be deleted.

isDirectory

public boolean isDirectory(Url url)

Tests if the specified resource represents a container of other resources.

Parameters:

url - The resource to be tested.

Returns:

True if the specified resource is a container, false otherwise.

getName

public java.lang.String getName(Url url)

Returns a short name for the Url.

Returns:

The last subpath in the file portion of the Url.

getChildren

public Url[] getChildren(Url url,
                         RegularExpression[] patterns,
                         int type)

Retrieves a list of children within a container, such as files within a directory.

Parameters:

url - The container resource.

pattern - An array of regular expressions constraining the set of values that will be returned. Only children whose final path component exactly matches at least one of the patterns will be represented in the resulting array. Note that a null array matches all children and that directories are not compared against the patterns, only files.

type - The constants TYPE_DIRECTORY, TYPE_FILE, and TYPE_BOTH can be used to control the type of resources that are represented in the result array.

Returns:

An array of valid resource descriptions in the form of Url objects. If no children exist, an empty array should be returned rather than null.

getChild

public Url getChild(Url url,
                    java.lang.String subpath)

Creates a new Url that adds the specified subpath to an existing Url's file path. The new Url will typically retain the protocol and host of the existing Url, but will always lose the anchor component.

Parameters:

url - The existing Url.

subpath - The subpath to be added to the Url's file path.

Returns:

The newly created Url.

getParent

public Url getParent(Url url)

Returns a Url with the last subpath from the supplied Url's file path removed. The anchor for the parent Url is always set to null, but the filesystem and protocol are typically inherited from the supplied Url.

Parameters:

url - The Url for which a parent is desired.

Returns:

The Url that serves as a logical parent the the supplied Url, or null if there is no parent Url, such as when the file path contains only a single subpath.

getFileObject

public java.io.File getFileObject(Url url)

Describes a Url in terms of a java.io.File instance. Note that this may not be appropriate for many filesystem types, and will return null in these cases.

Parameters:

url - The Url in question.

Returns:

An appropriate File object representation, or null if no equivelant file exists.

getCanonicalUrl

public Url getCanonicalUrl(Url url)

Reports the exact Url representation of a resource. For filesystem implementations where more than one Url are equivelant, such as a Win32 filesystem, one of the equivelant representations is the canonical representation, such as the capitalization that was used when actually creating a file under Win32.

Parameters:

url - The resource.

Returns:

The canonical representation of the Url, or the original Url if no canonical representation can be determined.

getRelativeUrl

public Url getRelativeUrl(Url root,
                          java.lang.String relativePath)

Create a relative path from an root Url to specified target Url. The anchor portions are taken care of by the VFS and are guaranteed to be null in this method.

Parameters:

root - The Url root.

relativePath - The relative path from the root.

Returns:

The newly derived Url.

getRelativePath

public java.lang.String getRelativePath(Url root,
                                        Url target,
                                        boolean onlyChildren)

Create a relative path from an root Url to specified target Url. For the purposes of relative pathing, the anchor is considered a part of the last subpath in the path.

Parameters:

root - The Url root.

target - The Url target.

onlyChildren - True if the target must be a descendant of the root, false if absolute paths and paths with leading "../" entries should be considered.

Returns:

The relative path to the target Url from this Url, or null if there is no valid path from the root Url to the target Url.

isValid

public boolean isValid(Url url)

Determines whether the state of a Url instance is valid.

Parameters:

url - The Url in question.

Returns:

True if the Url is valid, false otherwise.

fileHashCode

public int fileHashCode(Url url)

Produces a hash value for the file portion of a Url compatible with the definition of equality provided by fileEquals.

Parameters:

url - The Url to produce a hash value based on.

Returns:

The appropriate hash value.

fileEquals

public boolean fileEquals(Url url,
                          Url otherUrl)

Compares the file portion of two Url objects in a case sensitive manner.

Parameters:

url - The first of the two Urls to be compared.

otherUrl - The second of the two Urls to be compared.

Returns:

True if the file portions of the two Urls are identical, false otherwise.