Class Wrapper

java.lang.Object
gnu.cajo.utils.extra.Wrapper
All Implemented Interfaces:
Invoke, Serializable, Remote

public class Wrapper extends Object implements Invoke
The base class for wrapping objects, remote references, and proxies for syntactical transparency with the remaining codebase. It allows the object type to change between local object/remote/proxy, without affecting the calling code. It enforces compile time type checking, and the standard invocation systax, while still allowing invocation of methods via the reflection based invoke paradigm. It also promotes "lazy instantiation," as the wrapped reference will not be loaded into the runtime unless and until it is needed. If the wrapped object url is compatible, the wrapper may be freely passed between JVM instances.
Version:
1.0, 27-Apr-04 Initial release
See Also:
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected Object
    The object being wrapped by the reflection based invocation paradigm.
    private static final long
     
    protected String
    The URL where to get the wrapped object: file://, http://, ftp://, /path/name, path/name, or //[host][:port]/[name].
  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    The no-arg constructor does nothing, it is protected for use only by subclasses.
     
    The constructor loads an object, or a zipped marshalled object (zedmob) from a URL, a file, or from a remote rmiregistry.
  • Method Summary

    Modifier and Type
    Method
    Description
    This method attempts to extract usage information about the inner object, if the method is supported.
    invoke(String method, Object args)
    This method must be called by all interface methods of the subclass, as it will load the wrapped object if it has not yet been loaded.
    boolean
    This method is used to test if the inner object is a reference to a remote object.
    protected void
    This method is used to support lazy loading of remote object references, only when needed.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      See Also:
    • object

      protected transient Object object
      The object being wrapped by the reflection based invocation paradigm. It may be a reference to a remote object, or a proxy sent by a remote object, or even an ordinary local object. It is not declared final, as to allow its representation to change, as required for performance or other application specific reasons, for example to be further wrapped by a MonitorItem. It is transient to force subclasses to manage application specific persistence.
    • url

      protected String url
      The URL where to get the wrapped 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 ///.
  • Constructor Details

    • Wrapper

      protected Wrapper()
      The no-arg constructor does nothing, it is protected for use only by subclasses.
    • Wrapper

      public Wrapper(String url)
      The constructor loads an object, or a zipped marshalled object (zedmob) from a URL, a file, or from a remote rmiregistry. If the object is in a local file, it can be either inside the application's jar file, or on its local file system.

      Loading an item 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 item; in the format /path/name

      File loading will first be attempted from within the application's jar file, if that fails, it will then look in the local filesystem. Note: any socket connections made by the incoming item cannot be known at compile time, therefore proper operation if this VM is behind a firewall could be blocked. Use behind a firewall would require knowing all the ports that would be needed in advance, and enabling them before loading the item. Note: for efficiency, the item will not be loaded at this time, rather on the first time it is need to perform in a particular method.

      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 ///.
  • Method Details

    • load

      protected void load()
      This method is used to support lazy loading of remote object references, only when needed. It also absorbs the checked RemoteException, which will cause an unchecked NullPointerException, for the calling method's subsequent operation on the wrapped object.
    • isRemote

      public boolean isRemote()
      This method is used to test if the inner object is a reference to a remote object. This can be important to know as remote invocations are not time deterministic, and not assured of execution, as with local objects. If the wrapped object has not yet been loaded, this will cause it to happen, which could result in a NullPointerException on a load failure.
      Returns:
      True if the inner object is remote, false otherwise.
    • getDescription

      public String getDescription() throws Exception
      This method attempts to extract usage information about the inner object, if the method is supported.
      Returns:
      A detailed guide to object usage, preferably with examples, with HTML markup permitted.
      Throws:
      NoSuchMethodException - If the inner object does not support the description method.
      Exception - If the innter object rejected the invocation, for any application specific reasons.
    • invoke

      public Object invoke(String method, Object args) throws Exception
      This method must be called by all interface methods of the subclass, as it will load the wrapped object if it has not yet been loaded.
      Specified by:
      invoke in interface Invoke
      Parameters:
      method - The method name to be invoked.
      args - The arguments to provide to the method for its invocation, possibly null.
      Returns:
      The resulting data, from the invocation, possibly null.