uk.ac.rdg.resc.jstyx.client
Class CStyxFile

java.lang.Object
  uk.ac.rdg.resc.jstyx.client.CStyxFile

public class CStyxFile
extends java.lang.Object

A Styx file (or directory) from the point of view of the client. (It is called a CStyxFile in order to avoid confusion with the server-side StyxFile class.) To create a CStyxFile, open a StyxConnection and use the getFile() method. CStyxFiles cannot be created directly.

Author:

Jon Blower $Revision: 609 $ $Date: 2006-03-31 18:09:42 +0100 (Fri, 31 Mar 2006) $ $Log$ Revision 1.46 2006/03/21 14:58:41 jonblower Implemented clear-text password-based authentication and did some simple tests Revision 1.45 2006/01/06 10:14:22 jonblower Clarified comments Revision 1.44 2005/12/07 08:51:13 jonblower Added option to readAsync() to open file for reading and writing with truncation Revision 1.43 2005/12/01 08:21:55 jonblower Fixed javadoc comments Revision 1.42 2005/11/07 22:00:54 jonblower Added upload(java.io.File) method Revision 1.41 2005/10/14 18:05:19 jonblower Added walkFid() and exists() methods Revision 1.40 2005/09/11 18:50:42 jonblower Added toString() method Revision 1.39 2005/09/02 16:54:26 jonblower Added new writeAsync() methods Revision 1.38 2005/08/31 17:07:15 jonblower Fixed bug in getContents() and released ByteBuffer in fireDataArrived() Revision 1.36 2005/08/10 18:31:55 jonblower Bug fixes, plus added synchronous openOrCreate() method Revision 1.34 2005/08/05 13:46:40 jonblower Factored out all callback objects from CStyxFile into separate classes Revision 1.33 2005/08/04 16:48:57 jonblower Added and edited upload() methods in CStyxFile Revision 1.32 2005/07/28 16:37:35 jonblower Added isSameFile() method Revision 1.31 2005/07/06 17:46:19 jonblower Added setDirEntry() Revision 1.30 2005/06/27 17:18:03 jonblower Added accelerated downloading methods, and responded to changes with MessageCallback Revision 1.29 2005/06/22 17:08:34 jonblower Changed to allow target file to be null in download() Revision 1.28 2005/06/20 17:20:34 jonblower Added download() and downloadAsync() to CStyxFile Revision 1.27 2005/06/14 07:45:16 jonblower Implemented setting of params and async notification of parameter changes Revision 1.26 2005/05/26 16:48:48 jonblower Fixed bug in uploadFileAsync() Revision 1.24 2005/05/25 16:58:01 jonblower Changed implementation of openOrCreate() Revision 1.23 2005/05/25 15:36:55 jonblower No longer requires open fid, implemented createAsync() and openOrCreateAsync() methods Revision 1.22 2005/05/24 12:55:30 jonblower Added uploadFile() Revision 1.21 2005/05/23 16:48:17 jonblower Overhauled CStyxFile (esp. asynchronous methods) and StyxConnection (added cache of CStyxFiles) Revision 1.20 2005/05/23 07:36:19 jonblower Implementing uploadFileAsync Revision 1.19 2005/05/18 17:12:01 jonblower Added getURL() method Revision 1.18 2005/05/17 14:36:11 jonblower Fixed bug with getChildrenAsync() Revision 1.17 2005/05/12 15:59:59 jonblower Implemented getChildrenAsync() Revision 1.16 2005/05/12 14:20:55 jonblower Changed dataSent() method to dataWritten() (more accurate name) Revision 1.15 2005/05/12 08:00:33 jonblower Added getChildrenAsync() to CStyxFile and childrenFound() to CStyxFileChangeListener Revision 1.14 2005/05/12 07:40:52 jonblower CStyxFile.close() no longer throws a StyxException Revision 1.12 2005/05/05 07:08:37 jonblower Improved handling of buffers in change listeners Revision 1.11 2005/03/19 21:46:58 jonblower Further fixes relating to releasing ByteBuffers Revision 1.10 2005/03/18 13:55:59 jonblower Improved freeing of ByteBuffers, and bug fixes Revision 1.9 2005/03/16 17:55:52 jonblower Replaced use of java.nio.ByteBuffer with MINA's ByteBuffer to minimise copying of buffers Revision 1.8 2005/03/11 13:58:25 jonblower Merged MINA-Test_20059309 into main line of development Revision 1.7.2.3 2005/03/11 12:30:29 jonblower Changed so that message payloads are always ints, not longs Revision 1.7.2.2 2005/03/10 20:54:57 jonblower Removed references to Netty Revision 1.7.2.1 2005/03/10 11:49:17 jonblower Removed unneeded reference to StyxBuffer Revision 1.7 2005/03/07 08:29:18 jonblower Minor changes (better handling of path building) Revision 1.6 2005/02/28 11:43:36 jonblower Tidied up logging code Revision 1.5 2005/02/21 18:06:13 jonblower Un-synchronized many methods, made more robust in case of multiple calls to asynchronous methods Revision 1.4 2005/02/18 17:57:31 jonblower Changed a constructor to private access Revision 1.3 2005/02/18 09:11:35 jonblower Remove 'synchronized' from some methods, added some comments Revision 1.1.1.1 2005/02/16 18:58:17 jonblower Initial import

