Document safer deserialization option in Javadoc for SerializationUtils

Author: garydgregory

pom.xml

@@ -174,6 +174,7 @@
     <!-- Local macOS Java 21 says 0.92 -->
     <commons.jacoco.complexityRatio>0.91</commons.jacoco.complexityRatio>
     <commons.text.version>1.15.0</commons.text.version>
+    <commons.io.version>2.21.0</commons.io.version>
   </properties>
   <build>
     <defaultGoal>clean verify apache-rat:check checkstyle:check japicmp:cmp spotbugs:check pmd:check javadoc:javadoc</defaultGoal>
@@ -231,7 +232,17 @@
                 <artifactId>commons-text</artifactId>
                 <version>${commons.text.version}</version>
               </additionalDependency>
+              <additionalDependency>
+                <groupId>commons-io</groupId>
+                <artifactId>commons-io</artifactId>
+                <version>${commons.io.version}</version>
+              </additionalDependency>
             </additionalDependencies>
+            <links>
+              <link>https://commons.apache.org/proper/commons-io/apidocs</link>
+              <link>https://commons.apache.org/proper/commons-text/apidocs</link>
+              <link>${commons.javadoc.javaee.link}</link>
+            </links>
           </configuration>
           <executions>
             <execution>
@@ -324,7 +335,20 @@
           <source>${maven.compiler.source}</source>
           <quiet>true</quiet>
           <notimestamp>true</notimestamp>
+          <additionalDependencies>
+            <additionalDependency>
+              <groupId>org.apache.commons</groupId>
+              <artifactId>commons-text</artifactId>
+              <version>${commons.text.version}</version>
+            </additionalDependency>
+            <additionalDependency>
+              <groupId>commons-io</groupId>
+              <artifactId>commons-io</artifactId>
+              <version>${commons.io.version}</version>
+            </additionalDependency>
+          </additionalDependencies>
           <links>
+            <link>https://commons.apache.org/proper/commons-io/apidocs</link>
             <link>https://commons.apache.org/proper/commons-text/apidocs</link>
             <link>${commons.javadoc.javaee.link}</link>
           </links>

src/changes/changes.xml

@@ -76,6 +76,7 @@ The <action> type attribute can be add,update,fix,remove.
     <action issue="LANG-1802" type="fix" dev="ggregory" due-to="Gary Gregory, IcoreE">Fix collision in CharRange.hashCode().</action>
     <action                   type="fix" dev="ggregory" due-to="Gary Gregory">Fix race condition in Fraction.hashCode().</action>
     <action                   type="fix" dev="ggregory" due-to="Gary Gregory">Fix race condition in Range.hashCode().</action>
+    <action                   type="fix" dev="ggregory" due-to="Gary Gregory, Akshat_Agg">Document safer deserialization option in Javadoc for SerializationUtils.</action>
     <!-- ADD -->
     <!-- UPDATE -->
     <action                   type="update" dev="ggregory" due-to="Gary Gregory, Dependabot">Bump org.apache.commons:commons-parent from 92 to 93 #1498.</action>

src/main/java/org/apache/commons/lang3/SerializationUtils.java

@@ -28,19 +28,26 @@
 import java.util.Objects;
 
 /**
- * Assists with the serialization process and performs additional functionality based
- * on serialization.
+ * Performs additional functionality for serialization.
  *
  * <ul>
  * <li>Deep clone using serialization</li>
  * <li>Serialize managing finally and IOException</li>
  * <li>Deserialize managing finally and IOException</li>
  * </ul>
  *
- * <p>This class throws exceptions for invalid {@code null} inputs.
- * Each method documents its behavior in more detail.</p>
+ * <p>
+ * This class throws exceptions for invalid {@code null} inputs. Each method documents its behavior in more detail.
+ * </p>
+ * <p>
+ * If you want to secure deserialization with a whitelist or blacklist, please use Apache Commons IO's
+ * {@link org.apache.commons.io.serialization.ValidatingObjectInputStream ValidatingObjectInputStream}.
+ * </p>
+ * <p>
+ * #ThreadSafe#
+ * </p>
  *
- * <p>#ThreadSafe#</p>
+ * @see org.apache.commons.io.serialization.ValidatingObjectInputStream
  * @since 1.0
  */
 public class SerializationUtils {
@@ -140,13 +147,18 @@ public static <T extends Serializable> T clone(final T object) {
      * Without Generics in this declaration, the call site must type cast and can cause the same ClassCastException.
      * Note that in both cases, the ClassCastException is in the call site, not in this method.
      * </p>
+     * <p>
+     * If you want to secure deserialization with a whitelist or blacklist, please use Apache Commons IO's
+     * {@link org.apache.commons.io.serialization.ValidatingObjectInputStream ValidatingObjectInputStream}.
+     * </p>
      *
      * @param <T>  the object type to be deserialized.
      * @param objectData
      *            the serialized object, must not be null.
      * @return the deserialized object.
      * @throws NullPointerException if {@code objectData} is {@code null}.
      * @throws SerializationException (runtime) if the serialization fails.
+     * @see org.apache.commons.io.serialization.ValidatingObjectInputStream
      */
     public static <T> T deserialize(final byte[] objectData) {
         Objects.requireNonNull(objectData, "objectData");
@@ -172,12 +184,17 @@ public static <T> T deserialize(final byte[] objectData) {
      * Note that in both cases, the ClassCastException is in the call site, not in this method.
      * </p>
      *
+     * <p>
+     * If you want to secure deserialization with a whitelist or blacklist, please use Apache Commons IO's
+     * {@link org.apache.commons.io.serialization.ValidatingObjectInputStream ValidatingObjectInputStream}.
+     * </p>
+     *
      * @param <T>  the object type to be deserialized.
-     * @param inputStream
-     *            the serialized object input stream, must not be null.
+     * @param inputStream the serialized object input stream, must not be null.
      * @return the deserialized object.
      * @throws NullPointerException if {@code inputStream} is {@code null}.
      * @throws SerializationException (runtime) if the serialization fails.
+     * @see org.apache.commons.io.serialization.ValidatingObjectInputStream
      */
     @SuppressWarnings("resource") // inputStream is managed by the caller
     public static <T> T deserialize(final InputStream inputStream) {