gnu.cajo.utils

Class BaseItem

java.lang.Object

gnu.cajo.utils.BaseItem

public class BaseItem
extends 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

Nested Classes

Modifier and Type	Class and Description
class	BaseItem.MainThread The main processing thread of this object.

Field Summary

Fields

Modifier and Type	Field and Description
protected 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.
Thread	thread A reference to the object's processing thread.

Constructor Summary

Constructors

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

Method Summary

Methods

Modifier and Type	Method and Description
void	contact(String url) This method is canonically called when an object announces its reference via the Multicast class.
String	getDescription() This method is invoked by remote users of this object.
Remote	getItem(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.
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(Object proxy) This remotely invokable method is called by remote clients to install their proxies in this VM.
void	setProxy(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 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 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(Object proxy)
                    throws 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:

ClassNotFoundException - If the item does not accept proxies.

IllegalArgumentException - If the item provided is a remote reference.

Exception - If the proxy rejected the initialization invocation.

setProxy

public void setProxy(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:

IllegalArgumentException - If the method is called more than once, presumably by a remote object.

getProxy

public 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(String url)
               throws RemoteException,
                      NotBoundException,
                      IOException,
                      ClassNotFoundException,
                      InstantiationException,
                      IllegalAccessException,
                      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:

• As a URL; in the format file://path/name.
• As a class file; in the format path/name
• As a serialized object; in the format /path/name

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:

RemoteException - if the remote registry could not be reached, or the remote instance could not be be created.

NotBoundException - if the requested name is not in the registry.

IOException - if the zedmob format is invalid.

ClassNotFoundException - if a proxy was sent to the VM, and proxy hosting was not enabled.

InstantiationException - when the URL specifies a class name which cannot be instantiated at runtime.

IllegalAccessException - when the url specifies a class name and it does not support a no-arg constructor.

MalformedURLException - if the URL is not in the format explained

getDescription

public 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(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.