This is an automated email from the ASF dual-hosted git repository.
garydgregory 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 a0b71211f [LANG-1341] Javadoc: Clarify superclass equality in
EqualsBuilder
a0b71211f is described below
commit a0b71211f24135f66a4c1328f88d1444fead0349
Author: Gary Gregory <[email protected]>
AuthorDate: Sun Nov 1 15:20:31 2026 -0500
[LANG-1341] Javadoc: Clarify superclass equality in EqualsBuilder
Remove appendSuper(super.equals(obj)) from the general example.
When super.equals(obj) invokes Object.equals(Object), distinct
instances compare unequal even when all their fields are equal.
PR #1849 correctly addresses this documentation problem, but its
wording leaves inherited overrides implicit and describes the builder
as returning false without identifying isEquals().
Make the usage guidance explicit, cover inherited overrides, and
document that false makes the equality result false while true leaves
the current result unchanged. Explain when to omit identity comparison
for field-based equality and correct the super.equals(obj) examples.
References:
- https://issues.apache.org/jira/browse/LANG-1341
- https://github.com/apache/commons-lang/pull/1849
---
src/changes/changes.xml | 1 +
.../apache/commons/lang3/builder/EqualsBuilder.java | 21 ++++++++++++++++++---
2 files changed, 19 insertions(+), 3 deletions(-)
diff --git a/src/changes/changes.xml b/src/changes/changes.xml
index 17ffbe364..10092ea9f 100644
--- a/src/changes/changes.xml
+++ b/src/changes/changes.xml
@@ -83,6 +83,7 @@ The <action> type attribute can be add,update,fix,remove.
<action type="fix" dev="ggregory" due-to="Mohd Irshad,
Gary Gregory">Fix Conversion hex method Javadoc (#1845).</action>
<action type="fix" dev="ggregory" due-to="Gary
Gregory">Make FastDatePrinter time-zone tests deterministic (#1854).</action>
<action issue="LANG-1839" type="fix" dev="ggregory" due-to="Gary Gregory,
Raju Gupta">Fix recursive toString traversal cleanup (#1855).</action>
+ <action issue="LANG-1341" type="fix" dev="ggregory" due-to="Gary Gregory,
Reassoonn">Javadoc: Clarify superclass equality in EqualsBuilder.</action>
<!-- ADD -->
<action issue="LANG-1790" type="add" dev="ggregory" due-to="Mert Kirpici,
Ivan Šarić, Gary Gregory">Add optional FIFO ordering for TimedSemaphore
blocking acquisitions.</action>
<!-- UPDATE -->
diff --git a/src/main/java/org/apache/commons/lang3/builder/EqualsBuilder.java
b/src/main/java/org/apache/commons/lang3/builder/EqualsBuilder.java
index c1de769d1..49f561382 100644
--- a/src/main/java/org/apache/commons/lang3/builder/EqualsBuilder.java
+++ b/src/main/java/org/apache/commons/lang3/builder/EqualsBuilder.java
@@ -65,7 +65,6 @@
* }
* MyClass rhs = (MyClass) obj;
* return new EqualsBuilder()
- * .appendSuper(super.equals(obj))
* .append(field1, rhs.field1)
* .append(field2, rhs.field2)
* .append(field3, rhs.field3)
@@ -74,6 +73,11 @@
* </pre>
*
* <p>
+ * To include the superclass's equality check, add {@code
appendSuper(super.equals(obj))} to the builder chain.
+ * Omit this call if {@code super.equals(obj)} invokes {@link
Object#equals(Object)}: its identity comparison makes distinct instances
compare unequal,
+ * even when all their fields are equal. See {@link #appendSuper(boolean)} for
details.
+ * </p>
+ * <p>
* Alternatively, there is a method that uses reflection to determine
* the fields to test. Because these fields are usually private, the method,
* {@code reflectionEquals}, uses {@code AccessibleObject.setAccessible} to
@@ -896,9 +900,20 @@ private void appendArray(final Object lhs, final Object
rhs) {
}
/**
- * Adds the result of {@code super.equals()} to this builder.
+ * Includes the result of the superclass's equality check.
+ * <p>
+ * Passing {@code false} makes {@link #isEquals()} return {@code false}.
Passing {@code true} leaves the current result unchanged.
+ * </p>
+ * <p>
+ * Pass {@code super.equals(obj)} to include the superclass's equality
check. The {@code equals(Object)} implementation may be declared by the
superclass or
+ * inherited from an ancestor.
+ * </p>
+ * <p>
+ * When implementing field-based equality, omit this call if {@code
super.equals(obj)} invokes {@link Object#equals(Object)}. That implementation
compares
+ * object identity and returns {@code false} for distinct instances, even
when all their fields are equal.
+ * </p>
*
- * @param superEquals The result of calling {@code super.equals()}
+ * @param superEquals the result of calling {@code super.equals(obj)}
* @return {@code this} instance.
* @since 2.0
*/
