gnu.cajo.Grail Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of ghost4j Show documentation
Java wrapper for Ghostscript API
The newest version!
package gnu.cajo;

/*
 * A Generic Standard Interface for any distributed computing library.
 * Written by John Catherino 17-August-2007
 * This interface is offered into the public domain.
 */

/**
 * 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
 */
public interface Grail {
   /**
    * 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.
    * @param 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
    */
   void export(Object object) 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.
    * @param methodSetInterface The interface of methods that remote objects
    * are required to support
    * @return 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
    */
   Object[] lookup(Class methodSetInterface) throws Exception;
   /**
    * 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.
    * @param reference A reference to a remote object returned by the
    * lookup method of this interface
    * @param methodSetInterface The set (or subset) of client methods,
    * static or instance, that the remote object implements
    * @return A object implementing the method set interface provided, the
    * local method invocations will be transparently passed onto the remote
    */
   Object proxy(Object reference, Class methodSetInterface);
}