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.

Author:

John Catherino

Method Summary

Methods

Modifier and Type	Method and Description
void	export(Object object) This method makes an object's public methods, whether instance or static, remotely invocable.
Object[]	lookup(Class methodSetInterface) This method finds all remotely invocable objects, supporting the specified method set.
Object	proxy(Object reference, Class methodSetInterface) This method instantiates a Dynamic Proxy at the client, which implements the method set specified.

Method Detail

export

void export(Object object)
            throws 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:

Exception - For any network or framework specific reasons

lookup

Object[] lookup(Class methodSetInterface)
                throws 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:

Exception - For any network or framework specific reasons
java.lang.IllegalArgumentException - when the provided class is not a Java interface

proxy

Object proxy(Object reference,
           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