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

[Chris Hegarty]

Looks fine Stuart.

-Chris.

> On 13 Mar 2017, at 22:11, Stuart Marks <stuart.marks at oracle.com> wrote:
> 
> .. 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
>      */