Package gnu.cajo

Class Cajo

  • All Implemented Interfaces:
    Grail

    public final class Cajo
    extends java.lang.Object
    implements Grail
    This class implements the Generic Standard Interface for the cajo library. It is designed to work with all JRE's: 1.3 and higher.
    Version:
    1.0, 21-Aug-07
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  Cajo.Purger
      This internal use only helper class automatically removes unresponsive server references from the internal queue.
      static class  Cajo.Registrar
      This internal use only helper class maintains a registry of exported objects.
      static class  Cajo.Searchable
      This internal use only helper class scans an exported object to see if it has methods matching the client method set.
    • Constructor Summary

      Constructors 
      Constructor Description
      Cajo​(int port, java.lang.String serverHost, java.lang.String clientHost)
      The constructor configures the network address settings.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void export​(java.lang.Object object)
      This method makes any object's public methods, whether instance or static, remotely invocable.
      protected void finalize()  
      java.lang.Object[] lookup​(java.lang.Class methodSetInterface)
      This method finds all remotely invocable objects, supporting the specified method set.
      static void main​(java.lang.String[] args)
      Technically this method is unrelated to the class, it is used to furnish library version information.
      static java.lang.Object proxy​(java.lang.Object object)
      This method is used to allow clients to pass references to its own local objects, to other JVMs.
      java.lang.Object proxy​(java.lang.Object reference, java.lang.Class methodSetInterface)
      This method instantiates a Dynamic Proxy at the client, which implements the method set specified.
      void register​(java.lang.String hostname, int port)
      This method is used to manually collect remote registry entries.
      • Methods inherited from class java.lang.Object

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

      • multicast

        private final Multicast multicast
      • items

        private final java.util.Vector items
    • Constructor Detail

      • Cajo

        public Cajo​(int port,
                    java.lang.String serverHost,
                    java.lang.String clientHost)
             throws java.net.UnknownHostException,
                    java.io.IOException
        The constructor configures the network address settings. If a machine is operating behind a Network Adress Translating router (NAT), the internal and external addresses are requried. If not, then both addresses can be the same, or null arguments can be used.
        Parameters:
        port - The TCP port to be used for communications, for servers canonically it is the IANA assigned cajo port of 1198, for clients it can be any value, including 0, meaining chosen from any unused port available at the time of startup
        serverHost - The local network interface on which the item will will be remotely invokable. Typically it is specified when the server has multiple phyisical network interfaces, or is multi-homed, i.e. having multiple logical network interfaces. The value can be null, which will make the item accessible on all network interfaces, this is identical to providing the special port address "0.0.0.0".
        clientHost - The host name, or IP address the remote client will use to communicate with this server. If null, it will be the same as serverHost resolution. This would need to be explicitly specified if the server is operating behind NAT; i.e. when the server's subnet IP address is not the same as its address outside the subnet.
        Throws:
        UnknownHostException - If the either host address/name cannot be resolved, or is invalid
        java.io.IOException - If the startup announcement datagram packet could not be sent
    • Method Detail

      • finalize

        protected void finalize()
                         throws java.lang.Throwable
        Overrides:
        finalize in class java.lang.Object
        Throws:
        java.lang.Throwable
      • export

        public void export​(java.lang.Object object)
                    throws java.io.IOException
        This method makes any object's public methods, whether instance or static, remotely invocable. As the object being remoted is already instantiated, there is no artificial requirement for it to implement a no-arg constructor. If not all methods are safe to be made remotely invocable, then wrap the object with a special-case decorator.

        Note: if an object is exported more than once, it will be registered each time, you generally do not want to do this. Also, if you plan to use the register method, to contact remote registries directly, it is highly advisible to export all objects prior to doing so.

        Specified by:
        export in interface Grail
        Parameters:
        object - The POJO to be made remotely invocable, i.e. there is no requirement for it to implement any special interfaces, nor to be derived from any particular class
        Throws:
        java.rmi.RemoteException - If the internal registry could not be created
        java.io.IOException - If the announcement datagram packet could not be sent
      • lookup

        public java.lang.Object[] lookup​(java.lang.Class methodSetInterface)
                                  throws java.lang.Exception
        This method finds all remotely invocable objects, supporting the specified method set. The method set is a client defined interface. It specifies the method signatures required.
        Specified by:
        lookup in interface Grail
        Parameters:
        methodSetInterface - The interface of methods that remote objects are required to support
        Returns:
        An array of remote object references, specific to the framework, implementing the specified method collection
        Throws:
        java.lang.Exception - For any network or framework specific reasons
        java.lang.IllegalArgumentException - when the provided class is not a Java interface
      • proxy

        public java.lang.Object proxy​(java.lang.Object reference,
                                      java.lang.Class methodSetInterface)
        This method instantiates a Dynamic Proxy at the client, which implements the method set specified. This allows a remote object reference to be used in a semantically identical fashion as if it were local. The proxies can, if the service object reference is serialisable, be freely passed between JVMs, or persisted to storage for later use.
        Specified by:
        proxy in interface Grail
        Parameters:
        reference - A reference to a remote object returned by the lookup method of this interface, though actually, any object reference implementing the client method set would work
        methodSetInterface - The set (or subset) of public methods, static or instance, that the object reference implements
        Returns:
        An object implementing the method set interface provided.
      • proxy

        public static java.lang.Object proxy​(java.lang.Object object)
        This method is used to allow clients to pass references to its own local objects, to other JVMs. Normally all arguments are passed by value, meaning copies are sent to the remote JVM. Sometimes however, what is needed is for all users to have a reference to the same object instance, on which to perform operations.
        Parameters:
        object - The local client object for which a pass-by-reference is sought
        Returns:
        A proxy object, implementing all of the interfaces of the wrapped object argument, it will even work in the local context
      • register

        public void register​(java.lang.String hostname,
                             int port)
                      throws java.lang.Exception
        This method is used to manually collect remote registry entries. The specific addresses or host names of the remote JVMs must be known. It is used to reach JVMs that for some reason are not accessible by UDP. The method will also share all of its references. Note: you will generally want to export all of your service objects first, before making calls to register.
        Parameters:
        hostname - The address or domain name of a remote grail JVM
        port - The TCP port on which the object is being shared, canonically it 1198
        Throws:
        java.lang.Exception - Various types, related to network related errors: invalid host name, host unavailable, host unreachable, etc...
      • main

        public static void main​(java.lang.String[] args)
                         throws java.lang.Exception
        Technically this method is unrelated to the class, it is used to furnish library version information. It provides an execution point called when the library jar is executed. It simply copies the contents of the internal readme.txt file to the console.
        Throws:
        java.lang.Exception