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
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    class 
    The main processing thread of this object.
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    A reference to the proxy served by this object, if it has one.
    A reference to the object's processing code.
    A reference to the object's processing thread.
  • Constructor Summary

    Constructors
    Constructor
    Description
    The constructor does nothing, server item configuration is to be done by application specific subclasses.
  • Method Summary

    Modifier and Type
    Method
    Description
    void
    This method is canonically called when an object announces its reference via the Multicast class.
    This method is invoked by remote users of this object.
    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.
    This remotely invokable method is called by the remote clients, to request the server object's default proxy, if it supports one.
    This remotely invokable method is called by remote clients to install their proxies in this VM.
    void
    This method is called by the ItemServer during a bind operation to set the proxy member.
    void
    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 Details

    • 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 Details

    • BaseItem

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

    • 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

      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.