Method Summary

void	addChangeListener(CStyxFileChangeListener listener) Adds a CStyxFileChangeListener to this file.
void	close() Closes the file (i.e.
void	createAsync(boolean isDirectory, int permissions, int mode, MessageCallback callback) Creates this file on the remote server, provided that its parent directory exists.
void	download(java.io.File file) Downloads the data from this file and writes to a local java.io.File.
void	download(java.io.File file, int numRequests) Downloads the data from this file and writes to a local java.io.File.
void	downloadAsync(java.io.File file) Downloads the data from this file and writes to a local java.io.File.
void	downloadAsync(java.io.File file, int numRequests) Downloads the data from this file and writes to a local java.io.File.
void	downloadAsync(java.io.File file, int numRequests, MessageCallback callback) Downloads the data from this file and writes to a local java.io.File.
void	downloadAsync(java.io.File file, MessageCallback callback) Downloads the data from this file and writes to a local java.io.File.
boolean	exists() Tests to see if this file exists on the server, returning true if so and false if not.
void	fireChildrenFound() Fires the childrenFound() method on all registered listeners
void	fireCreated() Fires the fileCreated() method on all registered listeners
void	fireDataArrived(TreadMessage tReadMsg, RreadMessage rReadMsg) Fires the dataArrived() method on all registered listeners
void	fireDataWritten(TwriteMessage tWriteMsg) Fires the dataWritten() method on all registered listeners
void	fireDownloadComplete() Fires the downloadComplete() method on all registered listeners
void	fireError(java.lang.String message) Fires the error() method on all registered listeners
void	fireOpen() Fires the fileOpen() method on all registered listeners
void	fireStatChanged(RstatMessage rStatMsg) Fires the statChanged() method on all registered listeners
void	fireUploadComplete() Fires the uploadComplete() method on all registered listeners
CStyxFile[]	getChildren() Gets all the children of this directory.
void	getChildrenAsync() Reads this directory to get all its children.
StyxConnection	getConnection()
java.lang.String	getContents() Reads the entire contents of the file and returns them as a String.
DirEntry	getDirEntry()
long	getFid()
CStyxFile	getFile(java.lang.String path) Gets a reference to a file on the same connection as this CStyxFile.
java.lang.String	getGroup()
int	getIoUnit()
java.util.Date	getLastModified()
long	getLength()
static org.apache.log4j.Logger	getLogger()
int	getMode()
java.lang.String	getName() Gets the name of the file, i.e.
java.lang.String	getOwner()
java.lang.String	getParentPath() Gets the full path of the parent of this file
java.lang.String	getPath() Gets the full path of the file
Qid	getQid()
java.lang.String	getURL()
boolean	hasFid()
boolean	isAuth()
boolean	isDirectory()
boolean	isOpen()
boolean	isSameFile(CStyxFile otherFile) Returns true if this CStyxFile represents the same file on the server as the CStyxFile passed in the argument.
static void	main(java.lang.String[] args)
void	open(int mode) Opens the file on the server, i.e.
void	openAsync(int mode) Opens the file on the server.
void	openAsync(int mode, MessageCallback callback) Opens the file on the server.
CStyxFile	openFile(java.lang.String path, int mode) Gets a file on the same connection as this CStyxFile, then opens it.
void	openOrCreate(boolean isDirectory, int mode) Opens or creates this file: if the file exists it will be opened with the given mode.
void	openOrCreateAsync(boolean isDirectory, int mode, MessageCallback callback) Opens or creates this file: if the file exists it will be opened with the given mode.
org.apache.mina.common.ByteBuffer	read(long offset) Reads a chunk of data from the file.
void	readAsync(long offset) Reads a chunk of data from the file.
void	readAsync(long offset, boolean openForWriting) Reads a chunk of data from the file.
void	readAsync(long offset, int bytesRequired, boolean openForWriting, MessageCallback callback) Reads a chunk of data from the file.
void	readAsync(long offset, int bytesRequired, MessageCallback callback) Reads a chunk of data from the file.
void	readAsync(long offset, MessageCallback callback) Reads a chunk of data from the file.
void	refresh() Refreshes the stat (DirEntry) of the file.
void	refreshAsync() Refreshes the status of the file by sending a TStatMessage.
void	refreshAsync(MessageCallback callback) Refreshes the status of the file by sending a TstatMessage.
void	removeChangeListener(CStyxFileChangeListener listener) Removes the given change listener
void	setChildren(CStyxFile[] children) Sets the children of this file.
void	setContents(java.lang.String str) Sets the contents of the file to the given string.
void	setDirEntry(DirEntry dirEntry) Sets the dirEntry of this file.
void	setFid(long newFid) Sets the fid of the file.
void	setIoUnit(int newIoUnit) Sets the maximum number of bytes that can be read from or written to this file in a single operation.
void	setMode(int newMode) Set the mode of this file: this should not normally be called, except by the OpenCallback, when the file has been open
void	setQid(Qid newQid) Sets the qid of the file.
java.lang.String	toString()
void	upload(java.io.File fromFile) Uploads data from an local file to this file.
void	upload(java.io.InputStream in) Uploads data from an InputStream to this file.
void	uploadAsync(java.io.File file) Uploads data from a local java.io.File to this file.
void	uploadAsync(java.io.File file, MessageCallback callback) Uploads data from a local java.io.File to this file.
void	uploadAsync(java.io.InputStream in) Uploads data from an InputStream to this file.
void	uploadAsync(java.io.InputStream in, MessageCallback callback) Uploads data from an InputStream to this file.
void	walkFid() Gets a new fid from the pool and walks it to the location of this file.
void	walkFidAsync(MessageCallback callback) Gets a new fid from the pool and walks it to the location of this file.
long	write(byte[] bytes, int pos, int count, long offset, boolean truncate) Writes a block of data to the file at the given offset.
long	write(byte[] bytes, long offset, boolean truncate) Writes a block of data to the file at the given offset.
void	writeAll(byte[] bytes, long offset) Writes a block of data to the file at the given offset.
void	writeAsync(byte[] bytes, int pos, int count, long offset, boolean truncate, MessageCallback callback) Writes a chunk of data to the file at the given file offset.
void	writeAsync(byte[] bytes, long offset, boolean truncate) Writes a chunk of data to the file at the given file offset.
void	writeAsync(byte[] bytes, long offset, boolean truncate, MessageCallback callback) Writes a chunk of data to the file at the given file offset.
void	writeAsync(java.lang.String str, long offset) Writes a string to the file at the given offset, with truncation.
void	writeAsync(java.lang.String str, long offset, MessageCallback callback) Writes a string to the file at the given offset, with truncation.

Methods inherited from class java.lang.Object

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

Method Detail

getConnection

public StyxConnection getConnection()

Returns:

The connection on which this file sits

getName

public java.lang.String getName()

Gets the name of the file, i.e. the last part of the path

getPath

public java.lang.String getPath()

Gets the full path of the file

getParentPath

public java.lang.String getParentPath()

Gets the full path of the parent of this file

getURL

public java.lang.String getURL()

Returns:

the full URL to this file (e.g. "styx://localhost:9092/path/to/this")

isDirectory

public boolean isDirectory()
                    throws StyxException

Returns:

true if this is a directory. This method will block if it is necessary to send a message to get the stat of this file.

Throws:

StyxException

isAuth

public boolean isAuth()

Returns:

true if this is an authorization file.

getOwner

public java.lang.String getOwner()
                          throws StyxException

Returns:

the owner of the file

Throws:

StyxException

getGroup

public java.lang.String getGroup()
                          throws StyxException

Returns:

the group of the file

Throws:

StyxException

getLength

public long getLength()
               throws StyxException

Returns:

the length of the file in bytes. This method will block if it is necessary to send a message to get the stat of this file.

Throws:

StyxException

getLastModified

public java.util.Date getLastModified()
                               throws StyxException

Returns:

the last modified time of the file. This method will block if it is necessary to send a message to get the stat of this file.

Throws:

StyxException

getDirEntry

public DirEntry getDirEntry()

Returns:

the DirEntry object containing this file's attributes. If the DirEntry has not yet been set, this will return null. In this case, call refresh() on this file. Alternatively, if all you want is the Qid, it is possible that the Qid will be set, even if the DirEntry has not: try getQid().

setDirEntry

public void setDirEntry(DirEntry dirEntry)

Sets the dirEntry of this file. This method is not used often. It is most useful when creating a CStyxFile from reading a directory: in this case we have the DirEntry without having to separately stat the file.

hasFid

public boolean hasFid()

Returns:

true if a fid has been set for this file

getFid

public long getFid()

Returns:

the fid of this file

setMode

public void setMode(int newMode)

Set the mode of this file: this should not normally be called, except by the OpenCallback, when the file has been open

getMode

public int getMode()

Returns:

the mode under which this file is open, or -1 if this file is not open.

setFid

public void setFid(long newFid)

Sets the fid of the file. This should not normally be called except by GetFidCallback

setQid

public void setQid(Qid newQid)

Sets the qid of the file. This should not normally be called except by the callbacks in the uk.ac.rdg.resc.jstyx.client.callbacks package

getQid

public Qid getQid()

Returns:

the Qid of this file, or null if the qid has not yet been set

isOpen

public boolean isOpen()

Returns:

true if this file is open (i.e. its mode has been set)

isSameFile

public boolean isSameFile(CStyxFile otherFile)
                   throws StyxException

Returns true if this CStyxFile represents the same file on the server as the CStyxFile passed in the argument. This method may block if the dirEntry of one or both of the files is not set. Compares the qids of the two files (see Qid.equals())

Throws:

StyxException - if the dirEntry of one of the files was not set and there was an error getting the file's stat. If you know that the dirEntry of both files is already set, you can safely ignore this exception.

setIoUnit

public void setIoUnit(int newIoUnit)

Sets the maximum number of bytes that can be read from or written to this file in a single operation. This method should not normally be called directly, except by the OpenCallback.

getIoUnit

public int getIoUnit()

Returns:

the maximum number of bytes that can be read from or written to this file in a single operation. Will only return valid data once the file has been opened (or created).

setChildren

public void setChildren(CStyxFile[] children)

Sets the children of this file. This is not normally called directly, except by the GetChildrenCallback.

getLogger

public static org.apache.log4j.Logger getLogger()

Returns:

the Logger used by this class

walkFidAsync

public void walkFidAsync(MessageCallback callback)

Gets a new fid from the pool and walks it to the location of this file. Does not block; calls the replyArrived() method of the given callback if the walk was successful, or the error() method otherwise.

walkFid

public void walkFid()
             throws StyxException

Gets a new fid from the pool and walks it to the location of this file. This method blocks until the fid has been walked to the location of the file

Throws:

StyxException - if there was an error walking the fid (i.e. the file does not exist)

exists

public boolean exists()

Tests to see if this file exists on the server, returning true if so and false if not. This method may block (it will do so if we have to get a new fid and walk it to this file location, i.e. if the file has not been opened before).

open

public void open(int mode)
          throws StyxException

Opens the file on the server, i.e. prepares the file for reading or writing. This blocks until the open is complete. Use of this method will not cause the fileOpen() events of registered change listeners to be fired.

Parameters:

mode - Integer representing the mode - see the constants in StyxUtils. For example, to open a file for reading, use StyxUtils.OREAD. To open a file for writing with truncation use StyxUtils.OWRITE | StyxUtils.OTRUNC.

Throws:

StyxException

openAsync

public void openAsync(int mode)

Opens the file on the server. This call does not block; the fileOpen() method of any registered change listeners will be called when the Ropen message arrives. The error() method of any registered change listeners will be called if an error occurs opening the file.

Parameters:

mode - Integer representing the mode - see the constants in StyxUtils. For example, to open a file for reading, use StyxUtils.OREAD. To open a file for writing with truncation use StyxUtils.OWRITE | StyxUtils.OTRUNC.

Throws:

java.lang.IllegalStateException - if the file is already open

openAsync

public void openAsync(int mode,
                      MessageCallback callback)

Opens the file on the server. This call does not block; the replyArrived() method of the provided callback object will be called when the Ropen message arrives. The error() method of the provided callback will be called if an error occurred when opening the file, or if the file was already open under a different mode.

Parameters:

mode - Integer representing the mode - see the constants in StyxUtils. For example, to open a file for reading, use StyxUtils.OREAD. To open a file for writing with truncation use StyxUtils.OWRITE | StyxUtils.OTRUNC.

callback - The MessageCallback object that will handle the Ropen message

createAsync

public void createAsync(boolean isDirectory,
                        int permissions,
                        int mode,
                        MessageCallback callback)

Creates this file on the remote server, provided that its parent directory exists. Sends an error message to the callback if the file already exists.

openOrCreateAsync

public void openOrCreateAsync(boolean isDirectory,
                              int mode,
                              MessageCallback callback)

Opens or creates this file: if the file exists it will be opened with the given mode. If it does not exist it will be created, provided that the parent directory exists. Files will be created with 0666 permissions and directories with 0777, subject to the permissions of the parent directory.

openOrCreate

public void openOrCreate(boolean isDirectory,
                         int mode)
                  throws StyxException

Opens or creates this file: if the file exists it will be opened with the given mode. If it does not exist it will be created, provided that the parent directory exists. Files will be created with 0666 permissions and directories with 0777, subject to the permissions of the parent directory. Blocks until the opening or creation is complete

Throws:

StyxException

close

public void close()

Closes the file (i.e. clunks the fid). If the fid isn't set, this will do nothing. This sends the Tclunk message but does not wait for a reply (this doesn't matter because the rules of Styx say that the fid of the file is invalid as soon as the Tclunk is sent, whether the Rclunk arrives or not). I.e. this method will not block. The Rclunk message is handled in the StyxConnection class.

