This tutorial shows you steps to follow to implement and use custom socket factories with Java Remote Method Invocation (Java RMI). Custom socket factories can be used to control how remote method invocations are communicated at the network level. For example, they can be used to set socket options, control address binding, control connection establishment (such as to require authentication), and to control data encoding (such as to add encryption or compression).
When a remote object is exported, such as with the constructors
or exportObject methods of
java.rmi.server.UnicastRemoteObject or
java.rmi.activation.Activatable, then it is possible
to specify a custom client socket factory (a
java.rmi.server.RMIClientSocketFactory instance) and a
custom server socket factory (a
java.rmi.server.RMIServerSocketFactory instance) to be
used when communicating remote invocations for that remote
object.
A client socket factory controls the creation of sockets used to initiate remote invocations and thus can be used to control how connections are established and the type of socket to use. A server socket factory controls the creation of server sockets used to receive remote invocations and thus can be used to control how incoming connections are listened for and accepted as well as the type of sockets to use for incoming connections.
The remote stub for a remote object contains the client socket factory, if any, that the remote object was exported with, and thus a client socket factory must be serializable, and its code may be downloaded by clients just like the code for stub classes or any other serializable object passed over a remote invocation.
There is also a LocateRegistry.createRegistry
method for exporting a registry with custom socket factories and a
LocateRegistry.getRegistry method for obtaining the
stub for a registry with a custom client socket factory.
(Note that there is also a global socket factory for Java RMI,
which can be set with the setSocketFactory method of
java.rmi.server.RMISocketFactory. This global socket
factory is used for creating sockets when a remote stub does not
contain a custom client socket factory and for creating server
sockets when a remote object was not exported with a custom server
socket factory.)
This tutorial has three parts:
The source code for this tutorial is available in the following formats:
Many users are interested in secure communication between Java RMI clients and servers, such as with mutual authentication and encryption. Custom socket factories provide a hook for doing this. For more information, see Using Java RMI with SSL.ServerSocket and Socket.RMIClientSocketFactory.RMIServerSocketFactory.ServerSocket and
SocketIn this example, the custom socket factory creates sockets that perform simple XOR encryption and decryption. Note that this kind of encryption is easily decrypted by a knowledgeable cryptanalyst and is only used here to keep the example simple.
The custom XOR socket implementation includes the following sources. XOR sockets use special input and output stream implementations to handle XOR-ing the data written to or read from the socket.
RMIClientSocketFactoryXorClientSocketFactory, implements the
java.rmi.server.RMIClientSocketFactory interface. The
client socket factory needs to implement the
createSocket method to return the approriate client
socket instance, an XorSocket.
The client socket factory must implement the
java.io.Serializable interface so that instances can
be serialized to clients as part of remote stubs. It is also
essential to implement the equals and
hashCode methods so that the Java RMI implementation
will correctly share resources among remote stub instances with
equivalent client socket factories.
package examples.rmisocfac;
import java.io.*;
import java.net.*;
import java.rmi.server.*;
public class XorClientSocketFactory
implements RMIClientSocketFactory, Serializable {
private byte pattern;
public XorClientSocketFactory(byte pattern) {
this.pattern = pattern;
}
public Socket createSocket(String host, int port)
throws IOException
{
return new XorSocket(host, port, pattern);
}
public int hashCode() {
return (int) pattern;
}
public boolean equals(Object obj) {
return (getClass() == obj.getClass() &&
pattern == ((XorClientSocketFactory) obj).pattern);
}
}
RMIServerSocketFactoryXorServerSocketFactory, implements the
java.rmi.server.RMIServerSocketFactory interface. The
server socket factory needs to implement the
createServerSocket method to return the appropriate
server socket instance, an XorServerSocket.
The server socket factory does not need to implement the
Serializable interface because server socket factory
instances are not contained in remote stubs. It is still essential
for the server socket factory to implement the equals
and hashcode methods so that the Java RMI
implementation will correctly share resources among remote objects
exported with equivalent socket factories.
package examples.rmisocfac;
import java.io.*;
import java.net.*;
import java.rmi.server.*;
public class XorServerSocketFactory
implements RMIServerSocketFactory {
private byte pattern;
public XorServerSocketFactory(byte pattern) {
this.pattern = pattern;
}
public ServerSocket createServerSocket(int port)
throws IOException
{
return new XorServerSocket(port, pattern);
}
public int hashCode() {
return (int) pattern;
}
public boolean equals(Object obj) {
return (getClass() == obj.getClass() &&
pattern == ((XorServerSocketFactory) obj).pattern);
}
}
RMIClientSocketFactory
and RMIServerSocketFactory implementations. Store a
reference to the remote object's stub in a Java RMI registry so
that clients can look it up.RMIServerSocketFactory to create a server socket to
accept incoming calls to the remote object, and it will create a
stub that contains the corresponding custom
RMIClientSocketFactory. That client socket factory
will be used to create connections when remote invocations are made
to the remote object using the stub.
This example is similar to the example in the tutorial Getting Started Using Java RMI, but it uses custom socket factories instead of the default sockets used by the Java RMI implementation.
The application uses the following Hello remote
interface:
package examples.rmisocfac;
public interface Hello extends java.rmi.Remote {
String sayHello() throws java.rmi.RemoteException;
}
The server application creates a remote object implementing the
Hello remote interface and exports the object to use
custom socket factories using the
java.rmi.server.UnicastRemoteObject.exportObject
method that takes the custom socket factories as arguments. Next,
it creates a local registry and, in that registry, it binds a
reference to the remote object's stub with the name "Hello".
package examples.rmisocfac;
import java.io.*;
import java.rmi.*;
import java.rmi.server.*;
import java.rmi.registry.*;
public class HelloImpl implements Hello {
public HelloImpl() {}
public String sayHello() {
return "Hello World!";
}
public static void main(String args[]) {
if (System.getSecurityManager() == null) {
System.setSecurityManager(new SecurityManager());
}
byte pattern = (byte) 0xAC;
try {
/*
* Create remote object and export it to use
* custom socket factories.
*/
HelloImpl obj = new HelloImpl();
RMIClientSocketFactory csf = new XorClientSocketFactory(pattern);
RMIServerSocketFactory ssf = new XorServerSocketFactory(pattern);
Hello stub =
(Hello) UnicastRemoteObject.exportObject(obj, 0, csf, ssf);
/*
* Create a registry and bind stub in registry.
*
LocateRegistry.createRegistry(2002);
Registry registry = LocateRegistry.getRegistry(2002);
registry.rebind("Hello", stub);
System.out.println("HelloImpl bound in registry");
} catch (Exception e) {
System.out.println("HelloImpl exception: " + e.getMessage());
e.printStackTrace();
}
}
}
The client application obtains a reference to the registry used
by the server application. It then looks up the remote object's
stub and invokes its remote method sayHello:
package examples.rmisocfac;
import java.rmi.*;
import java.rmi.registry.*;
public class HelloClient {
public static void main(String args[]) {
if (System.getSecurityManager() == null) {
System.setSecurityManager(new SecurityManager());
}
try {
Registry registry = LocateRegistry.getRegistry(2002);
Hello obj = (Hello) registry.lookup("Hello");
String message = obj.sayHello();
System.out.println(message);
} catch (Exception e) {
System.out.println("HelloClient exception: " +
e.getMessage());
e.printStackTrace();
}
}
}
There are four steps to compile and run the application:
Step 1:
Compile the remote interface, client, and server classes
javac -d . XorInputStream.java javac -d . XorOutputStream.java javac -d . XorSocket.java javac -d . XorServerSocket.java javac -d . XorServerSocketFactory.java javac -d . XorClientSocketFactory.java javac -d . Hello.java javac -d . HelloClient.java javac -d . HelloImpl.java
java -Djava.security.policy=policy examples.rmisocfac.HelloImpl
The server output should look like this:
HelloImpl bound in registry
In another window start the client application making sure that the application classes are in the class path:
java -Djava.security.policy=policy examples.rmisocfac.HelloClient
The client output should look like this:
Hello World!
Note: Both the server and client applications use
a security policy file that grants permissions only to files in the
local class path (the current directory). The server application
needs permission to accept connections, and both the server and
client applications need permission to make connections. The
permission java.net.SocketPermission is granted to the
specified codebase URL, a "file:" URL relative to the current
directory. This permission grants the ability to both accept
connections from and make connections to any host on unprivileged
ports (that is ports >= 1024).
grant codeBase "file:." {
permission java.net.SocketPermission "*:1024-", "connect,accept";
};
Note that if you want to customize the communication to the
registry as well, such as to secure registry communication, then
that can be done by passing the appropriate custom socket factories
to the LocateRegistry.createRegistry and
LocateRegistry.getRegstry invocations.
