Class ItemProxy

  • All Implemented Interfaces:
    java.lang.Runnable

    public final class ItemProxy
    extends java.lang.Thread
    This class is used to receive server item callbacks by a firewalled client. A client whose firewall settings prohibit incoming socket connections is a common problem. To solve this, a client would request a remote reference to a ClientProxy from the server. It would then use an ItemProxy to link the remote item to the local client item. This class is a special purpose thread, which will make an outgoing call to the remote ClientProxy. This outgoing call will be blocked until the server has some data for it, at which point it will wake this thread, causing it to return with the callback method to be invoked on the local client object, and the data to be provided it. This object will call its local client, and return the resulting data, or exception to the server. This will result in this thread being put back to sleep again, until there is another callback. This lets local client objects be designed without regard for whether they will be behind a firewall or not. This technique enables asynchronous server callbacks using the client's outgoing socket, thereby solving the firewall issue. The development of this process was originally championed by project member Fredrik Larsen.

    Normally, a client would not invoke a method on the remote reference it receives to the server's ClientProxy object. However, if the client wishes to forcibly terminate its connection with the server, it can invoke a no-arg cutOff method on the reference. (See the note below)

    Note: The server could cut its connection to the client at any time, either intentionally by invoking its cutOff method, or worse, by a server crash. If the client wishes to be notified of this event, it must define a null argument method called cutOff. This will be invoked by the ItemProxy, in that event the cutOff method must accept a single argument, of type Exception, it will describe the reason behind the disconnection. A practical usage example is available online.
    Version:
    1.0, 28-Mar-04 Initial release
    • Nested Class Summary

      • Nested classes/interfaces inherited from class java.lang.Thread

        java.lang.Thread.State, java.lang.Thread.UncaughtExceptionHandler
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private java.lang.Object client  
      private java.lang.Object item  
      • Fields inherited from class java.lang.Thread

        MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY
    • Constructor Summary

      Constructors 
      Constructor Description
      ItemProxy​(RemoteInvoke item, java.lang.Object client)
      The constructor links the remote object to the firewalled client.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void run()
      The processing thread, and the crux of this technique.
      • Methods inherited from class java.lang.Thread

        activeCount, checkAccess, clone, countStackFrames, currentThread, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, onSpinWait, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, suspend, toString, yield
      • Methods inherited from class java.lang.Object

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

      • item

        private final java.lang.Object item
      • client

        private final java.lang.Object client
    • Constructor Detail

      • ItemProxy

        public ItemProxy​(RemoteInvoke item,
                         java.lang.Object client)
        The constructor links the remote object to the firewalled client. It will automatically start the thread, which will call the remote ClientProxy, blocking until there is a callback method to be invoked.
        Parameters:
        item - A remote reference to a ClientProxy, from which the remote object will invoke asynchronous callbacks
        client - The firewalled local object that wishes to receive asynchronous callbacks
    • Method Detail

      • run

        public void run()
        The processing thread, and the crux of this technique. This thread starts out by calling the remote ClientProxy, to enter a blocking wait. The ClientProxy will wake the thread, providing it an object array containing two things; the name of the method to be called on the local object, and the data to be provided it. This thread will invoke the local object's method, and return the result, or exception, to the ClientProxy, beginning the cycle again.
        Specified by:
        run in interface java.lang.Runnable
        Overrides:
        run in class java.lang.Thread