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

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

      Fields 
      Modifier and Type Field Description
      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

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

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      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:

        • 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:
        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.