This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-lang.git
The following commit(s) were added to refs/heads/master by this push:
new 4f4aa830b Document safer deserialization option in Javadoc for
SerializationUtils
4f4aa830b is described below
commit 4f4aa830bc5e2d51722235a9449fac7ef4f425f1
Author: Gary Gregory <[email protected]>
AuthorDate: Mon Dec 15 10:11:23 2025 -0500
Document safer deserialization option in Javadoc for SerializationUtils
---
pom.xml | 24 +++++++++++++++++
src/changes/changes.xml | 1 +
.../apache/commons/lang3/SerializationUtils.java | 31 +++++++++++++++++-----
3 files changed, 49 insertions(+), 7 deletions(-)
diff --git a/pom.xml b/pom.xml
index 7ecba2c05..6bd92eedc 100644
--- a/pom.xml
+++ b/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>
diff --git a/src/changes/changes.xml b/src/changes/changes.xml
index 225dd6eb4..9e18b8e80 100644
--- a/src/changes/changes.xml
+++ b/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>
diff --git a/src/main/java/org/apache/commons/lang3/SerializationUtils.java
b/src/main/java/org/apache/commons/lang3/SerializationUtils.java
index 5a41cc7c5..7c333a8ab 100644
--- a/src/main/java/org/apache/commons/lang3/SerializationUtils.java
+++ b/src/main/java/org/apache/commons/lang3/SerializationUtils.java
@@ -28,8 +28,7 @@
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>
@@ -37,10 +36,18 @@
* <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,6 +147,10 @@ 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
@@ -147,6 +158,7 @@ public static <T extends Serializable> T clone(final T
object) {
* @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) {
