Package gnu.cajo

Interface Grail

  • All Known Implementing Classes:
    Cajo

    public interface Grail
    This class defines a Generic Standard Java Interface for a Distributed Computing Library. It could be implemented by any reasonably sophisticated framework.

    Four fundamental constraints are imposed:

    • The server need only have one open port
    • A client can operate with all of its ports closed
    • Both the server, and the client, can be behind NAT routers
    • Common classes are mutual; i.e. no remote codebase serving is required

    The specific package in which this class resides, and that of its implementing class, can be framework specific.

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void export​(java.lang.Object object)
      This method makes an object's public methods, whether instance or static, remotely invocable.
      java.lang.Object[] lookup​(java.lang.Class methodSetInterface)
      This method finds all remotely invocable objects, supporting the specified method set.
      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.
    • Method Detail

      • export

        void export​(java.lang.Object object)
             throws java.lang.Exception
        This method makes an object's public methods, whether instance or static, remotely invocable. If not all methods are safe to be made remotely invocable, then wrap the object with a special-case decorator. Additionally, the registry hosting this reference must have the ability to dynamically detect, and be detected, by other similar registries; to create an implicit universal: Meta-Registry.

        Note: There is no silly requirement that the object being exported implement a no-arg constructor; any syntactically valid class definition will work.

        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.lang.Exception - For any network or framework specific reasons
      • lookup

        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.

        Four levels of remote object covariance must be supported here:

        • The remote object does not have to implement the method set interface class, rather merely have the matching methods, if not more. The package of the client interface does not matter either. This is technically known as Liskov Substitution, casually refered to as " duck-typing."
        • The remote object return type can be a subclass of the one specified by the client. Also, if the client method specifies void, any return type is acceptable.
        • The remote object can throw exeptions which are subclasses of the ones specified by the client, and need not throw any or all of the exceptions specified.
        • The interface method arguments do not have to match the specified server types exactly, they can be subclasses.

        Notes: If the client interface has superinterfaces, their methods must also be matched similarly. Method arguments, and returns, are alowed to be primitive types as well.

        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

        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. Also, the remote object must do its best to invoke the correct method, when null arguments are provided.
        Parameters:
        reference - A reference to a remote object returned by the lookup method of this interface
        methodSetInterface - The set (or subset) of client methods, static or instance, that the remote object implements
        Returns:
        A object implementing the method set interface provided, the local method invocations will be transparently passed onto the remote