com.borland.primetime.vfs
Class VFS

java.lang.Object
  |
  +--com.borland.primetime.vfs.VFS

public final class VFS
extends java.lang.Object

The VFS, or Virtual File System, is responsible for mapping a Url to a buffer representing its contents. The VFS serves as a global cache of Buffer instances, mapping Url descriptions to existing in-memory buffers when possible, and creating new buffers as necessary.

All attempts to manipulate a Url through the VFS are directed to the filesystem associated with the Url.

See Also:
Buffer, Filesystem

Field Summary
static int BLOCK_SIZE
           
 
Method Summary
static void addVFSListener(VFSListener listener)
          Adds a VFSListener to the list of listeners that receive VFS events.
static void copy(Url sourceUrl, Url targetUrl)
          Copies a resource, duplicating both the state of buffers and the persistant storage state.
static void copyStream(java.io.InputStream inputStream, java.io.OutputStream outputStream)
          Copies the contents of an InputStream to an OutputStream.
static void delete(Url url)
          Deletes the specified resource from permanent storage and ensures that its buffer, if in memory, has been emptied and marked as unmodified.
static boolean exists(Url url)
          Tests if the specified resource actually exists.
static Buffer findBuffer(Url url)
          Checks the cache for an existing reference to the underlying buffer.
static void fireBufferConflict(Buffer buffer)
          Notifies all registered VFSListeners that the content of the buffer has been changed in memory and on disk and that the resulting conflict needs to be resolved.
static Buffer getBuffer(Url url)
          Returns an instance of the appropriate Buffer subclass to represent the contents of a Url.
static Url getCanonicalUrl(Url url)
          Reports the exact Url representation of a resource.
static Url[] getChildren(Url url, int type)
          Retrieves a list of children within a resource, such as files within a directory.
static Url[] getChildren(Url url, RegularExpression[] patterns, int type)
          Retrieves a list of children within a resource, such as files within a directory.
static Url[] getChildren(Url url, RegularExpression pattern, int type)
          Retrieves a list of children within a resource, such as files within a directory.
static java.io.InputStream getInputStream(Url url)
          Creates an InputStream that reads from the specified Url.
static long getLastModified(Url url)
          Reports the time at which the contents of this resource were last modified.
static java.io.OutputStream getOutputStream(Url url)
          Creates an OutputStream that writes to the specified Url.
static java.io.OutputStream getOutputStream(Url url, boolean createBackup)
          Creates an OutputStream that writes to the specified Url.
static boolean isAutoBackupEnabled()
          Reports the current default behavior for backing up files before writing to them via getOutputStream().
static boolean isDirectory(Url url)
          Tests if the specified resource represents a container of other resources.
static boolean isReadOnly(Url url)
          Tests if the specified resource is read-only.
static void removeVFSListener(VFSListener listener)
          Removes a VFSListener from the list of listeners that receive VFS events.
static void rename(Url oldUrl, Url newUrl)
          Renames a resource by making a copy and deleting the original.
static void setAutoBackupEnabled(boolean enabled)
          Changes the current default behavior for backing up files before writing to them via getOutputStream().
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

BLOCK_SIZE

public static final int BLOCK_SIZE
Method Detail

copyStream

public static void copyStream(java.io.InputStream inputStream,
                              java.io.OutputStream outputStream)
                       throws java.io.IOException
Copies the contents of an InputStream to an OutputStream.
Throws:
java.io.IOException - If the copy cannot be completed due to read or write errors.

getBuffer

public static Buffer getBuffer(Url url)
                        throws java.io.IOException
Returns an instance of the appropriate Buffer subclass to represent the contents of a Url. This buffer may already be present in a global cache of all known buffers, or it may be created on demand in which case the contents of the Url is automatically read into the buffer via a call to the buffer's revert method.
Parameters:
url - The resource for which a buffer is desired.
Returns:
A Buffer representing the contents of the specified resource.
Throws:
java.io.IOException - If the specified resource could not be read.

findBuffer

public static Buffer findBuffer(Url url)
Checks the cache for an existing reference to the underlying buffer.
Parameters:
url - The Url key used to locate the desired buffer.
Returns:
The Buffer object associated with the Url is returned. A null return means that either the Url has never been mapped into the cache, or that the existing entry has been garbage collected.

getInputStream

public static java.io.InputStream getInputStream(Url url)
                                          throws java.io.IOException
Creates an InputStream that reads from the specified Url. If a buffer exists that represents the Url, the InputStream is opened directly on the buffer, otherwise an appropriate filesystem is found and used directly.
Parameters:
url - The resource to be read.
Returns:
The InputStream.
Throws:
java.io.IOException - If the Url specifies a resource that could not be read, or if no matching filesystem could be found for the Url.

isAutoBackupEnabled

public static boolean isAutoBackupEnabled()
Reports the current default behavior for backing up files before writing to them via getOutputStream().
Returns:
True if auto-backup is enabled, false otherwise.

setAutoBackupEnabled

public static void setAutoBackupEnabled(boolean enabled)
Changes the current default behavior for backing up files before writing to them via getOutputStream().
Parameters:
enabled - True if auto-backup should be enabled, false otherwise.

