| CONTENTS | PREV | NEXT | Java Remote Method Invocation |
When the RMI runtime implementation needs instances ofjava.net.Socketandjava.net.ServerSocketfor its connections, instead of instantiating objects of those classes directly, it calls thecreateSocketandcreateServerSocketmethods on the currentRMISocketFactoryobject, returned by the static methodRMISocketFactory.getSocketFactory. This allows the application to have a hook to customize the type of sockets used by the RMI transport, such as alternate subclasses of thejava.net.Socketandjava.net.ServerSocketclasses. The instance ofRMISocketFactoryto be used can be set once by trusted system code. In JDK1.1, this customization was limited to relatively global decisions about socket type, because the only parameters supplied to the factory's methods werehostandport(forcreateSocket) and justport(forcreateServerSocket).In the Java SE platform, the new interfaces
RMIServerSocketFactoryandRMIClientSocketFactoryhave been introduced to provide more flexible customization of what protocols are used to communicate with remote objects.To allow applications using RMI to take advantage of these new socket factory interfaces, several new constructors and
exportObjectmethods, that take the client and server socket factory as additional parameters, have been added to bothUnicastRemoteObjectandjava.rmi.activation.Activatable.Remote objects exported with either of the new constructors or
exportObjectmethods (withRMIClientSocketFactoryandRMIServerSocketFactoryparameters) will be treated differently by the RMI runtime. For the lifetime of such a remote object, the runtime will use the customRMIServerSocketFactoryto create aServerSocketto accept incoming calls to the remote object and use the customRMIClientSocketFactoryto create aSocketto connect clients to the remote object.The implementation of
RemoteRefandServerRefused in the stubs and skeletons for remote objects exported with custom socket factories isUnicastRef2andUnicastServerRef2, respectively. The wire representation of theUnicastRef2type contains a different representation of the "endpoint" to contact than theUnicastReftype has (which used just a host name string in UTF format, following by an integer port number). ForUnicastRef2, the endpoint's wire representation consists of a format byte specifying the contents of the rest of the endpoint's representation (to allow for future expansion of the endpoint representation) followed by data in the indicated format. Currently, the data may consist of a hostname in UTF format, a port number, and optionally (as specified by the endpoint format byte) the serialized representation of anRMIClientSocketFactoryobject that is used by clients to generate socket connections to remote object at this endpoint. The endpoint representation does not contain theRMIServerSocketFactoryobject that was specified when the remote object was exported.When calls are made through references of the
UnicastRef2type, the runtime uses thecreateSocketmethod of theRMIClientSocketFactoryobject in the endpoint when creating sockets for connections to the referent remote object. Also, when the runtime makes DGC "dirty" and "clean" calls for a particular remote object, it must call the DGC on the remote JVM using a connection generated from the sameRMIClientSocketFactoryobject as specified in the remote reference, and the DGC implementation on the server side should verify that this was done correctly.Remote objects exported with the older constructor or method on
UnicastRemoteObjectthat do not take custom socket factories as arguments will haveRemoteRefandServerRefof typeUnicastRefandUnicastServerRefas before and use the old wire representation for their endpoints, i.e. a host string in UTF format followed by an integer specifying the port number. This is so that RMI servers that do not use new 1.2 features will interoperate with older RMI clients.
RMISocketFactory Class
Thejava.rmi.server.RMISocketFactoryabstract class provides an interface for specifying how the transport should obtain sockets. Note that the class below usesSocketandServerSocketfrom thejava.netpackage.
package java.rmi.server;
public abstract class RMISocketFactory
implements RMIClientSocketFactory, RMIServerSocketFactory
{
public abstract Socket createSocket(String host, int port)
throws IOException;
public abstract ServerSocket createServerSocket(int port)
throws IOException;
public static void setSocketFactory(RMISocketFactory fac)
throws IOException {...}
public static RMISocketFactory getSocketFactory() {...}
public static void setFailureHandler(RMIFailureHandler fh) {...}
public static RMIFailureHandler getFailureHandler() {...}
}
The static methodsetSocketFactoryis used to set the socket factory from which RMI obtains sockets. The application may invoke this method with its ownRMISocketFactoryinstance only once. An application-defined implementation ofRMISocketFactorycould, for example, do preliminary filtering on the requested connection and throw exceptions, or return its own extension of thejava.net.Socketorjava.net.ServerSocketclasses, such as ones that provide a secure communication channel. Note that theRMISocketFactorymay only be set if the current security manager allows setting a socket factory; if setting the socket factory is disallowed, aSecurityExceptionwill be thrown.The static method
getSocketFactoryreturns the socket factory used by RMI. The method returnsnullif the socket factory is not set.The transport layer invokes the
createSocketandcreateServerSocketmethods on theRMISocketFactoryreturned by thegetSocketFactorymethod when the transport needs to create sockets. For example:
RMISocketFactory.getSocketFactory().createSocket(myhost, myport)
The methodcreateSocketshould create a client socket connected to the specified host and port. The methodcreateServerSocketshould create a server socket on the specified port.The default transport's implementation of
RMISocketFactoryprovides for transparent RMI through firewalls using HTTP as follows:
- On
createSocket, the factory automatically attempts HTTP connections to hosts that cannot be contacted with a direct socket.- On
createServerSocket, the factory returns a server socket that automatically detects if a newly accepted connection is an HTTP POST request. If so, it returns a socket that will transparently expose only the body of the request to the transport and format its output as an HTTP response.
The methodsetFailureHandlersets the failure handler to be called by the RMI runtime if the creation of a server socket fails. The failure handler returns a boolean to indicate if retry should occur. The default failure handler returnsfalse, meaning that by default recreation of sockets is not attempted by the runtime.The method
getFailureHandlerreturns the current handler for socket creation failure, ornullif the failure handler is not set.
RMIServerSocketFactory Interface
See theRMIServerSocketFactoryAPI documentation.
RMIClientSocketFactory Interface
See theRMIClientSocketFactoryAPI documentation.