gnu.cajo.utils
Class BaseProxy

java.lang.Object
  extended by gnu.cajo.utils.BaseProxy
All Implemented Interfaces:
java.io.Serializable

public abstract class BaseProxy
extends java.lang.Object
implements java.io.Serializable

A standard abstract base class for proxy objects. Proxies are remote object interfaces to server objects. They are intended to offload routine processing. They differ from server objects in that they are sent to remote VMs to operate, and are often not even instantiated in the runtime of the server's VM.

Version:
1.0, 01-Nov-99 Initial release
Author:
John Catherino
See Also:
Serialized Form

Nested Class Summary
 class BaseProxy.MainThread
          The main processing thread of this object.
 class BaseProxy.Panel
          A standard base class for graphical proxy objects.
 
Field Summary
 java.lang.String bundle
          The path/filename of the resource bundle in the proxy's codebase jar file.
 java.awt.Container container
          A reference to the proxy's graphical user interface, if any.
protected  RemoteInvoke item
          The reference to the sending server, on which the proxy may asynchronously callback.
protected  Remote remoteThis
          A remote reference to the proxy itself, which it can send to its server, or other remote VMs on which they can asynchronously callback.
protected  BaseProxy.MainThread runnable
          A reference to the proxy's processing code.
 java.lang.String[] strings
          The collection of strings to be displayed at the host VM.
 java.lang.Thread thread
          The processing thread of the proxy object, it will be started automatically upon arrival at the client when the init method is invoked.
 
Constructor Summary
BaseProxy()
          Nothing is performed in the constructor.
 
Method Summary
 void contact(java.lang.String url)
          This method is canonically called when an proxy 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.awt.Container init(Remote remoteRef)
          This function is called by the hosting client on upon the proxy's arrival.
 void setItem(RemoteInvoke item)
          This function is called by the ItemServer during its bind operation.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

remoteThis

protected transient Remote remoteThis
A remote reference to the proxy itself, which it can send to its server, or other remote VMs on which they can asynchronously callback.


item

protected RemoteInvoke item
The reference to the sending server, on which the proxy may asynchronously callback. It is set by the ItemServer during the bind operation.


runnable

protected BaseProxy.MainThread runnable
A reference to the proxy's processing code. If non-null, it will be started automatically upon arrival at the host. Its thread can be accessed through the thread member.


thread

public transient java.lang.Thread thread
The processing thread of the proxy object, it will be started automatically upon arrival at the client when the init method is invoked.


container

public java.awt.Container container
A reference to the proxy's graphical user interface, if any. It will be returned to the client as a result of its initialization invocation.


bundle

public java.lang.String bundle
The path/filename of the resource bundle in the proxy's codebase jar file. It will be used to localize any displayed strings, to the language of the proxy recipient, as close as possible, if supplied. It is declared public since its value is typically assigned by a builder application.


strings

public java.lang.String[] strings
The collection of strings to be displayed at the host VM. On instantiation at the host, the array will be loaded with localized strings from the most appropriate resource bundle for the locale of the receiving VM, if provided. It is public since its value is typically assigned by a builder program.

Constructor Detail

BaseProxy

public BaseProxy()
Nothing is performed in the constructor. Construction and configuration of the proxy are generally performed by a builder application.

Method Detail

setItem

public void setItem(RemoteInvoke item)
This function is called by the ItemServer during its bind operation.

Parameters:
item - A remote reference to the server object, on which the proxy may asynchronously call back to it.

init

public java.awt.Container init(Remote remoteRef)
This function is called by the hosting client on upon the proxy's arrival. The client will provide a reference to the proxy, remoted in the context of the client's VM. This value will be saved in the remoteThis member, and can be provided to other remote objects, on which they can contact the proxy. If the proxy has a string bundle, the localized strings most closely matching the locale of the receiving host will be loaded. If the proxy is graphical in nature, i.e. provides a graphical user interface, this method will return it to the host, so that it may display it, if it wishes.

Parameters:
remoteRef - A reference to the proxy, remoted in the context of the client's VM.
Returns:
The proxy's graphical user interface, if it has one, otherwise null.

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 proxy 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.