Class Xfile


  • public class Xfile
    extends java.lang.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[] block  
      private java.io.InputStream is  
      private int maxBlock  
      static boolean remoteInvoke
      This field can allow the static fetch method to be invoked by a remote client.
      private byte[] stub  
    • Constructor Summary

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

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static void fetch​(java.lang.Object item, java.lang.String source, java.lang.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​(java.lang.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

      • stub

        private final byte[] stub
      • maxBlock

        private final int maxBlock
      • is

        private java.io.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 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:
        java.lang.IllegalArgumentException - if the max block argument is less than 256 bytes, or greater than 1MB.
    • Method Detail

      • open

        public void open​(java.lang.String source)
                  throws java.io.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:
        java.io.IOException - If the specified resource does not exist, or cannot be opened.
      • nextBlock

        public byte[] nextBlock()
                         throws java.io.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:
        java.io.IOException - If a stream is not currently open, or if a read, or close error occurred.
      • fetch

        public static void fetch​(java.lang.Object item,
                                 java.lang.String source,
                                 java.lang.String dest)
                          throws java.lang.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:
        java.io.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.
        java.rmi.RemoteException - If a remote method invocation, involved in the data transfer, fails.
        java.lang.IllegalAccessException - If this method is being invoked by a remote JVM, and remote invocation has not been enabled.
        java.lang.Exception - By the remote JVM, if the operation is not supported.