read

public org.apache.mina.common.ByteBuffer read(long offset)
                                       throws StyxException

Reads a chunk of data from the file. Reads the maximum amount of data allowed in a single message, starting at the given file offset. Blocks until the server replies with the data. When you have finished with the data in the ByteBuffer that is returned, call release() on the buffer to ensure that the buffer can be re-used.

Returns:

a ByteBuffer containing the data that have been read. The position and limit of this buffer will be set correctly. Note that the position may not necessarily be zero (the buffer may well contain the entire contents of an RreadMessage, header and all).

Throws:

StyxException

readAsync

public void readAsync(long offset)

Reads a chunk of data from the file. Reads the maximum amount of data allowed in a single message, starting at the given file offset. If the file was not open before this method is called, the file will be opened with mode StyxUtils.OREAD (but the fileOpen() event will not be fired). Returns immediately; the dataArrived() events of registered CStyxFileChangeListeners will be called when the data arrive, and the error() events of registered CStyxFileChangeListeners will be called if an error occurs.

readAsync

public void readAsync(long offset,
                      boolean openForWriting)

Reads a chunk of data from the file. Reads the maximum amount of data allowed in a single message, starting at the given file offset. If the file was not open before this method is called, the file will be opened (but the fileOpen() event will not be fired). Returns immediately; the dataArrived() events of registered CStyxFileChangeListeners will be called when the data arrive, and the error() events of registered CStyxFileChangeListeners will be called if an error occurs.

