8020854: change RMI javadocs to specify that remote objects are exported to the wildcard address

Reviewed-by: rgallard, alanb

src/share/classes/java/rmi/server/RMISocketFactory.java

 /*
- * Copyright (c) 1996, 2002, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -33,15 +33,47 @@ import java.net.*;
  * in order to obtain client and server sockets for RMI calls.  An
  * application may use the <code>setSocketFactory</code> method to
  * request that the RMI runtime use its socket factory instance
- * instead of the default implementation.<p>
+ * instead of the default implementation.
  *
- * The default socket factory implementation used goes through a
+ * <p>The default socket factory implementation performs a
  * three-tiered approach to creating client sockets. First, a direct
  * socket connection to the remote VM is attempted.  If that fails
  * (due to a firewall), the runtime uses HTTP with the explicit port
  * number of the server.  If the firewall does not allow this type of
  * communication, then HTTP to a cgi-bin script on the server is used
- * to POST the RMI call.<p>
+ * to POST the RMI call.
+ *
+ * <p>The default socket factory implementation creates server sockets that
+ * are bound to the wildcard address, which accepts requests from all network
+ * interfaces.
+ *
+ * @implNote
+ * <p>You can use the {@code RMISocketFactory} class to create a server socket that
+ * is bound to a specific address, restricting the origin of requests. For example,
+ * the following code implements a socket factory that binds server sockets to the
+ * loopback address. This restricts RMI to processing requests only from the local host.
+ *
+ * <pre>{@code
+ *     class LoopbackSocketFactory extends RMISocketFactory {
+ *         public ServerSocket createServerSocket(int port) throws IOException {
+ *             return new ServerSocket(port, 5, InetAddress.getLoopbackAddress());
+ *         }
+ *
+ *         public Socket createSocket(String host, int port) throws IOException {
+ *             // just call the default client socket factory
+ *             return RMISocketFactory.getDefaultSocketFactory()
+ *                                    .createSocket(host, port);
+ *         }
+ *     }
+ *
+ *     // ...
+ *
+ *     RMISocketFactory.setSocketFactory(new LoopbackSocketFactory());
+ * }</pre>
+ *
+ * Set the {@code java.rmi.server.hostname} system property
+ * to a host name (typically {@code localhost}) that resolves to the loopback
+ * interface to ensure that the generated stubs use the right network interface.
  *
  * @author  Ann Wollrath
  * @author  Peter Jones

src/share/classes/java/rmi/server/UnicastRemoteObject.java

 /*
- * Copyright (c) 1996, 2003, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -100,6 +100,26 @@ import sun.rmi.server.UnicastServerRef2;
  * </ul>
  * </ul>
  *
+ * <p>If an object is exported with the
+ * {@link #exportObject(Remote) exportObject(Remote)}
+ * or
+ * {@link #exportObject(Remote, int) exportObject(Remote, port)}
+ * methods, or if a subclass constructor invokes one of the
+ * {@link #UnicastRemoteObject()}
+ * or
+ * {@link #UnicastRemoteObject(int) UnicastRemoteObject(port)}
+ * constructors, the object is exported with a server socket created using the
+ * {@link RMISocketFactory}
+ * class.
+ *
+ * @implNote
+ * <p>By default, server sockets created by the {@link RMISocketFactory} class
+ * listen on all network interfaces. See the
+ * {@link RMISocketFactory} class and the section
+ * <a href="{@docRoot}/../platform/rmi/spec/rmi-server29.html">RMI Socket Factories</a>
+ * in the
+ * <a href="{@docRoot}/../platform/rmi/spec/rmiTOC.html">Java RMI Specification</a>.
+ *
  * @author  Ann Wollrath
  * @author  Peter Jones
  * @since   JDK1.1