com.rmiproxy
Class ProxyNaming

java.lang.Object
  |
  +--com.rmiproxy.ProxyNaming

public final class ProxyNaming

extends java.lang.Object

The main access point to the RMI application firewall. ProxyNaming is the only interface clients and servers need to use.

For RMI servers, the RMI Proxy provides:

• the ability to place RMI servers behind firewalls
• access control to the remote service, by
  • hostname/IP address
  • bound-name
  • remote interfaces and methods

For RMI clients, the RMI Proxy supercedes the inferior HTTP tunnelling technique, providing:

• the same ability to place clients behind firewalls
• much improved performance and reliability over HTTP tunnelling
• the ability to access RMI servers behind different firewalls
• access control to the remote service, by
  • hostname/IP address
  • bound-name
  • remote interfaces and methods

The API implemented by ProxyNaming is identical to that of java.rmi.Naming.

When an RMI server behind a firewall is bound to a registry, ProxyNaming.bind or rebind should be used instead of java.rmi.Naming.bind or rebind. This propagates the binding to the server JVM's RMI Proxy Registry. This proxy in turn may have another, more outer, proxy, specified by the value of its rmi.proxyHost property; if so, the propagation continues all the way to the outermost one at the final firewall (i.e. the one which has no further proxy). As a result, the server binding is now visible at the outermost RMI Proxy (usually, to the Internet), and can be accessed by clients, subject to the access control policies of the RMI Proxies. The bind/rebind action itself is also subject to the access control policy of each proxy, so as to control the security of binding to remote registries - this is not supported by java.rmi.Naming.

When an RMI client behind a firewall looks up an RMI registry URL, it should use ProxyNaming.lookup instead of java.rmi.Naming.lookup. This action delegates the lookup via all the client-side proxies, specified by the value of their rmi.proxyHost property, to the proxy at the final firewall (i.e. the one which has no further proxy - usually, the one at the junction with the Internet). Network administrators willing, this proxy is able to 'see' the server's outermost proxy through both the remaining firewalls, and so a binding for the name can be found.

The rmi.proxyHost property is an RMI URL which names the RMI Proxy host and port for the current JVM (similar to http.proxyHost and http.proxyPort). It is always the RMI Proxy which is closer to the Internet than this host.

The rmi.nonProxyHosts property is a list of hostnames that ProxyNaming should contact directly, not via the proxy. If the host being contacted appears in rmi.nonProxyHosts, or if no value for rmi.proxyHost is set, ProxyNaming behaves identically to java.rmi.Naming.

Notes:

• The RMI URL to be looked up by an RMI client must contain the hostname/port number of the outermost server-side RMI proxy, not the hostname/port number of the server itself.
• If the server is not behind a firewall, it need not use ProxyNaming, regardless of where the client is.
• If the client is not behind a firewall, it need not use ProxyNaming, regardless of where the server is.
• Any client of an RMI server, whether accessed directly or via an RMI Proxy, must be prepared to deal with a NoSuchObjectException arising out of a premature unexport due to a false DGC report. This is not a new issue in RMI design: it can occur whenever "network partitions exist between client and server" (RMI Specification, §3), because these make DGC unreliable. It is likely to occur in configurations involving RMI Proxies because such configurations almost always contain network partitions.
• For security and administrative reasons, the RMI Proxy runs on a single TCP/IP port, the standard RMI Registry port (1099). This port must be opened by the firewall administrator for access by the RMI Proxy.

Method Summary

static void	bind(java.lang.String name, java.rmi.Remote object) Binds a name to a remote object.
static java.lang.String[]	list(java.lang.String name) Lists the contents of a remote registry.
static java.rmi.Remote	lookup(java.lang.String name) Looks up a remote item in a registry.
static void	rebind(java.lang.String name, java.rmi.Remote object) Rebinds a name to a new remote object, overriding any existing binding.
static void	unbind(java.lang.String name) Unbinds a name from any association with a remote object.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

list

public static java.lang.String[] list(java.lang.String name)
                               throws java.rmi.RemoteException,
                                      java.rmi.AccessException,
                                      java.net.MalformedURLException

Lists the contents of a remote registry.

Parameters:

name - RMI URL of the registry: rmi://host[:port]. Note that if the server is behind a firewall, the client must provide the hostname/port number of the outermost server-side RMI proxy, not the hostname/port number of the server itself.

Returns:

An array (possibly 0 elements) of URL-formatted names bound in the registry.

Throws:

java.rmi.RemoteException - remote error

java.rmi.AccessException - permission denied by RMI or firewall

java.net.MalformedURLException - bad registry URL

lookup

public static java.rmi.Remote lookup(java.lang.String name)
                              throws java.rmi.RemoteException,
                                     java.rmi.AccessException,
                                     java.rmi.NotBoundException,
                                     java.net.MalformedURLException

Looks up a remote item in a registry.

Parameters:

name - RMI URL of the item: rmi://host[:port]/item. Note that if the server is behind a firewall, the client must provide the hostname/port number of the outermost server-side RMI proxy, not the hostname/port number of the server itself.

Returns:

A stub to the remote object bound to name

Throws:

java.rmi.RemoteException - remote error

java.rmi.AccessException - permission denied by RMI or firewall

java.rmi.NotBoundException - name not bound

java.net.MalformedURLException - bad item URL

bind

public static void bind(java.lang.String name,
                        java.rmi.Remote object)
                 throws java.rmi.RemoteException,
                        java.rmi.AccessException,
                        java.rmi.AlreadyBoundException,
                        java.net.MalformedURLException

Binds a name to a remote object.

Parameters:

name - RMI URL of the item: rmi://host[:port]/item

object - reference to the remote object to bind

Throws:

java.rmi.RemoteException - remote error

java.rmi.AccessException - permission denied by RMI or firewall

java.rmi.AlreadyBoundException - name already bound

java.net.MalformedURLException - bad item URL

rebind

public static void rebind(java.lang.String name,
                          java.rmi.Remote object)
                   throws java.rmi.RemoteException,
                          java.rmi.AccessException,
                          java.net.MalformedURLException

Rebinds a name to a new remote object, overriding any existing binding.

Parameters:

name - RMI URL of the item: rmi://host[:port]/item

object - reference to the remote object to bind

Throws:

java.rmi.RemoteException - remote error

java.rmi.AccessException - permission denied by RMI or firewall

java.net.MalformedURLException - bad item URL

unbind

public static void unbind(java.lang.String name)
                   throws java.rmi.RemoteException,
                          java.rmi.AccessException,
                          java.rmi.NotBoundException,
                          java.net.MalformedURLException

Unbinds a name from any association with a remote object.

Parameters:

name - RMI URL of the item: rmi://host[:port]/item

Throws:

java.rmi.RemoteException - remote error

java.rmi.AccessException - permission denied by RMI or firewall

java.rmi.NotBoundException - name not bound

java.net.MalformedURLException - bad item URL