Parameters:

offset - The index of the first byte of data in the file to read

openForWriting - If this is true, the file will be opened for reading and writing with truncation, provided that the file is not open already. If this is false, the file will be opened for reading only

readAsync

public void readAsync(long offset,
                      MessageCallback callback)

Reads a chunk of data from the file. Reads the maximum number of bytes allowed in a single message, starting at the given file offset. If the file was not open before this method is called, the file will be opened for reading only (but the fileOpen() event will not be fired). Returns immediately; the replyArrived() events of the provided callback will be called when the data arrive, and the error() method of the callback will be called if an error occurs. When the reply arrives, the data will be contained in a ByteBuffer that is part of the RreadMessage: use RreadMessage.getData() to get the buffer. After you have finished with the buffer, call release() on the buffer to return it to the pool.

readAsync

public void readAsync(long offset,
                      int bytesRequired,
                      MessageCallback callback)

Reads a chunk of data from the file. Sends request to read the given number of bytes, starting at the given file offset. If bytesRequired < 0, the maximum number of bytes allowed in a single message will be read. If the file was not open before this method is called, the file will be opened for reading (but the fileOpen() event will not be fired). Returns immediately; the replyArrived() events of the provided callback will be called when the data arrive, and the error() method of the callback will be called if an error occurs. When the reply arrives, the data will be contained in a ByteBuffer that is part of the RreadMessage: use RreadMessage.getData() to get the buffer. After you have finished with the buffer, call release() on the buffer to return it to the pool.