getOutputStream

public static java.io.OutputStream getOutputStream(Url url)
                                            throws VFSException,
                                                   java.io.IOException
Creates an OutputStream that writes to the specified Url. If a buffer exists that represents the Url, the OutputStream will write directly to the buffer. For consistency with the normal behavior of this method when no such buffer exists, the buffer will be written to the appropriate filesystem immediately after the OutputStream is closed. If it is necessary to write only to an in-memory buffer, retrieve the buffer directly with getBuffer and use its getOutputStream method instead.

The current setting for automatic backups is used to determine whether or not a backup file should be created.

Parameters:
url - The resource to be written.
Returns:
The OutputStream.
Throws:
java.io.IOException - If the Url specifies a resource that could not be written to.

getOutputStream

public static java.io.OutputStream getOutputStream(Url url,
                                                   boolean createBackup)
                                            throws VFSException,
                                                   java.io.IOException
Creates an OutputStream that writes to the specified Url. If a buffer exists that represents the Url, the OutputStream will write directly to the buffer. For consistency with the normal behavior of this method when no such buffer exists, the buffer will be written to the appropriate filesystem immediately after the OutputStream is closed. If it is necessary to write only to an in-memory buffer, retrieve the buffer directly with getBuffer and use its getOutputStream method instead.
Parameters:
url - The resource to be written.
createBackup - True if a backup file should be created, false otherwise.
Returns:
The OutputStream.
Throws:
java.io.IOException - If the Url specifies a resource that could not be written to.

isReadOnly

public static boolean isReadOnly(Url url)
Tests if the specified resource is read-only. If the Url does not refer to a valid resource, this method will return a value based on the likelihood that such a Url could be created. A read-only filesystem will return true if no such resource exists, while a read/write filesystem will return false.
Parameters:
url - The resource to be tested.
Returns:
False if the specified Url can be written to, true if it cannot.

getLastModified

public static 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.

getCanonicalUrl

public static 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.

exists

public static boolean exists(Url url)
Tests if the specified resource actually exists. For this method's purposes, Buffers that have not yet been saved to a filesystem are considered to exist unless they are unmodified and zero length.
Parameters:
url - The resource to be tested.
Returns:
True if the specified resource exists, false otherwise.

isDirectory

public static 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.

getChildren

public static Url[] getChildren(Url url,
                                int type)

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

Parameters:
url - The container resource.
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 will be returned rather than null.

getChildren

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

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

Parameters:
url - The container resource.
pattern - A regular expression constraining the set of values that will be returned. Only children whose final path component exactly matches the pattern will be represented in the resulting array. Note that directories are not compared against the pattern, 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 will be returned rather than null.

getChildren

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

Retrieves a list of children within a resource, 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 will be returned rather than null.

delete

public static void delete(Url url)
                   throws java.io.IOException
Deletes the specified resource from permanent storage and ensures that its buffer, if in memory, has been emptied and marked as unmodified. Attempts to delete a read-only resource will fail, but attempting to delete a non-existant resource will succeed.
Parameters:
url - The resource to be deleted.
Throws:
java.io.IOException - If the Url specifies a resource that could not be deleted.

rename

public static void rename(Url oldUrl,
                          Url newUrl)
                   throws java.io.IOException,
                          java.io.FileNotFoundException,
                          ReadOnlyException
Renames a resource by making a copy and deleting the original. The rename process takes into account the state of buffers, so that the target buffer contains the modified contents of the original buffer, and the persistant representation matches of the target matches the representation of the source.
Parameters:
sourceUrl - The resource's current Url.
desinationUrl - The resource's desired Url.
Throws:
java.io.IOException - If the resource could not be renamed due to a read or write error, or the source is read-only, or the target Url already exists.
java.io.FileNotFoundException - If the source does not exist as either a buffer in the VFS or a resource in a filesystem.

copy

public static void copy(Url sourceUrl,
                        Url targetUrl)
                 throws java.io.IOException
Copies a resource, duplicating both the state of buffers and the persistant storage state. For example, after a copy operation on a file with in-memory buffer modifications, both the source and the target will be represented by modified buffers and out-of-date on disk representations.

If the target Url already exists, copy will silently overwrite it.

Parameters:
sourceUrl - The resource to copy from.
targetUrl - The resource to copy to.
Throws:
java.io.IOException - If the resource could not be copied due to a read or write error.
java.io.FileNotFoundException - If the source does not exist as either a buffer in the VFS or a resource in a filesystem.

addVFSListener

public static void addVFSListener(VFSListener listener)
Adds a VFSListener to the list of listeners that receive VFS events.
Parameters:
listener - The listener.

removeVFSListener

public static void removeVFSListener(VFSListener listener)
Removes a VFSListener from the list of listeners that receive VFS events.
Parameters:
listener - The listener.

fireBufferConflict

public static void fireBufferConflict(Buffer buffer)
Notifies all registered VFSListeners that the content of the buffer has been changed in memory and on disk and that the resulting conflict needs to be resolved.