Class ClientProxy

  • All Implemented Interfaces:
    Invoke, java.io.Serializable, java.rmi.Remote

    public final class ClientProxy
    extends java.lang.Object
    implements Invoke
    This class is used to send server item callbacks to a firewalled client. A client whose firewall settings prohibit incoming socket connections is a common problem. This class is called ClientProxy, as it is a stand-in representation of a remote reference to a client, behind a firewall. This allows server objects to be designed without regard to client firewall issues. An intermediary process would give the server item a real remote reference to the client object when there is no client firewall, or a ClientProxy when there is. The client links the remote reference to this ClientProxy, to the locally firewalled client, using an ItemProxy object. The server item invokes methods on this client proxy which result in an immediate callback invocation on the client.

    Note: this paradigm is not threadsafe! It is expected that callbacks to the remote client will not be invoked reentrantly. Correspondingly, a unique instance of this object must be given to each remote client object. A practical usage example is available online.

    Version:
    1.0, 28-Mar-04 Initial release
    See Also:
    Serialized Form
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private java.lang.Object args  
      private boolean connected  
      private boolean done  
      private java.lang.String method  
      Remote remoteThis
      This is the remoted reference to the server's ClientProxy.
      int timeout
      This is the longest value, in milliseconds, that the server will wait for a client invocation to execute before it aborts it.
    • Constructor Summary

      Constructors 
      Constructor Description
      ClientProxy()
      A server creates this object, then provides the remote reference member remoteThis to the client.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void cutOff()
      This method abruptly terminates the ClientProxy link to the server.
      java.lang.Object invoke​(java.lang.String method, java.lang.Object args)
      This method serves two fundamentally different, but symmetrical purposes.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • method

        private java.lang.String method
      • args

        private java.lang.Object args
      • done

        private boolean done
      • connected

        private boolean connected
      • timeout

        public int timeout
        This is the longest value, in milliseconds, that the server will wait for a client invocation to execute before it aborts it. It is set by default to 5000 (5 seconds). Depending on the type of functionality being performed in the client methods, this time may require adjusting. When it is changed, the new value will apply for all subsequent calls.
      • remoteThis

        public final Remote remoteThis
        This is the remoted reference to the server's ClientProxy. It is passed back to the client, to be used int the ItemProxy constructor, to create a firewall traversing asynchronous callback link. In order to work, logically, it can only be passed to one remote client.
    • Constructor Detail

      • ClientProxy

        public ClientProxy()
                    throws java.rmi.RemoteException
        A server creates this object, then provides the remote reference member remoteThis to the client. This creates the first half of the bridge, the ItemProxy class completes the second half.
        Throws:
        java.rmi.RemoteException - If the remote reference creation fails.
    • Method Detail

      • cutOff

        public void cutOff()
                    throws java.rmi.NoSuchObjectException
        This method abruptly terminates the ClientProxy link to the server. The client can detect the detachment, if it wishes, by implementing a similar cutOff method. The client may also remotely invoke this method, if it wishes to sever its link to the server. Any subsequent invocations by the server will result in client timeout exceptions. This method also calls notify(), in case there was an invocation in process when this happened. Note: it would not make sense to call this method more than once, ever, for a given object instance.
        Throws:
        java.rmi.NoSuchObjectException - Should this method ever be called more than once, on the same object.
      • invoke

        public java.lang.Object invoke​(java.lang.String method,
                                       java.lang.Object args)
                                throws java.lang.Exception
        This method serves two fundamentally different, but symmetrical purposes. Initially a remote ItemProxy calls this method to have its calling thread blocked until the server item needs to make an asynchronous callback. Secondly, the server item will also invoke this method, and will have its thread blocked, until the resulting data, or exception, is returned from the firewalled client, via its ItemProxy.
        Specified by:
        invoke in interface Invoke
        Parameters:
        method - The name of the method on the firewalled remote client to be invoked asynchronously.
        args - The data to be provided the method of the callback method, or data resulting from the client callback.
        Returns:
        The result of the client object callback.
        Throws:
        java.lang.InterruptedException - If the client is not listening, or if the callback timeout has expired.
        java.rmi.RemoteException - For any network related failures.
        java.lang.Exception - For any client specific reasons.