Mercurial > hg > openjdk > lambda > jdk
changeset 10543:1ea1b24c1a04
8023863: deprecate support for statically-generated stubs from RMI (JRMP)
4449028: exportObject() javadoc should specify behavior for null socket factories
Reviewed-by: dfuchs, darcy
author | smarks |
---|---|
date | Wed, 30 Oct 2013 18:39:09 -0700 |
parents | 0734e1584d9d |
children | 18c111c17231 |
files | src/share/classes/java/rmi/server/RemoteStub.java src/share/classes/java/rmi/server/UnicastRemoteObject.java src/share/classes/java/rmi/server/package.html |
diffstat | 3 files changed, 135 insertions(+), 54 deletions(-) [+] |
line wrap: on
line diff
--- a/src/share/classes/java/rmi/server/RemoteStub.java Wed Oct 30 17:45:12 2013 -0700 +++ b/src/share/classes/java/rmi/server/RemoteStub.java Wed Oct 30 18:39:09 2013 -0700 @@ -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 @@ * * @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 @@ } /** - * 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) {
--- 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. + * + * <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> + * + * <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. * - * <p>For the constructors and static <code>exportObject</code> methods - * below, the stub for a remote object being exported is obtained as - * follows: + * <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. * * <ul> * - * <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 @@ * * <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 @@ /** * 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 @@ /** * 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 @@ /** * 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 @@ /** * 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 @@ /** * 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 @@ /** * 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
--- 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.</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>