com.borland.primetime.vfs
Class Buffer

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

public final class Buffer
extends java.lang.Object
implements BufferUpdater

Buffer is the concrete implementation for all virtual file system buffer management. A buffer is an in-memory representation of the information referred to by a Url, and as such may represent changes to a Url that have not yet been saved to permanent storage.

See Also:
Url

Field Summary
static Buffer[] EMPTY_ARRAY
           
static long MODIFIED_NEVER
           
static int STATE_LOADING
           
static int STATE_MODIFIED
           
static int STATE_READONLY
           
 
Constructor Summary
Buffer(Url url)
          Initializes a new Buffer instance to represent the contents of a specified Url.
 
Method Summary
 void addBufferListener(BufferListener listener)
          Adds a BufferListener to the list of listeners that receive buffer events from this buffer.
 void check()
          Checks the underlying representation of this buffer to ensure that the in-memory representation is up to date with changes that may have been made outside the VFS.
 void fireBufferChanged(BufferUpdater updater)
          Notifies all registered BufferListeners that the content of the buffer has been changed.
 void fireBufferLoaded()
          Notifies all registered BufferListeners that the content of the buffer has been loaded.
 void fireBufferSaving()
          Notifies all registered BufferListeners that the content of the buffer is about to be saved.
 void fireBufferStateChanged(int oldState, int newState)
          Notifies all registered BufferListeners that the state of the buffer has been changed.
 byte[] getBufferContent(Buffer buffer)
          Reads the conents of the buffer's Url source and returns it as a byte array.
 byte[] getContent()
          Returns the buffer's contents as an array of bytes.
 java.io.InputStream getInputStream()
          Creates an InputStream to provide read-only access to the contents of the buffer as defined by getContent.
 long getLastModified()
          Returns a timestamp representing the last time the buffer's contents were modified.
static int getModifiedBufferCount()
          Returns the count of all buffers managed by the VFS that are currently marked as modified.
static Buffer[] getModifiedBuffers()
          Returns a copy of the list of all buffers managed by the VFS that are currently marked as modified.
 java.io.OutputStream getOutputStream()
          Creates an OutputStream to provide write access to the contents of the buffer.
 int getSize()
          Reports the length of the buffer content in bytes.
 long getSourceLastModified()
          A timestamp representing the last time the source of the buffer's contents had been modified at the time the buffer was read.
 Url getUrl()
          Returns the Url that this buffer represents.
 boolean isLoading()
          Determines if the buffer is in the midst of being loaded from permanent storage.
 boolean isModified()
          Determines if the buffer has been changed since it was last loaded from or saved to permanent storage.
 boolean isReadOnly()
          Reports whether the buffer is currently read only, a state that is typically kept in sync with the state of the source of the buffer by the virtual file system.
 void removeBufferListener(BufferListener listener)
          Removes a BufferListener from the list of listeners that receive buffer events from this buffer.
 void revert()
          Conceptually, this reads the conents of the buffer's Url source, marks the buffer unmodified, and sets the buffer's read-only state to match that of the source Url.
 void save()
          Writes the contents of a buffer to its Url and marks the buffer unmodified.
 void setContent(BufferUpdater updater)
          Sets the contents of the buffer in a lazy fasion using a BufferUpdater.
 void setContent(byte[] content)
          Sets the buffer's contents as an array of bytes.
 void setModified(boolean modified)
          Changes the modified state of the buffer and automatically updates the value returned by getLastModified to reflect the current time, or resets it to the value of sourceLastModified if the buffer is being set to an unmodified state.
 void updateContent()
          If the buffer has an associated BufferUpdater, forces the buffer to fetch its current contents and discard the reference to the updater.
static void updateModifiedBuffers()
          Forces all lazy updates to be flushed to the appropriate buffers.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

EMPTY_ARRAY

public static final Buffer[] EMPTY_ARRAY

MODIFIED_NEVER

public static final long MODIFIED_NEVER

STATE_MODIFIED

public static final int STATE_MODIFIED

STATE_READONLY

public static final int STATE_READONLY

STATE_LOADING

public static final int STATE_LOADING
Constructor Detail

Buffer

public Buffer(Url url)
Initializes a new Buffer instance to represent the contents of a specified Url. Note that the Url associated with a buffer is invariant.
Parameters:
url - The associated Url.
Method Detail

getUrl

public Url getUrl()
Returns the Url that this buffer represents.
Returns:
The Url.

revert

public void revert()
Conceptually, this reads the conents of the buffer's Url source, marks the buffer unmodified, and sets the buffer's read-only state to match that of the source Url. Lastly, the buffer's sourceLastModified property is set to match the timestamp on the Url.

In practice the actual loading of the buffer's contents is deferred until the first time it is accessed.


save

public void save()
          throws java.io.IOException
Writes the contents of a buffer to its Url and marks the buffer unmodified. Lastly, the buffer's sourceLastModified property is reset to match the Url's new timestamp.
Throws:
java.io.IOException - If the Url cannot be written to.

check

public void check()
Checks the underlying representation of this buffer to ensure that the in-memory representation is up to date with changes that may have been made outside the VFS. The read-only state is set to match the current filesystem state, and the buffer's sourceLastModified property is compared with the original Url's last modification.

If the Url has been updated then the action depends on the buffer's state. If the buffer is not modified, the buffer is automatically updated via a call to revert. Otherwise, the VFS's VFSListeners are notified to give the user a chance to make the choice.


getContent

public byte[] getContent()
Returns the buffer's contents as an array of bytes.
Returns:
The array of bytes representing the content of the buffer.

setContent

