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-collections.git
The following commit(s) were added to refs/heads/master by this push:
new 7daa5afa9 Document non-atomic merge semantics for BloomFilter (#695)
7daa5afa9 is described below
commit 7daa5afa9e9cfe66f35043e1927a22c40735c9d0
Author: Dexter.k <[email protected]>
AuthorDate: Sat Jun 27 00:32:19 2026 +0000
Document non-atomic merge semantics for BloomFilter (#695)
---
src/changes/changes.xml | 1 +
.../org/apache/commons/collections4/bloomfilter/BloomFilter.java | 7 +++++++
2 files changed, 8 insertions(+)
diff --git a/src/changes/changes.xml b/src/changes/changes.xml
index ddecd39fe..160d2bce6 100644
--- a/src/changes/changes.xml
+++ b/src/changes/changes.xml
@@ -24,6 +24,7 @@
<body>
<release version="4.6.0" date="YYYY-MM-DD" description="This is a feature
and maintenance release. Java 8 or later is required.">
<!-- FIX -->
+ <action type="fix" dev="ggregory" due-to="Naveed Khan, Gary
Gregory">[javadoc] Document that BloomFilter merge operations are non-atomic
and a filter that throws during a merge should be considered invalid.</action>
<action type="fix" dev="ggregory" due-to="Gary
Gregory">org.apache.commons.collections4.map.AbstractReferenceMap.ReferenceEntry.toReference(ReferenceStrength,
T, int) now throws IllegalArgumentException instead of Error.</action>
<action type="fix" dev="ggregory" due-to="Eric Hubert, Gary
Gregory">Remove deprecation annotation of
org.apache.commons.collections4.Factory; this will be deprecated in 5.0 in
favor of java.util.function.Supplier.</action>
<action type="fix" dev="ggregory" due-to="Eric Hubert, Gary
Gregory">Remove deprecation annotation of
org.apache.commons.collections4.Predicate; this will be deprecated in 5.0 in
favor of java.util.function.Predicate.</action>
diff --git
a/src/main/java/org/apache/commons/collections4/bloomfilter/BloomFilter.java
b/src/main/java/org/apache/commons/collections4/bloomfilter/BloomFilter.java
index b006e5317..2e4a6f308 100644
--- a/src/main/java/org/apache/commons/collections4/bloomfilter/BloomFilter.java
+++ b/src/main/java/org/apache/commons/collections4/bloomfilter/BloomFilter.java
@@ -23,6 +23,13 @@ import java.util.Objects;
* <p>
* <em>See implementation notes for {@link BitMapExtractor} and {@link
IndexExtractor}.</em>
* </p>
+ * <p>
+ * The {@code merge} operations enable bit indexes one at a time and are not
atomic. If an index is out of
+ * range an {@link IllegalArgumentException} is raised, but indexes processed
before the bad one may already
+ * have been enabled. By design the filter is not rolled back: such an
exception signals misuse with bad
+ * indexes and must not be ignored. A filter that throws during a merge should
be considered invalid, since
+ * it may hold bits that do not correspond to any valid hashed value.
+ * </p>
*
* @param <T> The BloomFilter type.
* @see BitMapExtractor
