gnu.cajo.utils
Class BaseItem

java.lang.Object
  extended by gnu.cajo.utils.BaseItem

public class BaseItem
extends java.lang.Object

An optional base class for server objects. Server objects differ from proxy objects in that they never leave their host VM.

Version:
1.0, 01-Nov-99 Initial release
Author:
John Catherino

Nested Class Summary
 class BaseItem.MainThread
          The main processing thread of this object.
 
Field Summary
protected  java.rmi.MarshalledObject proxy
          A reference to the proxy served by this object, if it has one.
protected  BaseItem.MainThread runnable
          A reference to the object's processing code.
 java.lang.Thread thread
          A reference to the object's processing thread.
 
Constructor Summary
BaseItem()
          The constructor does nothing, server item configuration is to be done by application specific subclasses.
 
Method Summary
 void contact(java.lang.String url)
          This method is canonically called when an object announces its reference via the Multicast class.
 java.lang.String getDescription()
          This method is invoked by remote users of this object.
 Remote getItem(java.lang.String url)
          A method will load either an object, or a zipped marshalled object (zedmob) of an object, from a URL, file, or from a remote rmiregistry.
 java.rmi.MarshalledObject getProxy()
          This remotely invokable method is called by the remote clients, to request the server object's default proxy, if it supports one.
 Remote installProxy(java.lang.Object proxy)
          This remotely invokable method is called by remote clients to install their proxies in this VM.
 void setProxy(java.rmi.MarshalledObject proxy)
          This method is called by the ItemServer during a bind operation to set the proxy member.
 void startThread()
          This method is called by the ItemServer during a bind operation.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

runnable

protected BaseItem.MainThread runnable
A reference to the object's processing code. If non-null, it will be started automatically binding in the rmiregistry. Its thread can be accessed through the thread member.


proxy

protected java.rmi.MarshalledObject proxy
A reference to the proxy served by this object, if it has one. It is assigned by the ItemServer during its bind operation.


thread

public java.lang.Thread thread
A reference to the object's processing thread. It can be used to interrupt the thread, to signal the object to perform an orderly shutdown.

Constructor Detail

BaseItem

public BaseItem()
The constructor does nothing, server item configuration is to be done by application specific subclasses.

Method Detail

installProxy

public Remote installProxy(java.lang.Object proxy)
                    throws java.lang.Exception
This remotely invokable method is called by remote clients to install their proxies in this VM. This invocation will only succeed if the acceptProxies method of the ItemServer has been called. The received proxy's init method will be invoked with a reference to itself, remoted in the context of this VM. This is done to initialise the proxy, and provide it with a handle to pass to other remote objects, on which they can contact this proxy. The remote proxy reference will be returned to the caller, providing an interface on which to asynchronously call its proxy.

Parameters:
proxy - The proxy to run in this VM, it is typically sent as a MarshalledObject, from which it will be extracted automatically.
Returns:
A reference to the proxy remoted within this context.
Throws:
java.lang.ClassNotFoundException - If the item does not accept proxies.
java.lang.IllegalArgumentException - If the item provided is a remote reference.
java.lang.Exception - If the proxy rejected the initialization invocation.

setProxy

public void setProxy(java.rmi.MarshalledObject proxy)
This method is called by the ItemServer during a bind operation to set the proxy member. If the BaseItem does not support a proxy, it can be given one, just once, by a remote item. Conceptually this is very powerful, but must be used carefully.

Parameters:
proxy - The object's proxy object, if it supports one.
Throws:
java.lang.IllegalArgumentException - If the method is called more than once, presumably by a remote object.

getProxy

public java.rmi.MarshalledObject getProxy()
This remotely invokable method is called by the remote clients, to request the server object's default proxy, if it supports one.

Returns:
A the proxy serving this object, otherwise null.

startThread

public void startThread()
This method is called by the ItemServer during a bind operation. If the item has a processing thread, meaning its runnable member is not null, the thread will be started, and its reference stored in the thread member.


getItem

public Remote getItem(java.lang.String url)
               throws java.rmi.RemoteException,
                      java.rmi.NotBoundException,
                      java.io.IOException,
                      java.lang.ClassNotFoundException,
                      java.lang.InstantiationException,
                      java.lang.IllegalAccessException,
                      java.net.MalformedURLException
A method will load either an object, or a zipped marshalled object (zedmob) of an object, from a URL, file, or from a remote rmiregistry. If the object is in a local file, it can be either inside the server's jar file, or on its local file system.

Loading an object from a file can be specified in one of three ways:

Parameters:
url - The URL where to get the object: file://, http://, ftp://, /path/name, path/name, or //[host][:port]/[name]. The host, port, and name, are all optional. If missing the host is presumed local, the port 1099, and the name "main". The referenced resource can be returned as a MarshalledObject, it will be extracted automatically. If the URL is null, it will be assumed to be ///.
Returns:
A remote reference to the object contained in the URL. It may be either local, or remote to this VM.
Throws:
java.rmi.RemoteException - if the remote registry could not be reached, or the remote instance could not be be created.
java.rmi.NotBoundException - if the requested name is not in the registry.
java.io.IOException - if the zedmob format is invalid.
java.lang.ClassNotFoundException - if a proxy was sent to the VM, and proxy hosting was not enabled.
java.lang.InstantiationException - when the URL specifies a class name which cannot be instantiated at runtime.
java.lang.IllegalAccessException - when the url specifies a class name and it does not support a no-arg constructor.
java.net.MalformedURLException - if the URL is not in the format explained

getDescription

public java.lang.String getDescription()
This method is invoked by remote users of this object. It is expected that subclasses will override this method to provide detailed usage information. Use of HTML for particularly long descriptions is permitted. By default this method will return: not defined.

Returns:
A description of the callable methods, their arguments, returns, and functionality.

contact

public void contact(java.lang.String url)
This method is canonically called when an object announces its reference via the Multicast class. It is expected to receive the URLs of objects that heard the announcement, and wish to be contacted.

Parameters:
url - A //host:port/name type URL on which the 'first-contact' object of a remote VM can be reached.