CONTENTS | PREV | NEXT | Java Remote Method Invocation |
The SocketType class represents a socket protocol type that denotes the protocol type and, consequently, the RMISocketFactory to be used for communicating with a remote object.package java.rmi.server;
public final class SocketType implements java.io.Serializable {
public SocketType(String protocol,
byte[] refData,
Object serverData)
throws java.rmi.RemoteException;
public String getProtocol();
public byte[] getRefData();
public Object getServerData();
public void write(java.io.DataOutput out)
throws java.io.IOException;
public static SocketType read(java.io.DataInput in)
throws java.io.IOException;
public int hashCode();
public boolean equals(Object obj);
}
When the RMI runtime implementation needs instances of java.net.Socket and java.net.ServerSocket for its connections, instead of instantiating objects of those classes directly, it calls thecreateSocket
andcreateServerSocket
methods on the current RMISocketFactory object, 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 the java.net.Socket and java.net.ServerSocket classes. The instance of RMISocketFactory to be used can be set once by trusted system code. In JDK 1.1, this customization was limited to relatively global decisions about socket type, because the only parameters supplied to the factory's methods were host and port (forcreateSocket
) and just port number (forcreateServerSocket
).In JDK 1.2, the new class SocketType has been introduced to provide more flexible customization of what protocols are used to communicate with remote objects. SocketType objects provide additional information to an RMISocketFactory instance to indicate what kind of sockets need to be created. The previously defined
createSocket
andcreateServerSocket
methods that do not take a SocketType object still behave as they did in JDK 1.1. SocketType objects are intended to describe a set of requirements for the socket instance to be returned in an implementation independent manner (for example, class names are not used to allow for different implementations of the same desired socket type). If the RMISocketFactory instance does not understand the requirements specified in a SocketType object, it must throw a java.io.IOException from thecreateSocket
orcreateServerSocket
method. The default implementation of these methods that take SocketType objects is to just throw an IOException.To allow applications using RMI to take advantage of this new interface between the RMI runtime and the current RMISocketFactory, the following new constructor and new
exportObject
method that take an additional parameter, a SocketType have been added to UnicastRemoteObject.Remote objects exported with either the constructor or the method that take a SocketType will be treated differently by the RMI runtime. For the lifetime of such a remote object, the runtime will bind a server socket to the specified port (or an arbitrary one, if it was specified to be zero) of the specified type, and RMI calls to that object will only be allowed to execute if they came over connections to that port. Such a server socket may be used to accept calls for multiple (different) remote objects if they were exported with the same SocketType and port number. The runtime will use the instance of java.net.ServerSocket returned by the current RMISocketFactory object's
createServerSocket
method with the specified port and socket type provided. If a call arrives over a different ServerSocket for a remote object but with an ObjID that does exist in the runtime, a NoSuchObjectException will be thrown.The implementation of RemoteRef and ServerRef used in the stubs and skeletons for remote objects exported with a SocketType is UnicastRef2 and UnicastServerRef2, respectively. The wire representation of the UnicastRef2 type contains a different representation of the "endpoint" to contact than the UnicastRef type has (which used just a host name string in UTF format, following by an integer port number). For UnicastRef2, 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 the indicated data. Currently, the data may consist of a hostname in UTF format, a port number, and optionally (as specified by the endpoint format byte) the wire representation of a SocketType object that specifies what kind of client socket object must be used to contact the indicated remote object. The wire representation of the SocketType is currently defined as follows:
A wire representation of the refData array's length as -1 indicates a null refData for that SocketType object. The SocketType's serverData object is not part of the wire representation of the SocketType object; it will be null in client's reference. Therefore, it is only useful for the creation of the server socket in the VM contained the remote implementation.When calls are made through references of the UnicastRef2 type, the runtime must pass the enclosed SocketType object to the current RMISocketFactory object 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 VM using a connection with the same SocketType 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 UnicastRemoteObject that do not take a SocketType will have RemoteRef and ServerRef of type UnicastRef and UnicastServerRef as before and use the old wire representation for their endpoints, i.e. a host string in UTF format followed by integer specifying the port number. This is so that RMI servers that do not use new JDK 1.2 features will interoperate with older RMI clients.
The SocketType constructor creates a socket type with the protocol name, protocol, whose reference data is refData, and whose server data is serverData.The methods
getProtocol
,getRefData
, andgetServerData
return the corresponding values that were passed to the SocketType constructor, except thatgetServerData
may return null if the instance is a copy of a SocketType object made when a remote reference is passed in an RMI call.The
write
method writes out the wire format representation of the SocketType instance to the specified stream out. Thestatic
read
method reads the wire representation of the SocketType from the stream, in, and returns an instance of a SocketType initialized with the information read from the stream; note that the serverData will be null.The
equals
method of SocketType returns true if its argument is also of class SocketType, if the protocol strings of the two objects are equal, and if the refData arrays are either both null or both consist of the exact same sequence of bytes. Note that the serverData of the SocketType does not matter in this test of equality.