Package gnu.cajo.utils.extra
Class Xfile
java.lang.Object
gnu.cajo.utils.extra.Xfile
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
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate byte[]
private InputStream
private final int
static boolean
This field can allow the static fetch method to be invoked by a remote client.private final byte[]
-
Constructor Summary
ConstructorsConstructorDescriptionXfile
(int maxBlock) The constructor simply sets the maximum transfer block size. -
Method Summary
Modifier and TypeMethodDescriptionstatic void
This is the only method used by clients, it fetches the file from the specified source, and saves it to the specified destination.byte[]
This method is called by the client's static fetch method, to request subsequent blocks of the file, until the transfer is complete.void
This method is called by the client's static fetch method, to open a resource on a remote Java Virtual Machine.
-
Field Details
-
stub
private final byte[] stub -
maxBlock
private final int maxBlock -
is
-
block
private byte[] block -
remoteInvoke
public static boolean remoteInvokeThis 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 Details
-
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 Details
-
open
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
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
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.
-