mscharhag, Programming and Stuff;

A blog about programming and software development topics, mostly focused on Java technologies including Java EE, Spring and Grails.

Tuesday, 22 October, 2013

Two things to remember when using Java RMI

This is a short blog post about two common pitfalls you should be aware of when using Java RMI.

Setting java.rmi.server.hostname

If you are getting strange Connection refused to host: <ip> error messages on the RMI client and you are sure the connection should work (you double checked all the standard things like network configuration etc.) the RMI system property java.rmi.server.hostname is something to look at.

To call a method on a remote object the RMI client has first to retrieve a remote stub object from the RMI registry. This stub object contains the server address that is later used to connect to the remote object when a remote method should be called (the connection to the RMI registry and the connection to the remote object are two completely different things). By default the server will try to detect his own address and pass it to the stub object. Unfortunatelly the algorithm that is used to detect the server address doesn't always produce a useful result (depending on the network configuration).

It is possible to override the server address that is passed to the stub object, by setting the system property java.rmi.server.hostname on the RMI server.

This can either be done in Java code

  System.setProperty("java.rmi.server.hostname", "<<rmi server ip>>");

or by adding a Java command line parameter:

  -Djava.rmi.server.hostname=<<rmi server ip>>

Setting RMI service ports

If you have trouble making RMI calls through a firewall you should make sure you set specific ports for remote objects. By default port 1099 used by the RMI registry so make sure you opened this port in the firewall. However, this port is only used by the client to connect to the RMI registry and not for the communication between the stub and the remote object. For the later one random ports are used by default. Since you don't want to open all ports in your firewall you should set a specific port for RMI remote objects.

This can be done by overriding the createServerSocket() method of RMISocketFactory:

public class MyRMISocketFactory extends RMISocketFactory {
  private static final int PREFERED_PORT = 1234;
  public ServerSocket createServerSocket(int port) throws IOException {
    if (port == 0) {
      return new ServerSocket(PREFERED_PORT);
    return super.createServerSocket(port);

By default createServerSocket() chooses a free random port if 0 is passed as parameter. In this modified version of createServerSocket() a specific port (1234) is returned when 0 is passed as parameter.

If you are using Spring's RmiServiceExporter you can use the setServicePort() method to export services on a specific port:

<bean class="org.springframework.remoting.rmi.RmiServiceExporter">
  <property name="servicePort" value="1234"/>

Note that multiple remote objects/services can share the same port. After you set a specific port, you just have to open this port in your firewall.


  • Ray - Thursday, 21 January, 2016

    When you say "multiple remote objects/services can share the same port" does that mean an instance can be both a client and server and operate over the same service port?

  • vikram - Monday, 5 December, 2016

    I have been looking for this information, Thanks.

  • EJP - Monday, 13 February, 2017

    You don't need to write an `RMIServerSocketFactory` just to get a fixed port number. Alll you have to do is provide it when exporting the remote objects. Ports can be shared under several conditions, not unconditionally.

  • Simon - Tuesday, 23 January, 2018

    Very helpful thanks :)

Leave a reply