RemoteStub 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 @@
*
* @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 RemoteStub.
+ * Constructs a {@code RemoteStub}.
*/
protected RemoteStub() {
super();
}
/**
- * Constructs a RemoteStub, with the specified remote
+ * Constructs a {@code RemoteStub} with the specified remote
* reference.
*
* @param ref the remote reference
@@ -58,14 +64,17 @@
}
/**
- * 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 setRef method
- * is not needed since RemoteStubs can be created with
- * the RemoteStub(RemoteRef) 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 -r 0734e1584d9d -r 1ea1b24c1a04 src/share/classes/java/rmi/server/UnicastRemoteObject.java
--- a/src/share/classes/java/rmi/server/UnicastRemoteObject.java Wed Oct 30 17:45:12 2013 -0700
+++ b/src/share/classes/java/rmi/server/UnicastRemoteObject.java Wed Oct 30 18:39:09 2013 -0700
@@ -30,51 +30,88 @@
/**
* 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.
+ *
+ * Deprecated: Static Stubs. 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. + * + *
There are six ways to export remote objects: + * + *
For the constructors and static exportObject methods
- * below, the stub for a remote object being exported is obtained as
- * follows:
+ *
The fourth technique, {@link #exportObject(Remote)}, + * always uses statically generated stubs and is deprecated. + * + *
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. + * + *
The default value of the + * {@code java.rmi.server.ignoreStubClasses} property is {@code false}. + * + *
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. * *
rmic tool) is loaded and an instance of that stub
- * class is constructed as follows.
- * Remote.
+ * implements an interface that extends {@code Remote}.
*
* "_Stub".
+ * the binary name of the root class with the suffix {@code _Stub}.
*
* java.rmi.server.ignoreStubClasses is set to
- * "true" (case insensitive), a {@link
- * java.lang.reflect.Proxy} instance is constructed with the following
- * properties:
+ * Stubs are dynamically generated by constructing an instance of + * a {@link java.lang.reflect.Proxy Proxy} with the following characteristics: * *
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 - *
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 * RMI Socket Factories @@ -146,6 +168,10 @@ /** * Creates and exports a new UnicastRemoteObject object using an * anonymous port. + * + *
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 @@ /** * Creates and exports a new UnicastRemoteObject object using the * particular supplied port. + * + *
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 port is zero, an anonymous port is chosen)
* @throws RemoteException if failed to export object
@@ -171,6 +201,11 @@
/**
* Creates and exports a new UnicastRemoteObject object using the
* particular supplied port and socket factories.
+ *
+ *
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 port is zero, an anonymous port is chosen)
* @param csf the client-side socket factory for making calls to the
@@ -236,12 +271,23 @@
/**
* 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.
+ *
+ *
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 @@ /** * Exports the remote object to make it available to receive incoming * calls, using the particular supplied port. + * + *
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 @@ /** * Exports the remote object to make it available to receive incoming * calls, using a transport specified by the given socket factory. + * + *
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 -r 0734e1584d9d -r 1ea1b24c1a04 src/share/classes/java/rmi/server/package.html --- a/src/share/classes/java/rmi/server/package.html Wed Oct 30 17:45:12 2013 -0700 +++ b/src/share/classes/java/rmi/server/package.html Wed Oct 30 18:39:09 2013 -0700 @@ -36,6 +36,23 @@ mechanism has been deprecated. See {@link java.rmi.server.RMISocketFactory} for further information. +
Deprecated: Skeletons and Static Stubs. + +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. +