public void setContent(byte[] content)
                throws ReadOnlyException
Sets the buffer's contents as an array of bytes. This method is called by getOutputStream when the complete contents have been written.
Parameters:
content - An array of bytes representing the new content of the buffer.
Throws:
com.borland.vfs.ReadOnlyException - If the buffer is read only.

getInputStream

public java.io.InputStream getInputStream()
Creates an InputStream to provide read-only access to the contents of the buffer as defined by getContent.
Returns:
The InputStream.

getOutputStream

public java.io.OutputStream getOutputStream()
                                     throws ReadOnlyException
Creates an OutputStream to provide write access to the contents of the buffer. Changes are accumulated until the OutputStream is closed, at which time the contents of the Buffer are updated via setContent(byte[]).
Returns:
The OutputStream.
Throws:
ReadOnlyException - If the buffer is read only.

getSize

public int getSize()
Reports the length of the buffer content in bytes.
Returns:
Zero if the buffer is completely empty, an approximate size in bytes otherwise.

setContent

public void setContent(BufferUpdater updater)
                throws ReadOnlyException

Sets the contents of the buffer in a lazy fasion using a BufferUpdater. All listeners are notified that the buffer's contents has changed, but the information is only read if there is an actual request to read the new contents.

Note that the Buffer may maintain a reference to the BufferUpdater instance for an arbitrarily long period of time. To ensure that this reference is released, call the Buffer's updateContent() method to force the most recent updater's contents to be read immediately.

See Also:
BufferUpdater

updateContent

public void updateContent()

If the buffer has an associated BufferUpdater, forces the buffer to fetch its current contents and discard the reference to the updater.


getLastModified

public long getLastModified()
Returns a timestamp representing the last time the buffer's contents were modified.
Returns:
The time of the buffer's last modification, or the time the source of the data was last modified if the buffer has not been modified.

getSourceLastModified

public long getSourceLastModified()
A timestamp representing the last time the source of the buffer's contents had been modified at the time the buffer was read. This value is used by the VFS to determine whether when the buffer's contents is outdated and should be refreshed. Note that this value's accuracy depends on the filesystem in question and cannot reliably be compared with the system clock.
Returns:
The timestamp, or the special value MODIFIED_NEVER if the buffer's contents were never read from permanent storage.

isReadOnly

public boolean isReadOnly()
Reports whether the buffer is currently read only, a state that is typically kept in sync with the state of the source of the buffer by the virtual file system.
Returns:
True if the buffer is read only, false otherwise.

isModified

public boolean isModified()
Determines if the buffer has been changed since it was last loaded from or saved to permanent storage.
Returns:
True if the buffer has been modifed and not yet saved, false otherwise.

setModified

public void setModified(boolean modified)
Changes the modified state of the buffer and automatically updates the value returned by getLastModified to reflect the current time, or resets it to the value of sourceLastModified if the buffer is being set to an unmodified state.

Internal methods that alter the contents of the buffer invoke setModified(true), even if the modified flag is already set.

Parameters:
modified - True if the buffer should be marked as modified, false otherwise.

getModifiedBuffers

public static Buffer[] getModifiedBuffers()
Returns a copy of the list of all buffers managed by the VFS that are currently marked as modified.
Returns:
An array of Buffer instances.

getModifiedBufferCount

public static int getModifiedBufferCount()
Returns the count of all buffers managed by the VFS that are currently marked as modified.
Returns:
An int representing the count of modified Buffer instances.

updateModifiedBuffers

public static void updateModifiedBuffers()
Forces all lazy updates to be flushed to the appropriate buffers. This can make a dramatic difference if invoked just prior to garbage collection since it removes all references from the VFS back to other subsystems.

isLoading

public boolean isLoading()
Determines if the buffer is in the midst of being loaded from permanent storage. Since many state transitions occur during loading, a client may wish to wait for the buffer to be fully loaded before taking action.
Returns:
True if the buffer is still being loaded, false otherwise.

addBufferListener

public void addBufferListener(BufferListener listener)
Adds a BufferListener to the list of listeners that receive buffer events from this buffer.
Parameters:
listener - The listener.

removeBufferListener

public void removeBufferListener(BufferListener listener)
Removes a BufferListener from the list of listeners that receive buffer events from this buffer.
Parameters:
listener - The listener.

fireBufferChanged

public void fireBufferChanged(BufferUpdater updater)
Notifies all registered BufferListeners that the content of the buffer has been changed.

fireBufferLoaded

public void fireBufferLoaded()
Notifies all registered BufferListeners that the content of the buffer has been loaded.

fireBufferSaving

public void fireBufferSaving()
Notifies all registered BufferListeners that the content of the buffer is about to be saved.

fireBufferStateChanged

public void fireBufferStateChanged(int oldState,
                                   int newState)
Notifies all registered BufferListeners that the state of the buffer has been changed. This method is automatically invoked by setState, and indirectly by setModified, setReadOnly and setLoading if the new setting causes a change in state. The states passed to listeners may be interpreted using the constants described under getState.
Parameters:
oldState - The state of the buffer prior to the change.
newState - The current state of the buffer.

getBufferContent

public byte[] getBufferContent(Buffer buffer)
Reads the conents of the buffer's Url source and returns it as a byte array. This mechanism is used by revert() to allow the buffer to lazily load its own content.

If a java.io.FileNotFoundException is thrown by the Url's filesystem, an empty array is returned and the buffer is marked as modified with a source timestamp of Buffer.MODIFIED_NEVER.

Specified by:
getBufferContent in interface BufferUpdater
Returns:
An array of bytes containing the on-disk representation of the buffer.