JDK 9 RFR: 8066640: clarify security checks in ObjectInputStream.enableResolveObject

[Stuart Marks]

.. and ObjectOutputStream.enableReplaceObject.

https://bugs.openjdk.java.net/browse/JDK-8066640

Please review this small spec change for these methods. This aligns the 
specification to be in agreement with the actual implementation. Essentially the 
change replaces the current wording:

<< If enable is true, and there is a security manager installed, this method 
first calls the security manager's checkPermission method.... >>

with the following:

<< If object replacement is currently not enabled, and if enable is true, and 
there is a security manager installed, this method first calls the security 
manager's checkPermission method.... >>

Patch appended below, including some editorial and markup changes to improve 
consistency.

Thanks!

s'marks



# HG changeset patch
# User smarks
# Date 1489442411 25200
#      Mon Mar 13 15:00:11 2017 -0700
# Node ID 6b6e3d5ab6027d2243d2e786682a117a8245764a
# Parent  173d03f43b765cbcddfc2dff9cbf816e088af906
8066640: clarify security checks in ObjectInputStream.enableResolveObject and 
ObjectOutputStream.enableReplaceObject
Reviewed-by: XXX

diff -r 173d03f43b76 -r 6b6e3d5ab602 
src/java.base/share/classes/java/io/ObjectInputStream.java
--- a/src/java.base/share/classes/java/io/ObjectInputStream.java	Fri Mar 10 
09:20:55 2017 -0800
+++ b/src/java.base/share/classes/java/io/ObjectInputStream.java	Mon Mar 13 
15:00:11 2017 -0700
@@ -812,23 +812,24 @@
      }

      /**
-     * Enable the stream to allow objects read from the stream to be replaced.
-     * When enabled, the resolveObject method is called for every object being
+     * Enables the stream to do replacement of objects read from the stream. When
+     * enabled, the {@link #resolveObject} method is called for every object being
       * deserialized.
       *
-     * <p>If <i>enable</i> is true, and there is a security manager installed,
+     * <p>If object replacement is currently not enabled, and
+     * {@code enable} is true, and there is a security manager installed,
       * this method first calls the security manager's
-     * <code>checkPermission</code> method with the
-     * <code>SerializablePermission("enableSubstitution")</code> permission to
-     * ensure it's ok to enable the stream to allow objects read from the
-     * stream to be replaced.
+     * {@code checkPermission} method with the
+     * {@code SerializablePermission("enableSubstitution")} permission to
+     * ensure it's ok to enable the stream to do replacement of objects
+     * read from the stream.
       *
-     * @param   enable true for enabling use of <code>resolveObject</code> for
+     * @param   enable true for enabling use of {@code resolveObject} for
       *          every object being deserialized
       * @return  the previous setting before this method was invoked
       * @throws  SecurityException if a security manager exists and its
-     *          <code>checkPermission</code> method denies enabling the stream
-     *          to allow objects read from the stream to be replaced.
+     *          {@code checkPermission} method denies enabling the stream
+     *          to do replacement of objects read from the stream.
       * @see SecurityManager#checkPermission
       * @see java.io.SerializablePermission
       */
diff -r 173d03f43b76 -r 6b6e3d5ab602 
src/java.base/share/classes/java/io/ObjectOutputStream.java
--- a/src/java.base/share/classes/java/io/ObjectOutputStream.java	Fri Mar 10 
09:20:55 2017 -0800
+++ b/src/java.base/share/classes/java/io/ObjectOutputStream.java	Mon Mar 13 
15:00:11 2017 -0700
@@ -589,22 +589,24 @@
      }

      /**
-     * Enable the stream to do replacement of objects in the stream.  When
-     * enabled, the replaceObject method is called for every object being
+     * Enables the stream to do replacement of objects written to the stream.  When
+     * enabled, the {@link #replaceObject} method is called for every object being
       * serialized.
       *
-     * <p>If <code>enable</code> is true, and there is a security manager
-     * installed, this method first calls the security manager's
-     * <code>checkPermission</code> method with a
-     * <code>SerializablePermission("enableSubstitution")</code> permission to
-     * ensure it's ok to enable the stream to do replacement of objects in the
-     * stream.
+     * <p>If object replacement is currently not enabled, and
+     * {@code enable} is true, and there is a security manager installed,
+     * this method first calls the security manager's
+     * {@code checkPermission} method with the
+     * {@code SerializablePermission("enableSubstitution")} permission to
+     * ensure it's ok to enable the stream to do replacement of objects
+     * written to the stream.
       *
-     * @param   enable boolean parameter to enable replacement of objects
+     * @param   enable true for enabling use of {@code replaceObject} for
+     *          every object being serialized
       * @return  the previous setting before this method was invoked
       * @throws  SecurityException if a security manager exists and its
-     *          <code>checkPermission</code> method denies enabling the stream
-     *          to do replacement of objects in the stream.
+     *          {@code checkPermission} method denies enabling the stream
+     *          to do replacement of objects written to the stream.
       * @see SecurityManager#checkPermission
       * @see java.io.SerializablePermission
       */