Parameters:

offset - The index of the first byte of data in the file to read

bytesRequired - The maximum number of bytes required

callback - The class that will be notified if the read was successful, or if there was an error

readAsync

public void readAsync(long offset,
                      int bytesRequired,
                      boolean openForWriting,
                      MessageCallback callback)

Reads a chunk of data from the file. Sends request to read the given number of bytes, starting at the given file offset. If bytesRequired < 0, the maximum number of bytes allowed in a single message will be read. Returns immediately; the replyArrived() events of the provided callback will be called when the data arrive, and the error() method of the callback will be called if an error occurs. When the reply arrives, the data will be contained in a ByteBuffer that is part of the RreadMessage: use RreadMessage.getData() to get the buffer. After you have finished with the buffer, call release() on the buffer to return it to the pool.

Parameters:

offset - The index of the first byte of data in the file to read

bytesRequired - The maximum number of bytes required

openForWriting - If this is true, the file will be opened for reading and writing with truncation, provided that the file is not open already. If this is false, the file will be opened for reading only

callback - The class that will be notified if the read was successful, or if there was an error

getContents

public java.lang.String getContents()
                             throws StyxException

Reads the entire contents of the file and returns them as a String. This should only be used for relatively short files that can sensibly fit into a String - do not use for large files as not only will this method block until the file is read, you may run into memory problems.

