8023863: deprecate support for statically-generated stubs from RMI (JRMP)

4449028: exportObject() javadoc should specify behavior for null socket factories
Reviewed-by: dfuchs, darcy

3 files changed, 134 insertions, 53 deletions

diff --git a/src/share/classes/java/rmi/server/RemoteStub.java b/src/share/classes/java/rmi/server/RemoteStub.java
index 988132cacc..36f8eb068e 100644
--- a/src/share/classes/java/rmi/server/RemoteStub.java
+++ b/src/share/classes/java/rmi/server/RemoteStub.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2004, 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
@@ -25,7 +25,8 @@
 package java.rmi.server;
 
 /**
- * The <code>RemoteStub</code> class is the common superclass to client
+ * The {@code RemoteStub} class is the common superclass of
+ * statically generated client
  * stubs and provides the framework to support a wide range of remote
  * reference semantics.  Stub objects are surrogates that support
  * exactly the same set of remote interfaces defined by the actual
@@ -33,21 +34,26 @@ package java.rmi.server;
  *
  * @author  Ann Wollrath
  * @since   JDK1.1
+ *
+ * @deprecated Statically generated stubs are deprecated, since
+ * stubs are generated dynamically. See {@link UnicastRemoteObject}
+ * for information about dynamic stub generation.
  */
