gnu.cajo
Class Cajo

java.lang.Object
  extended by gnu.cajo.Cajo
All Implemented Interfaces:
Grail

public final class Cajo
extends java.lang.Object
implements Grail

This class implements the Generic Standard Interface using the cajo library. It is designed to work with all JRE's: 1.3 and higher.

Version:
1.0, 21-Aug-07
Author:
John Catherino

Constructor Summary
Cajo()
          The defaule constructor announces the cajo object on the cajo IANA standard address and port, with a default ttl value of 16.
Cajo(int ttl)
          This constructor announces the cajo object on the cajo IANA standard address and port using a specific ttl value.
 
Method Summary
 void export(java.lang.Object object)
          This method makes any object's public methods, whether instance or static, remotely invocable.
 void export(java.lang.Object object, java.lang.Object target)
          This method makes any 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.
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, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Cajo

public Cajo()
     throws java.io.IOException
The defaule constructor announces the cajo object on the cajo IANA standard address and port, with a default ttl value of 16.
Note: invoke gnu.cajo.invoke.Remote.config, and construct a gnu.cajo.utils.CodebaseServer if needed, to configure the JVM before invoking this constructor.

Throws:
java.io.IOException - If the startup announcement datagram packet could not be sent

Cajo

public Cajo(int ttl)
     throws java.io.IOException
This constructor announces the cajo object on the cajo IANA standard address and port using a specific ttl value.
Note: invoke gnu.cajo.invoke.Remote.config, and construct a gnu.cajo.utils.CodebaseServer if needed, to configure the JVM before invoking this constructor.

Parameters:
ttl - The time for interface export announcements to live, it is decremented each time it is passed to a new router, a value of 0 confines the announcement to the local subnet, the max value of 255 could theoretically traverse the entire internet (assuming no routers blocked datagram packets)
Throws:
java.io.IOException - If the startup announcement datagram packet could not be sent
Method Detail

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.io.IOException - If the announcement datagram packet could not be sent

export

public void export(java.lang.Object object,
                   java.lang.Object target)
            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.

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
target - The object on which to invoke methods, this is used when object parameter is wrapped e.g. in a MonitorItem or AuditorItem
Throws:
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)
                              throws java.rmi.RemoteException
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 (if the reference has not been already remoted, it will be)
Returns:
A dynamic proxy object, implementing all of the interfaces of the wrapped object argument, it will even work in the local context
Throws:
java.rmi.RemoteException - If the remoting of the object, when necessary, fails, typically due to network configuration issues

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.io.IOException
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.io.IOException - If the readme.txt file cannot be found