Throws:

StyxException

setContents

public void setContents(java.lang.String str)
                 throws StyxException

Sets the contents of the file to the given string. Overwrites anything else in the file. Writes EOF and closes the file after use unless the file was open before this method was called. If the file was open before this message is called, it must be open for writing with truncation (i.e. StyxUtils.OWRITE | StyxUtils.OTRUNC)

Parameters:

str - The new file contents

Throws:

StyxException - if there was an error opening or writing to the file

writeAll

public void writeAll(byte[] bytes,
                     long offset)
              throws StyxException

Writes a block of data to the file at the given offset. Will write the data in several separate messages if necessary. The file will be truncated at the end of the new data.

Throws:

StyxException - if there is an error writing to the file

write

public long write(byte[] bytes,
                  long offset,
                  boolean truncate)
           throws StyxException

Writes a block of data to the file at the given offset. Cannot write more than this.getIOUnit() bytes in a single message. Blocks until the write confirmation arrives. Does not change the offset of the file

Parameters:

bytes - The data to write. Will attempt to write all the data in this array.

offset - The position in the file at which to write the data

truncate - True if the file is to be truncated at the end of the new data

Returns:

The number of bytes written to the file

Throws:

StyxException - if there is an error writing to the file

write

public long write(byte[] bytes,
                  int pos,
                  int count,
                  long offset,
                  boolean truncate)
           throws StyxException

Writes a block of data to the file at the given offset. Cannot write more than this.getIOUnit() bytes in a single message. Blocks until the write confirmation arrives. Does not change the offset of the file

Parameters:

bytes - The data to write.

pos - The index of the first data point in the byte array to write

count - The number of bytes from the input array to write

offset - The position in the file at which to write the data

truncate - True if the file is to be truncated at the end of the new data

Returns:

The number of bytes written to the file

Throws:

StyxException - if there is an error writing to the file

writeAsync

public void writeAsync(java.lang.String str,
                       long offset)

Writes a string to the file at the given offset, with truncation. When the write confirmation arrives, the dataWritten() method of any registered CStyxFileChangeListeners will be called. The file will be truncated at the end of the string.

writeAsync

public void writeAsync(java.lang.String str,
                       long offset,
                       MessageCallback callback)

Writes a string to the file at the given offset, with truncation. When the write confirmation arrives, the callback's replyArrived() method will be called. The callback's error() method will be called if an error occurs. The file will be truncated at the end of the string.

writeAsync

public void writeAsync(byte[] bytes,
                       long offset,
                       boolean truncate)

Writes a chunk of data to the file at the given file offset. Returns immediately; the dataWritten() method of any waiting change listeners will be called when the write confirmation arrives, and the error() method of any waiting change listeners will be called if an error occurs.

Parameters:

bytes - The byte array containing the data to write. This will attempt to write all the data in the array

offset - The position in the file at which the data will be written

truncate - True if the file should be truncated at the end of the new data

writeAsync

public void writeAsync(byte[] bytes,
                       long offset,
                       boolean truncate,
                       MessageCallback callback)

Writes a chunk of data to the file at the given file offset. Returns immediately; the callback's replyArrived() method will be called when the reply arrives and the callback's error() method will be called if an error occurs.

Parameters:

bytes - The array of bytes to write

offset - The position in the file at which the data will be written

truncate - If this is true, the file will be truncated at the end of the new data

callback - The replyArrived() method of this callback object will be called when the write confirmation arrives

writeAsync

public void writeAsync(byte[] bytes,
                       int pos,
                       int count,
                       long offset,
                       boolean truncate,
                       MessageCallback callback)

Writes a chunk of data to the file at the given file offset. Returns immediately; the callback's replyArrived() method will be called when the reply arrives and the callback's error() method will be called if an error occurs.

Parameters:

bytes - The array of bytes to write