+@Deprecated
 abstract public class RemoteStub extends RemoteObject {
 
     /** indicate compatibility with JDK 1.1.x version of class */
     private static final long serialVersionUID = -1585587260594494182L;
 
     /**
-     * Constructs a <code>RemoteStub</code>.
+     * Constructs a {@code RemoteStub}.
      */
     protected RemoteStub() {
         super();
     }
 
     /**
-     * Constructs a <code>RemoteStub</code>, with the specified remote
+     * Constructs a {@code RemoteStub} with the specified remote
      * reference.
      *
      * @param ref the remote reference
@@ -58,14 +64,17 @@ abstract public class RemoteStub extends RemoteObject {
     }
 
     /**
-     * Sets the remote reference inside the remote stub.
+     * Throws {@link UnsupportedOperationException}.
      *
      * @param stub the remote stub
      * @param ref the remote reference
+     * @throws UnsupportedOperationException always
      * @since JDK1.1
-     * @deprecated no replacement.  The <code>setRef</code> method
-     * is not needed since <code>RemoteStub</code>s can be created with
-     * the <code>RemoteStub(RemoteRef)</code> constructor.
+     * @deprecated No replacement.  The {@code setRef} method
+     * was intended for setting the remote reference of a remote
+     * stub. This is unnecessary, since {@code RemoteStub}s can be created
+     * and initialized with a remote reference through use of
+     * the {@link #RemoteStub(RemoteRef)} constructor.
      */
     @Deprecated
     protected static void setRef(RemoteStub stub, RemoteRef ref) {
diff --git a/src/share/classes/java/rmi/server/UnicastRemoteObject.java b/src/share/classes/java/rmi/server/UnicastRemoteObject.java
index 80cab6f9ba..802d7144ec 100644
--- a/src/share/classes/java/rmi/server/UnicastRemoteObject.java
+++ b/src/share/classes/java/rmi/server/UnicastRemoteObject.java
@@ -30,51 +30,88 @@ import sun.rmi.server.UnicastServerRef2;
 
 /**
  * Used for exporting a remote object with JRMP and obtaining a stub
- * that communicates to the remote object.
+ * that communicates to the remote object. Stubs are either generated
+ * at runtime using dynamic proxy objects, or they are generated statically
+ * at build time, typically using the {@code rmic} tool.
  *
- * <p>For the constructors and static <code>exportObject</code> methods
- * below, the stub for a remote object being exported is obtained as
- * follows:
+ * <p><strong>Deprecated: Static Stubs.</strong> <em>Support for statically
+ * generated stubs is deprecated. This includes the API in this class that
+ * requires the use of static stubs, as well as the runtime support for
+ * loading static stubs.  Generating stubs dynamically is preferred, using one
+ * of the five non-deprecated ways of exporting objects as listed below. Do
+ * not run {@code rmic} to generate static stub classes. It is unnecessary, and
+ * it is also deprecated.</em>
  *
- * <ul>
+ * <p>There are six ways to export remote objects:
+ *
+ * <ol>
+ *
+ * <li>Subclassing {@code UnicastRemoteObject} and calling the
+ * {@link #UnicastRemoteObject()} constructor.
+ *
+ * <li>Subclassing {@code UnicastRemoteObject} and calling the
+ * {@link #UnicastRemoteObject(int) UnicastRemoteObject(port)} constructor.
+ *
+ * <li>Subclassing {@code UnicastRemoteObject} and calling the
+ * {@link #UnicastRemoteObject(int, RMIClientSocketFactory, RMIServerSocketFactory)
+ * UnicastRemoteObject(port, csf, ssf)} constructor.
+ *
+ * <li>Calling the
+ * {@link #exportObject(Remote) exportObject(Remote)} method.
+ * <strong>Deprecated.</strong>
+ *
+ * <li>Calling the
+ * {@link #exportObject(Remote, int) exportObject(Remote, port)} method.
+ *
+ * <li>Calling the
+ * {@link #exportObject(Remote, int, RMIClientSocketFactory, RMIServerSocketFactory)
+ * exportObject(Remote, port, csf, ssf)} method.
+ *
+ * </ol>
+ *
+ * <p>The fourth technique, {@link #exportObject(Remote)},
+ * always uses statically generated stubs and is deprecated.
+ *
+ * <p>The other five techniques all use the following approach: if the
+ * {@code java.rmi.server.ignoreStubClasses} property is {@code true}
+ * (case insensitive) or if a static stub cannot be found, stubs are generated
+ * dynamically using {@link java.lang.reflect.Proxy Proxy} objects. Otherwise,
+ * static stubs are used.
+ *
+ * <p>The default value of the
+ * {@code java.rmi.server.ignoreStubClasses} property is {@code false}.
+ *
+ * <p>Statically generated stubs are typically pregenerated from the
+ * remote object's class using the {@code rmic} tool. A static stub is
+ * loaded and an instance of that stub class is constructed as described
+ * below.
  *
- * <li>If the remote object is exported using the {@link
- * #exportObject(Remote) UnicastRemoteObject.exportObject(Remote)} method,
- * a stub class (typically pregenerated from the remote object's class
- * using the <code>rmic</code> tool) is loaded and an instance of that stub
- * class is constructed as follows.
  * <ul>
  *
- * <li>A "root class" is determined as follows:  if the remote object's
+ * <li>A "root class" is determined as follows: if the remote object's
  * class directly implements an interface that extends {@link Remote}, then
  * the remote object's class is the root class; otherwise, the root class is
  * the most derived superclass of the remote object's class that directly
- * implements an interface that extends <code>Remote</code>.
+ * implements an interface that extends {@code Remote}.
  *
  * <li>The name of the stub class to load is determined by concatenating
- * the binary name of the root class with the suffix <code>"_Stub"</code>.
+ * the binary name of the root class with the suffix {@code _Stub}.
  *
  * <li>The stub class is loaded by name using the class loader of the root
- * class.  The stub class must extend {@link RemoteStub} and must have a
- * public constructor that has one parameter, of type {@link RemoteRef}.
+ * class. The stub class must extend {@link RemoteStub} and must have a
+ * public constructor that has one parameter of type {@link RemoteRef}.
  *
  * <li>Finally, an instance of the stub class is constructed with a
  * {@link RemoteRef}.
- * </ul>
  *
- * <li>If the appropriate stub class could not be found, or the stub class
- * could not be loaded, or a problem occurs creating the stub instance, a
+ * <li>If the appropriate stub class could not be found, or if the stub class
+ * could not be loaded, or if a problem occurs creating the stub instance, a
  * {@link StubNotFoundException} is thrown.
  *
- * <li>For all other means of exporting:
- * <ul>
+ * </ul>
  *
- * <li>If the remote object's stub class (as defined above) could not be
- * loaded or the system property
- * <code>java.rmi.server.ignoreStubClasses</code> is set to
- * <code>"true"</code> (case insensitive), a {@link
- * java.lang.reflect.Proxy} instance is constructed with the following
- * properties:
+ * <p>Stubs are dynamically generated by constructing an instance of
+ * a {@link java.lang.reflect.Proxy Proxy} with the following characteristics:
  *
  * <ul>
  *
@@ -90,28 +127,13 @@ import sun.rmi.server.UnicastServerRef2;
  *
  * <li>If the proxy could not be created, a {@link StubNotFoundException}
  * will be thrown.
- * </ul>
- *
- * <li>Otherwise, an instance of the remote object's stub class (as
- * described above) is used as the stub.
  *
  * </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
+ * Depending upon which constructor or static method is used for exporting an
+ * object, {@link RMISocketFactory} may be used for creating sockets.
+ * By default, server sockets created by {@link RMISocketFactory}
  * 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>
@@ -146,6 +168,10 @@ public class UnicastRemoteObject extends RemoteServer {
     /**
      * Creates and exports a new UnicastRemoteObject object using an
      * anonymous port.
+     *
+     * <p>The object is exported with a server socket
+     * created using the {@link RMISocketFactory} class.
+     *
      * @throws RemoteException if failed to export object
      * @since JDK1.1
      */
@@ -157,6 +183,10 @@ public class UnicastRemoteObject extends RemoteServer {
     /**
      * Creates and exports a new UnicastRemoteObject object using the
      * particular supplied port.
+     *
+     * <p>The object is exported with a server socket
+     * created using the {@link RMISocketFactory} class.
+     *
      * @param port the port number on which the remote object receives calls
      * (if <code>port</code> is zero, an anonymous port is chosen)
      * @throws RemoteException if failed to export object
@@ -171,6 +201,11 @@ public class UnicastRemoteObject extends RemoteServer {
     /**
      * Creates and exports a new UnicastRemoteObject object using the
      * particular supplied port and socket factories.
+     *
+     * <p>Either socket factory may be {@code null}, in which case
+     * the corresponding client or server socket creation method of
+     * {@link RMISocketFactory} is used instead.
+     *
      * @param port the port number on which the remote object receives calls
      * (if <code>port</code> is zero, an anonymous port is chosen)
      * @param csf the client-side socket factory for making calls to the
@@ -236,12 +271,23 @@ public class UnicastRemoteObject extends RemoteServer {
 
     /**
      * Exports the remote object to make it available to receive incoming
-     * calls using an anonymous port.
+     * calls using an anonymous port. This method will always return a
+     * statically generated stub.
+     *
+     * <p>The object is exported with a server socket
+     * created using the {@link RMISocketFactory} class.
+     *
      * @param obj the remote object to be exported
      * @return remote object stub
      * @exception RemoteException if export fails
      * @since JDK1.1
+     * @deprecated This method is deprecated because it supports only static stubs.
+     * Use {@link #exportObject(Remote, int) exportObject(Remote, port)} or
+     * {@link #exportObject(Remote, int, RMIClientSocketFactory, RMIServerSocketFactory)
+     * exportObject(Remote, port, csf, ssf)}
+     * instead.
      */
+    @Deprecated
     public static RemoteStub exportObject(Remote obj)
         throws RemoteException
     {
@@ -258,6 +304,10 @@ public class UnicastRemoteObject extends RemoteServer {
     /**
      * Exports the remote object to make it available to receive incoming
      * calls, using the particular supplied port.
+     *
+     * <p>The object is exported with a server socket
+     * created using the {@link RMISocketFactory} class.
+     *
      * @param obj the remote object to be exported
      * @param port the port to export the object on
      * @return remote object stub
@@ -273,6 +323,11 @@ public class UnicastRemoteObject extends RemoteServer {
     /**
      * Exports the remote object to make it available to receive incoming
      * calls, using a transport specified by the given socket factory.
+     *
+     * <p>Either socket factory may be {@code null}, in which case
+     * the corresponding client or server socket creation method of
+     * {@link RMISocketFactory} is used instead.
+     *
      * @param obj the remote object to be exported
      * @param port the port to export the object on
      * @param csf the client-side socket factory for making calls to the
diff --git a/src/share/classes/java/rmi/server/package.html b/src/share/classes/java/rmi/server/package.html
index 98b76699fa..1bfa46dfa8 100644
--- a/src/share/classes/java/rmi/server/package.html
+++ b/src/share/classes/java/rmi/server/package.html
@@ -36,6 +36,23 @@ implements the RMI Transport protocol and HTTP tunneling.
 mechanism has been deprecated. See {@link java.rmi.server.RMISocketFactory} for
 further information.</em>
 
+<p><strong>Deprecated: Skeletons and Static Stubs.</strong>
+
+<em>Skeletons and statically generated stubs are deprecated.  This
+includes the APIs in this package that require the use of skeletons
+or static stubs, the runtime support for them, and the use of the
+{@code rmic} stub compiler to generate them.  Support for skeletons
+and static stubs may be removed in a future release of the
+platform. Skeletons are unnecessary, as server-side method dispatching
+is handled directly by the RMI runtime. Statically generated stubs are
+unnecessary, as stubs are generated dynamically using {@link
+java.lang.reflect.Proxy Proxy} objects. See {@link
+java.rmi.server.UnicastRemoteObject UnicastRemoteObject} for
+information about dynamic stub generation. Generation of skeletons and
+static stubs was typically performed as part of an application's build
+process by calling the {@code rmic} tool. This is unnecessary, and
+calls to {@code rmic} can simply be omitted.</em>
+
 <!--
 <h2>Package Specification</h2>