From 3a8e6f31c4cc23a9ba406fbf59144d812a5214c9 Mon Sep 17 00:00:00 2001 From: smarks Date: Wed, 30 Oct 2013 18:39:09 -0700 Subject: 8023863: deprecate support for statically-generated stubs from RMI (JRMP) 4449028: exportObject() javadoc should specify behavior for null socket factories Reviewed-by: dfuchs, darcy --- src/share/classes/java/rmi/server/RemoteStub.java | 25 ++-- .../java/rmi/server/UnicastRemoteObject.java | 145 ++++++++++++++------- src/share/classes/java/rmi/server/package.html | 17 +++ 3 files changed, 134 insertions(+), 53 deletions(-) (limited to 'src/share/classes/java/rmi') 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 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 @@ 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 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 @@ 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 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 --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. * - *

For the constructors and static exportObject methods - * below, the stub for a remote object being exported is obtained as - * follows: + *

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. * - *

- * - * - *

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 @@ public class UnicastRemoteObject extends RemoteServer { /** * 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 @@ public class UnicastRemoteObject extends RemoteServer { /** * 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 @@ public class UnicastRemoteObject extends RemoteServer { /** * 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 @@ 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. + * + *

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. + * + *

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. + * + *

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. +

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. +