gnu.cajo.utils.extra

Class Xfile

java.lang.Object

gnu.cajo.utils.extra.Xfile

public class Xfile
extends Object

This class is used to transfer files between Java Virtual Machines. This class normally resides in the codebase of both the client, and the server. A client invokes only the static fetch method. This will implicitly use the open and nextBlock methods on the server Xfile object, to complete the transfer. A server simply instantiates, and remotes an Xfile object, to enable file transfers. For threadsafety; a server should give each client a unique instance of this class.

Note: this object will try to send any file the client requests, therefore it should either be used by trusted clients, or with access priviliges appropriately locked down. Another option is to override the open method in a subclass, to check the requested resource against an approved list, throwing an exception if not.

Version:

1.0, 25-Jan-06 Initial release

Author:

John Catherino

Field Summary

Fields

Modifier and Type	Field and Description
static boolean	remoteInvoke This field can allow the static fetch method to be invoked by a remote client.

Constructor Summary

Constructors

Constructor and Description
Xfile(int maxBlock) The constructor simply sets the maximum transfer block size.

Method Summary

Methods

Modifier and Type	Method and Description
static void	fetch(Object item, String source, String dest) This is the only method used by clients, it fetches the file from the specified source, and saves it to the specified destination.
byte[]	nextBlock() This method is called by the client's static fetch method, to request subsequent blocks of the file, until the transfer is complete.
void	open(String source) This method is called by the client's static fetch method, to open a resource on a remote Java Virtual Machine.

Methods inherited from class java.lang.Object

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

Field Detail

remoteInvoke

public static boolean remoteInvoke

This field can allow the static fetch method to be invoked by a remote client. By default its value is false, prohibiting this functionality. Enabling this opens the possibility for a client to direct a server object to transfer a file into itself, from yet some other remote location, or even to transfer the data to yet another remote location. This is a heady concept; an Xfile object can operate simultaneously as a client, and a server; the implications are worthy of contemplation, before enabling.

Constructor Detail

Xfile

public Xfile(int maxBlock)

The constructor simply sets the maximum transfer block size.

Parameters:

maxBlock - The largest possible block to return from the nextBlock method. It is suggested not to exceed 64k bytes.

Throws:

IllegalArgumentException - if the max block argument is less than 256 bytes, or greater than 1MB.

Method Detail

open

public void open(String source)
          throws IOException

This method is called by the client's static fetch method, to open a resource on a remote Java Virtual Machine. Only one resource may be open at a time. If a resource is currently open when this method is called, the currently open resource stream will then be closed silently. If the server is deployed in a jar file, it will check within its jar first, to try to find the resource, before looking outside.

Parameters:

source - The resource to be loaded, typically the path and name of the file on the server's local filesystem.

Throws:

IOException - If the specified resource does not exist, or cannot be opened.

nextBlock

public byte[] nextBlock()
                 throws IOException

This method is called by the client's static fetch method, to request subsequent blocks of the file, until the transfer is complete. It will transfer the number of bytes available from the stream, at the time of invocation, up to the maximum block size, specified in its constructor. It will close the source stream automatically, with the request of the final data block.

Returns:

The next variably sized block from the source stream.

Throws:

IOException - If a stream is not currently open, or if a read, or close error occurred.

fetch

public static void fetch(Object item,
         String source,
         String dest)
                  throws Exception

This is the only method used by clients, it fetches the file from the specified source, and saves it to the specified destination. It will first invoke the open method on the server item reference, it will then call nextBlock repeatedly, storing the results, until the entire file has been transferred. This method is synchronized, to provide threadsafety on the client side.

As a special case; the source and/or destination arguments can be URLs.

For example:

• file://path/name.ext
• http://host/path/name.ext
• ftp://[username:password@]host/path/name.ext

however, only as permitted by the SecurityPolicy of the client and server JVMs, and supported by their installed protocol handlers.

Parameters:

item - The object, presumably a remote reference to an Xfile object, with which to fetch the resource.

source - The file resource, typically the path and name of the file in the server's local filesystem, to be transferred.

dest - The resource, typically the path and name of the file in the clients's local filesystem, in which to transfer the data. If the destination is local, and the path does not exist, it will attempt to create it automatically.

Throws:

IOException - If the source is invalid, the destination is invalid, or either could not be opened. If the destination already exists, it will be overwritten.

RemoteException - If a remote method invocation, involved in the data transfer, fails.

IllegalAccessException - If this method is being invoked by a remote JVM, and remote invocation has not been enabled.

Exception - By the remote JVM, if the operation is not supported.