pos - The position in the array of the first byte to write

count - The number of bytes from the byte array to write

offset - The position in the file at which the data will be written

truncate - If this is true, the file will be truncated at the end of the new data

callback - The replyArrived() method of this callback object will be called when the write confirmation arrives

refresh

public void refresh()
             throws StyxException

Refreshes the stat (DirEntry) of the file. Blocks until the operation is complete. Does not fire the statChanged() event on any registered change listeners.

Throws:

StyxException

refreshAsync

public void refreshAsync()

Refreshes the status of the file by sending a TStatMessage. Does not wait for a reply; when the reply arrives, the dirEntry of this file will be set and the statChanged() event of any registered change listeners will be fired.

refreshAsync

public void refreshAsync(MessageCallback callback)

Refreshes the status of the file by sending a TstatMessage. Does not wait for a reply; when the reply arrives, the dirEntry of this file will be set and the replyArrived() method of the provided callback object will be called with an RwalkMessage as the argument.

getFile

public CStyxFile getFile(java.lang.String path)

Gets a reference to a file on the same connection as this CStyxFile. This does not open, create or check the existence of the file: no messages are sent to the server in this method so this will never block.

Parameters:

path - The path of the file to be opened, relative to this file.

Throws:

InvalidPathException - if the path is not valid

openFile

public CStyxFile openFile(java.lang.String path,
                          int mode)
                   throws StyxException

Gets a file on the same connection as this CStyxFile, then opens it. This blocks until the file is opened.

Parameters:

path - The path of the file to be opened, relative to this file.

mode - The mode with which to open the file

Throws:

StyxException - if the file could not be opened with the given mode

getChildren

public CStyxFile[] getChildren()
                        throws StyxException

Gets all the children of this directory. If this is not a directory, this will return null (TODO: does it? Or does it throw an Exception?). (For an empty directory, this will return a zero- length array.) This method blocks until the directory has been read.

Throws:

StyxException

getChildrenAsync

public void getChildrenAsync()

Reads this directory to get all its children. When the process is completed the childrenFound() event is fired on all registered listeners.

download

public void download(java.io.File file)
              throws StyxException

Downloads the data from this file and writes to a local java.io.File. If this file already exists it will be overwritten. This method blocks; it returns when the download is complete and throws a StyxException if an error occurs.

Parameters:

file - The java.io.File to which the data will be written. If this file already exists it will be overwritten. If this is null, the data will be downloaded but not written to a file

Throws:

StyxException

download

public void download(java.io.File file,
                     int numRequests)
              throws StyxException

Downloads the data from this file and writes to a local java.io.File. If this file already exists it will be overwritten. This method blocks; it returns when the download is complete and throws a StyxException if an error occurs.

Parameters:

file - The java.io.File to which the data will be written. If this file already exists it will be overwritten. If this is null, the data will be downloaded but not written to a file

numRequests - The number of simultaneous read requests that will be sent. The download may proceed faster with a larger number of simultaneous read requests. If numRequests > 1, the file on the remote server must be seekable otherwise unpredictable behaviour may result.

Throws:

StyxException

downloadAsync

public void downloadAsync(java.io.File file,
                          int numRequests)

Downloads the data from this file and writes to a local java.io.File. This method returns immediately; when the download has finished, the downloadComplete() event will be fired all all registered change listeners.

Parameters:

file - The java.io.File to which the data will be written. If this file already exists it will be overwritten.

numRequests - The number of simultaneous read requests that will be sent. The download may proceed faster with a larger number of simultaneous read requests. If numRequests > 1, the file on the remote server must be seekable otherwise unpredictable behaviour may result.

downloadAsync

public void downloadAsync(java.io.File file)

Downloads the data from this file and writes to a local java.io.File. This method returns immediately; when the download has finished, the downloadComplete() event will be fired all all registered change listeners.

Parameters:

file - The java.io.File to which the data will be written. If this file already exists it will be overwritten.

downloadAsync

public void downloadAsync(java.io.File file,
                          MessageCallback callback)

Downloads the data from this file and writes to a local java.io.File. This method returns immediately; when the download has finished, the replyArrived() method of the given MessageCallback will be called.

Parameters:

file - The java.io.File to which the data will be written. If this file already exists it will be overwritten.

downloadAsync

public void downloadAsync(java.io.File file,
                          int numRequests,
                          MessageCallback callback)

Downloads the data from this file and writes to a local java.io.File. This method returns immediately; when the download has finished, the replyArrived() method of the given MessageCallback will be called.

Parameters:

file - The java.io.File to which the data will be written. If this file already exists it will be overwritten.

