4958969: ObjectOutputStream example leads to non-working code

Reviewed-by: lancea, naoto

Author: Roger Riggs

src/java.base/share/classes/java/io/ObjectInputFilter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2016, 2021, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2016, 2022, 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
@@ -80,14 +80,15 @@
  *
  * <p>For example, a filter that allows example classes, allows classes in the
  * {@code java.base} module, and rejects all other classes can be set:
- *
- * <pre>{@code As a command line property:
- *     % java -Djdk.serialFilter="example.*;java.base/*;!*" ...}</pre>
- *
- * <pre>{@code Or programmatically:
+ * As a command line property:
+ * {@snippet :
+ *     % java -Djdk.serialFilter="example.*;java.base/*;!*" ...
+ * }
+ * Or programmatically:
+ * {@snippet lang="java":
  *     var filter = ObjectInputFilter.Config.createFilter("example.*;java.base/*;!*")
- *     ObjectInputFilter.Config.setSerialFilter(filter);}</pre>
- *
+ *     ObjectInputFilter.Config.setSerialFilter(filter);
+ * }
  * <p>In an application with multiple execution contexts, the application can provide a
  * {@linkplain Config#setSerialFilterFactory(BinaryOperator) filter factory} to
  * protect individual contexts by providing a custom filter for each. When the stream
@@ -191,7 +192,7 @@
  * The {@code doWithSerialFilter} method does the setup of the thread-specific filter
  * and invokes the application provided {@link Runnable Runnable}.
  *
- * <pre>{@code
+ * {@snippet lang="java":
  * public static final class FilterInThread implements BinaryOperator<ObjectInputFilter> {
  *
  *     private final ThreadLocal<ObjectInputFilter> filterThreadLocal = new ThreadLocal<>();
@@ -242,12 +243,12 @@
  *         }
  *     }
  * }
- * }</pre>
+ * }
  * <h3>Using the Filter Factory</h3>
  * To use {@code FilterInThread} utility create an instance and configure it as the
  * JVM-wide filter factory.  The {@code doWithSerialFilter} method is invoked with a
  * filter allowing the example application and core classes:
- * <pre>{@code
+ * {@snippet lang="java":
  *        // Create a FilterInThread filter factory and set
  *        var filterInThread = new FilterInThread();
  *        ObjectInputFilter.Config.setSerialFilterFactory(filterInThread);
@@ -258,7 +259,7 @@
  *              byte[] bytes = ...;
  *              var o = deserializeObject(bytes);
  *        });
- * }</pre>
+ * }
  * <p>
  * Unless otherwise noted, passing a {@code null} argument to a
  * method in this interface and its nested classes will cause a
