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
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private 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

    Constructors
    Constructor
    Description
    Xfile(int maxBlock)
    The constructor simply sets the maximum transfer block size.
  • Method Summary

    Modifier and Type
    Method
    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[]
    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 Details

    • stub

      private final byte[] stub
    • maxBlock

      private final int maxBlock
    • is

      private InputStream is
    • block

      private byte[] block
    • 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 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

      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.