numRequests - The number of simultaneous read requests that will be sent. The download may proceed faster with a larger number of simultaneous read requests. If numRequests > 1, the file on the remote server must be seekable otherwise unpredictable behaviour may result.

Throws:

java.lang.IllegalArgumentException - if numRequests is less than 1 or greater than 100.

upload

public void upload(java.io.InputStream in)
            throws StyxException

Uploads data from an InputStream to this file. If this file does not exist it will be created with rw-rw-rw- (0666) permissions, subject to the permissions of the host directory. Blocks until the file has been uploaded, or throws a StyxException if an error occurred. After the upload is complete, the InputStream will not be closed.

Parameters:

in - The InputStream from which to read data to be written to this file

Throws:

StyxException

upload

public void upload(java.io.File fromFile)
            throws StyxException

Uploads data from an local file to this file. If this (Styx) file does not exist it will be created with rw-rw-rw- (0666) permissions, subject to the permissions of the host directory. Blocks until the file has been uploaded, or throws a StyxException if an error occurred.

Parameters:

fromFile - The File from which to read data to be written to this file

Throws:

StyxException

uploadAsync

public void uploadAsync(java.io.InputStream in)

Uploads data from an InputStream to this file. If this file does not exist it will be created with rw-rw-rw- (0666) permissions, subject to the permissions of the host directory. When the process is finished, the uploadComplete() event will be fired on all registered CStyxFileChangeListeners. If an error occurs, the error() event will be fired on registered change listeners. After the upload is complete, the InputStream will not be closed.

Parameters:

in - The InputStream from which to read data to be written to this file

uploadAsync

public void uploadAsync(java.io.InputStream in,
                        MessageCallback callback)

Uploads data from an InputStream to this file. If this file does not exist it will be created with rw-rw-rw- (0666) permissions, subject to the permissions of the host directory. When the process is finished, the replyArrived() method of the provided callback object will be called. If an error occurs, the error() method of the provided callback object will be called.

Parameters:

in - The InputStream from which to read data to be written to this file

callback - The MessageCallback that will be notified when the upload process is complete.

uploadAsync

public void uploadAsync(java.io.File file)

Uploads data from a local java.io.File to this file. If this (Styx) file does not exist it will be created with rw-rw-rw- (0666) permissions, subject to the permissions of the host directory. When the process is finished, the uploadComplete() event will be fired on all registered CStyxFileChangeListeners. If an error occurs, the error() event will be fired on registered change listeners.

Parameters:

file - The File to copy/upload

uploadAsync

public void uploadAsync(java.io.File file,
                        MessageCallback callback)

Uploads data from a local java.io.File to this file. If this (Styx) file does not exist it will be created with rw-rw-rw- (0666) permissions, subject to the permissions of the host directory. When the process is finished, the replyArrived() method of the provided callback object will be called. If an error occurs, the error() method of the provided callback object will be called.

Parameters:

file - The File to copy/upload

callback - The MessageCallback that will be notified when the upload process is complete.

addChangeListener

public void addChangeListener(CStyxFileChangeListener listener)

Adds a CStyxFileChangeListener to this file. The methods of the change listener will be called when events happen, such as new data arriving or a change in permissions, etc (note that this notification will only happen if the changes are made by calling methods of this CStyxFile instance. If another client makes changes, we will not be notified here). If this listener is already registered, this method does nothing.

removeChangeListener

public void removeChangeListener(CStyxFileChangeListener listener)

Removes the given change listener

fireError

public void fireError(java.lang.String message)

Fires the error() method on all registered listeners

fireOpen

public void fireOpen()

Fires the fileOpen() method on all registered listeners

fireCreated

public void fireCreated()

Fires the fileCreated() method on all registered listeners

fireDataArrived

public void fireDataArrived(TreadMessage tReadMsg,
                            RreadMessage rReadMsg)

Fires the dataArrived() method on all registered listeners

fireStatChanged

public void fireStatChanged(RstatMessage rStatMsg)

Fires the statChanged() method on all registered listeners

fireDataWritten

public void fireDataWritten(TwriteMessage tWriteMsg)

Fires the dataWritten() method on all registered listeners

fireChildrenFound

public void fireChildrenFound()

Fires the childrenFound() method on all registered listeners

fireUploadComplete

public void fireUploadComplete()

Fires the uploadComplete() method on all registered listeners

fireDownloadComplete

public void fireDownloadComplete()

Fires the downloadComplete() method on all registered listeners

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

Returns:

The name of the file (not the full path).

main

public static void main(java.lang.String[] args)