@@ -310,11 +311,11 @@ public interface ObjectInputFilter {
      * <p>
      * Example, to create a filter that will allow any class loaded from the platform
      * or bootstrap classloaders.
-     * <pre><code>
+     * {@snippet lang="java":
      *     ObjectInputFilter f
      *         = allowFilter(cl -> cl.getClassLoader() == ClassLoader.getPlatformClassLoader() ||
      *                       cl.getClassLoader() == null, Status.UNDECIDED);
-     * </code></pre>
+     * }
      *
      * @param predicate a predicate to test a non-null Class
      * @param otherStatus a Status to use if the predicate is {@code false}
@@ -344,10 +345,10 @@ static ObjectInputFilter allowFilter(Predicate<Class<?>> predicate, Status other
      * </ul>
      * <p>
      * Example, to create a filter that will reject any class loaded from the application classloader.
-     * <pre><code>
+     * {@snippet lang="java":
      *     ObjectInputFilter f = rejectFilter(cl ->
      *          cl.getClassLoader() == ClassLoader.ClassLoader.getSystemClassLoader(), Status.UNDECIDED);
-     * </code></pre>
+     * }
      *
      * @param predicate a predicate to test a non-null Class
      * @param otherStatus a Status to use if the predicate is {@code false}

src/java.base/share/classes/java/io/ObjectInputStream.java

@@ -116,18 +116,18 @@
  * the object's most specific class.
  *
  * <p>For example to read from a stream as written by the example in
- * ObjectOutputStream:
+ * {@link ObjectOutputStream}:
  * <br>
- * <pre>
- *      FileInputStream fis = new FileInputStream("t.tmp");
- *      ObjectInputStream ois = new ObjectInputStream(fis);
- *
- *      int i = ois.readInt();
- *      String today = (String) ois.readObject();
- *      Date date = (Date) ois.readObject();
- *
- *      ois.close();
- * </pre>
+ * {@snippet lang="java" :
+ *     try (FileInputStream fis = new FileInputStream("t.tmp");
+ *          ObjectInputStream ois = new ObjectInputStream(fis)) {
+ *         String label = (String) ois.readObject();
+ *         LocalDateTime dateTime = (LocalDateTime) ois.readObject();
+ *         // Use label and dateTime
+ *     } catch (Exception ex) {
+ *         // handle exception
+ *     }
+ * }
  *
  * <p>Classes control how they are serialized by implementing either the
  * java.io.Serializable or java.io.Externalizable interfaces.
@@ -142,14 +142,14 @@
  * serialization and deserialization process should implement methods
  * with the following signatures:
  *
- * <pre>
- * private void writeObject(java.io.ObjectOutputStream stream)
- *     throws IOException;
- * private void readObject(java.io.ObjectInputStream stream)
- *     throws IOException, ClassNotFoundException;
- * private void readObjectNoData()
- *     throws ObjectStreamException;
- * </pre>
+ * {@snippet lang="java":
+ *     private void writeObject(java.io.ObjectOutputStream stream)
+ *         throws IOException;
+ *     private void readObject(java.io.ObjectInputStream stream)
+ *         throws IOException, ClassNotFoundException;
+ *     private void readObjectNoData()
+ *         throws ObjectStreamException;
+ * }
  *
  * <p>The method name, modifiers, return type, and number and type of
  * parameters must match exactly for the method to be used by
@@ -771,9 +771,9 @@ public void registerValidation(ObjectInputValidation obj, int prio)
      *
      * <p>The default implementation of this method in
      * {@code ObjectInputStream} returns the result of calling
-     * <pre>
+     * {@snippet lang="java":
      *     Class.forName(desc.getName(), false, loader)
-     * </pre>
+     * }
      * where {@code loader} is the first class loader on the current
      * thread's stack (starting from the currently executing method) that is
      * neither the {@linkplain ClassLoader#getPlatformClassLoader() platform
@@ -833,9 +833,9 @@ protected Class<?> resolveClass(ObjectStreamClass desc)
      * objects for the interfaces that are named in the {@code interfaces}
      * parameter.  The {@code Class} object for each interface name
      * {@code i} is the value returned by calling
-     * <pre>
+     * {@snippet lang="java":
      *     Class.forName(i, false, loader)
-     * </pre>
+     * }
      * where {@code loader} is the first class loader on the current
      * thread's stack (starting from the currently executing method) that is
      * neither the {@linkplain ClassLoader#getPlatformClassLoader() platform

src/java.base/share/classes/java/io/ObjectOutputStream.java

@@ -66,32 +66,29 @@
  * written.
  *
  * <p>For example to write an object that can be read by the example in
- * ObjectInputStream:
- * <br>
- * <pre>
- *      FileOutputStream fos = new FileOutputStream("t.tmp");
- *      ObjectOutputStream oos = new ObjectOutputStream(fos);
- *
- *      oos.writeInt(12345);
- *      oos.writeObject("Today");
- *      oos.writeObject(new Date());
- *
- *      oos.close();
- * </pre>
+ * {@link ObjectInputStream}:
+ * {@snippet lang="java":
+ *      try (FileOutputStream fos = new FileOutputStream("t.tmp");
+ *           ObjectOutputStream oos = new ObjectOutputStream(fos)) {
+ *          oos.writeObject("Today");
+ *          oos.writeObject(LocalDateTime.now());
+ *      } catch (Exception ex) {
+ *          // handle exception
+ *      }
+ * }
  *
  * <p>Serializable classes that require special handling during the
  * serialization and deserialization process should implement methods
  * with the following signatures:
  *
- * <br>
- * <pre>
- * private void readObject(java.io.ObjectInputStream stream)
- *     throws IOException, ClassNotFoundException;
- * private void writeObject(java.io.ObjectOutputStream stream)
- *     throws IOException
- * private void readObjectNoData()
- *     throws ObjectStreamException;
- * </pre>
+ * {@snippet lang="java":
+ *     private void readObject(java.io.ObjectInputStream stream)
+ *         throws IOException, ClassNotFoundException;
+ *     private void writeObject(java.io.ObjectOutputStream stream)
+ *         throws IOException;
+ *     private void readObjectNoData()
+ *         throws ObjectStreamException;
+ * }
  *
  * <p>The method name, modifiers, return type, and number and type of
  * parameters must match exactly for the method to be used by