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 39cfde6cf [COLLECTIONS-895] Deprecate the Bag family in favor of the
MultiSet family (#709)
39cfde6cf is described below
commit 39cfde6cf1d4ca5be37261253c1552d7e604ac9e
Author: Paul King <[email protected]>
AuthorDate: Fri Jul 10 23:47:57 2026 +1000
[COLLECTIONS-895] Deprecate the Bag family in favor of the MultiSet family
(#709)
---
src/main/java/org/apache/commons/collections4/Bag.java | 2 ++
src/main/java/org/apache/commons/collections4/BagUtils.java | 2 ++
src/main/java/org/apache/commons/collections4/IterableUtils.java | 1 +
src/main/java/org/apache/commons/collections4/MultiMapUtils.java | 2 ++
src/main/java/org/apache/commons/collections4/SortedBag.java | 2 ++
.../org/apache/commons/collections4/bag/AbstractBagDecorator.java | 2 ++
.../java/org/apache/commons/collections4/bag/AbstractMapBag.java | 2 ++
.../apache/commons/collections4/bag/AbstractSortedBagDecorator.java | 2 ++
src/main/java/org/apache/commons/collections4/bag/CollectionBag.java | 2 ++
.../org/apache/commons/collections4/bag/CollectionSortedBag.java | 2 ++
src/main/java/org/apache/commons/collections4/bag/HashBag.java | 2 ++
src/main/java/org/apache/commons/collections4/bag/PredicatedBag.java | 2 ++
.../org/apache/commons/collections4/bag/PredicatedSortedBag.java | 2 ++
.../java/org/apache/commons/collections4/bag/SynchronizedBag.java | 2 ++
.../org/apache/commons/collections4/bag/SynchronizedSortedBag.java | 2 ++
.../java/org/apache/commons/collections4/bag/TransformedBag.java | 2 ++
.../org/apache/commons/collections4/bag/TransformedSortedBag.java | 2 ++
src/main/java/org/apache/commons/collections4/bag/TreeBag.java | 2 ++
.../java/org/apache/commons/collections4/bag/UnmodifiableBag.java | 2 ++
.../org/apache/commons/collections4/bag/UnmodifiableSortedBag.java | 2 ++
src/main/java/org/apache/commons/collections4/bag/package-info.java | 5 +++++
.../apache/commons/collections4/collection/PredicatedCollection.java | 4 ++++
22 files changed, 48 insertions(+)
diff --git a/src/main/java/org/apache/commons/collections4/Bag.java
b/src/main/java/org/apache/commons/collections4/Bag.java
index ca95c993f..de8dde949 100644
--- a/src/main/java/org/apache/commons/collections4/Bag.java
+++ b/src/main/java/org/apache/commons/collections4/Bag.java
@@ -69,7 +69,9 @@ import java.util.Set;
* @param <E> The type of elements in this bag
* @see MultiSet
* @since 2.0
+ * @deprecated Since 4.6.0, use {@link MultiSet} instead; see the migration
notes above.
*/
+@Deprecated
public interface Bag<E> extends Collection<E> {
/**
diff --git a/src/main/java/org/apache/commons/collections4/BagUtils.java
b/src/main/java/org/apache/commons/collections4/BagUtils.java
index 2d1233e03..12ff8b29d 100644
--- a/src/main/java/org/apache/commons/collections4/BagUtils.java
+++ b/src/main/java/org/apache/commons/collections4/BagUtils.java
@@ -32,7 +32,9 @@ import
org.apache.commons.collections4.bag.UnmodifiableSortedBag;
* Provides utility methods and decorators for {@link Bag} and {@link
SortedBag} instances.
*
* @since 2.1
+ * @deprecated Since 4.6.0, use {@link MultiSetUtils} instead.
*/
+@Deprecated
public class BagUtils {
/**
diff --git a/src/main/java/org/apache/commons/collections4/IterableUtils.java
b/src/main/java/org/apache/commons/collections4/IterableUtils.java
index b7eed16d4..5bd916ff4 100644
--- a/src/main/java/org/apache/commons/collections4/IterableUtils.java
+++ b/src/main/java/org/apache/commons/collections4/IterableUtils.java
@@ -536,6 +536,7 @@ public class IterableUtils {
* @param obj the object to find the cardinality of
* @return the number of occurrences of obj in iterable
*/
+ @SuppressWarnings("deprecation") // Bag is supported until removed
public static <E, T extends E> int frequency(final Iterable<E> iterable,
final T obj) {
if (iterable instanceof Set<?>) {
return ((Set<E>) iterable).contains(obj) ? 1 : 0;
diff --git a/src/main/java/org/apache/commons/collections4/MultiMapUtils.java
b/src/main/java/org/apache/commons/collections4/MultiMapUtils.java
index a1021dbe2..3cc74cb8b 100644
--- a/src/main/java/org/apache/commons/collections4/MultiMapUtils.java
+++ b/src/main/java/org/apache/commons/collections4/MultiMapUtils.java
@@ -97,7 +97,9 @@ public class MultiMapUtils {
* @param map the {@link MultiValuedMap} to use.
* @param key the key to look up.
* @return a new Bag containing the values from the {@link
MultiValuedMap}, or null if input map is null.
+ * @deprecated Since 4.6.0, use {@link
#getValuesAsMultiSet(MultiValuedMap, Object)} instead.
*/
+ @Deprecated
public static <K, V> Bag<V> getValuesAsBag(final MultiValuedMap<K, V> map,
final K key) {
return map != null ? new HashBag<>(map.get(key)) : null;
}
diff --git a/src/main/java/org/apache/commons/collections4/SortedBag.java
b/src/main/java/org/apache/commons/collections4/SortedBag.java
index 99238a156..47151ff38 100644
--- a/src/main/java/org/apache/commons/collections4/SortedBag.java
+++ b/src/main/java/org/apache/commons/collections4/SortedBag.java
@@ -31,7 +31,9 @@ import java.util.Comparator;
* @param <E> The type of elements in this bag
* @see SortedMultiSet
* @since 2.0
+ * @deprecated Since 4.6.0, use {@link SortedMultiSet} instead; see the {@link
Bag} Javadoc for migration notes.
*/
+@Deprecated
public interface SortedBag<E> extends Bag<E> {
/**
diff --git
a/src/main/java/org/apache/commons/collections4/bag/AbstractBagDecorator.java
b/src/main/java/org/apache/commons/collections4/bag/AbstractBagDecorator.java
index dd59e6ff8..8e3fe1213 100644
---
a/src/main/java/org/apache/commons/collections4/bag/AbstractBagDecorator.java
+++
b/src/main/java/org/apache/commons/collections4/bag/AbstractBagDecorator.java
@@ -29,7 +29,9 @@ import
org.apache.commons.collections4.collection.AbstractCollectionDecorator;
*
* @param <E> The type of elements in this bag
* @since 3.0
+ * @deprecated Since 4.6.0, use {@link
org.apache.commons.collections4.multiset.AbstractMultiSetDecorator} instead.
*/
+@Deprecated
public abstract class AbstractBagDecorator<E>
extends AbstractCollectionDecorator<E> implements Bag<E> {
diff --git
a/src/main/java/org/apache/commons/collections4/bag/AbstractMapBag.java
b/src/main/java/org/apache/commons/collections4/bag/AbstractMapBag.java
index 6a424b6c5..aa9c5f65c 100644
--- a/src/main/java/org/apache/commons/collections4/bag/AbstractMapBag.java
+++ b/src/main/java/org/apache/commons/collections4/bag/AbstractMapBag.java
@@ -44,7 +44,9 @@ import org.apache.commons.collections4.set.UnmodifiableSet;
*
* @param <E> The type of elements in this bag
* @since 3.0 (previously DefaultMapBag v2.0)
+ * @deprecated Since 4.6.0, use {@link
org.apache.commons.collections4.multiset.AbstractMapMultiSet} instead.
*/
+@Deprecated
public abstract class AbstractMapBag<E> implements Bag<E> {
/**
diff --git
a/src/main/java/org/apache/commons/collections4/bag/AbstractSortedBagDecorator.java
b/src/main/java/org/apache/commons/collections4/bag/AbstractSortedBagDecorator.java
index 7fea16baf..f76933cfe 100644
---
a/src/main/java/org/apache/commons/collections4/bag/AbstractSortedBagDecorator.java
+++
b/src/main/java/org/apache/commons/collections4/bag/AbstractSortedBagDecorator.java
@@ -28,7 +28,9 @@ import org.apache.commons.collections4.SortedBag;
*
* @param <E> The type of elements in this bag
* @since 3.0
+ * @deprecated Since 4.6.0, use {@link
org.apache.commons.collections4.multiset.AbstractSortedMultiSetDecorator}
instead.
*/
+@Deprecated
public abstract class AbstractSortedBagDecorator<E>
extends AbstractBagDecorator<E> implements SortedBag<E> {
diff --git
a/src/main/java/org/apache/commons/collections4/bag/CollectionBag.java
b/src/main/java/org/apache/commons/collections4/bag/CollectionBag.java
index 99c3e1a9a..6c7d757ce 100644
--- a/src/main/java/org/apache/commons/collections4/bag/CollectionBag.java
+++ b/src/main/java/org/apache/commons/collections4/bag/CollectionBag.java
@@ -38,7 +38,9 @@ import org.apache.commons.collections4.Bag;
* @see Bag
* @param <E> The type of elements in this bag
* @since 4.0
+ * @deprecated Since 4.6.0, no longer needed; a {@link
org.apache.commons.collections4.MultiSet} already complies with the {@link
Collection} contract.
*/
+@Deprecated
public final class CollectionBag<E> extends AbstractBagDecorator<E> {
/** Serialization version */
diff --git
a/src/main/java/org/apache/commons/collections4/bag/CollectionSortedBag.java
b/src/main/java/org/apache/commons/collections4/bag/CollectionSortedBag.java
index 40c39fb7e..4b23c4849 100644
--- a/src/main/java/org/apache/commons/collections4/bag/CollectionSortedBag.java
+++ b/src/main/java/org/apache/commons/collections4/bag/CollectionSortedBag.java
@@ -29,7 +29,9 @@ import org.apache.commons.collections4.SortedBag;
*
* @param <E> The type of elements in this bag
* @since 4.0
+ * @deprecated Since 4.6.0, no longer needed; a {@link
org.apache.commons.collections4.SortedMultiSet} already complies with the
{@link java.util.Collection} contract.
*/
+@Deprecated
public final class CollectionSortedBag<E> extends
AbstractSortedBagDecorator<E> {
/** Serialization version */
diff --git a/src/main/java/org/apache/commons/collections4/bag/HashBag.java
b/src/main/java/org/apache/commons/collections4/bag/HashBag.java
index d968c3613..6efc306a6 100644
--- a/src/main/java/org/apache/commons/collections4/bag/HashBag.java
+++ b/src/main/java/org/apache/commons/collections4/bag/HashBag.java
@@ -46,7 +46,9 @@ import java.util.HashMap;
*
* @param <E> The type of elements in this bag
* @since 3.0 (previously in main package v2.0)
+ * @deprecated Since 4.6.0, use {@link
org.apache.commons.collections4.multiset.HashMultiSet} instead.
*/
+@Deprecated
public class HashBag<E> extends AbstractMapBag<E> implements Serializable {
/** Serial version lock */
diff --git
a/src/main/java/org/apache/commons/collections4/bag/PredicatedBag.java
b/src/main/java/org/apache/commons/collections4/bag/PredicatedBag.java
index 5d1ae2eba..241303552 100644
--- a/src/main/java/org/apache/commons/collections4/bag/PredicatedBag.java
+++ b/src/main/java/org/apache/commons/collections4/bag/PredicatedBag.java
@@ -42,7 +42,9 @@ import
org.apache.commons.collections4.collection.PredicatedCollection;
*
* @param <E> The type of elements in this bag
* @since 3.0
+ * @deprecated Since 4.6.0, use {@link
org.apache.commons.collections4.multiset.PredicatedMultiSet} instead.
*/
+@Deprecated
public class PredicatedBag<E> extends PredicatedCollection<E> implements
Bag<E> {
/** Serialization version */
diff --git
a/src/main/java/org/apache/commons/collections4/bag/PredicatedSortedBag.java
b/src/main/java/org/apache/commons/collections4/bag/PredicatedSortedBag.java
index 46a5beff8..f6b824c7b 100644
--- a/src/main/java/org/apache/commons/collections4/bag/PredicatedSortedBag.java
+++ b/src/main/java/org/apache/commons/collections4/bag/PredicatedSortedBag.java
@@ -40,7 +40,9 @@ import org.apache.commons.collections4.SortedBag;
*
* @param <E> The type of elements in this bag
* @since 3.0
+ * @deprecated Since 4.6.0, use {@link
org.apache.commons.collections4.multiset.PredicatedSortedMultiSet} instead.
*/
+@Deprecated
public class PredicatedSortedBag<E> extends PredicatedBag<E> implements
SortedBag<E> {
/** Serialization version */
diff --git
a/src/main/java/org/apache/commons/collections4/bag/SynchronizedBag.java
b/src/main/java/org/apache/commons/collections4/bag/SynchronizedBag.java
index 803c9ef56..56c6505f6 100644
--- a/src/main/java/org/apache/commons/collections4/bag/SynchronizedBag.java
+++ b/src/main/java/org/apache/commons/collections4/bag/SynchronizedBag.java
@@ -34,7 +34,9 @@ import
org.apache.commons.collections4.collection.SynchronizedCollection;
*
* @param <E> The type of elements in this bag
* @since 3.0
+ * @deprecated Since 4.6.0, use {@link
org.apache.commons.collections4.multiset.SynchronizedMultiSet} instead.
*/
+@Deprecated
public class SynchronizedBag<E> extends SynchronizedCollection<E> implements
Bag<E> {
/**
diff --git
a/src/main/java/org/apache/commons/collections4/bag/SynchronizedSortedBag.java
b/src/main/java/org/apache/commons/collections4/bag/SynchronizedSortedBag.java
index 4ad7353e5..f460159c9 100644
---
a/src/main/java/org/apache/commons/collections4/bag/SynchronizedSortedBag.java
+++
b/src/main/java/org/apache/commons/collections4/bag/SynchronizedSortedBag.java
@@ -34,7 +34,9 @@ import org.apache.commons.collections4.SortedBag;
*
* @param <E> The type of elements in this bag
* @since 3.0
+ * @deprecated Since 4.6.0, use {@link
org.apache.commons.collections4.multiset.SynchronizedSortedMultiSet} instead.
*/
+@Deprecated
public class SynchronizedSortedBag<E> extends SynchronizedBag<E> implements
SortedBag<E> {
/** Serialization version */
diff --git
a/src/main/java/org/apache/commons/collections4/bag/TransformedBag.java
b/src/main/java/org/apache/commons/collections4/bag/TransformedBag.java
index 22773dbdb..f7d1253ba 100644
--- a/src/main/java/org/apache/commons/collections4/bag/TransformedBag.java
+++ b/src/main/java/org/apache/commons/collections4/bag/TransformedBag.java
@@ -37,7 +37,9 @@ import org.apache.commons.collections4.set.TransformedSet;
*
* @param <E> The type of elements in this bag
* @since 3.0
+ * @deprecated Since 4.6.0, use {@link
org.apache.commons.collections4.multiset.TransformedMultiSet} instead.
*/
+@Deprecated
public class TransformedBag<E> extends TransformedCollection<E> implements
Bag<E> {
/** Serialization version */
diff --git
a/src/main/java/org/apache/commons/collections4/bag/TransformedSortedBag.java
b/src/main/java/org/apache/commons/collections4/bag/TransformedSortedBag.java
index b7c9ca60d..563b64be3 100644
---
a/src/main/java/org/apache/commons/collections4/bag/TransformedSortedBag.java
+++
b/src/main/java/org/apache/commons/collections4/bag/TransformedSortedBag.java
@@ -35,7 +35,9 @@ import org.apache.commons.collections4.Transformer;
*
* @param <E> The type of elements in this bag
* @since 3.0
+ * @deprecated Since 4.6.0, use {@link
org.apache.commons.collections4.multiset.TransformedSortedMultiSet} instead.
*/
+@Deprecated
public class TransformedSortedBag<E> extends TransformedBag<E> implements
SortedBag<E> {
/** Serialization version */
diff --git a/src/main/java/org/apache/commons/collections4/bag/TreeBag.java
b/src/main/java/org/apache/commons/collections4/bag/TreeBag.java
index e1b60df63..f2ec44668 100644
--- a/src/main/java/org/apache/commons/collections4/bag/TreeBag.java
+++ b/src/main/java/org/apache/commons/collections4/bag/TreeBag.java
@@ -52,7 +52,9 @@ import org.apache.commons.collections4.SortedBag;
*
* @param <E> The type of elements in this bag
* @since 3.0 (previously in main package v2.0)
+ * @deprecated Since 4.6.0, use {@link
org.apache.commons.collections4.multiset.TreeMultiSet} instead.
*/
+@Deprecated
public class TreeBag<E> extends AbstractMapBag<E> implements SortedBag<E>,
Serializable {
/** Serial version lock */
diff --git
a/src/main/java/org/apache/commons/collections4/bag/UnmodifiableBag.java
b/src/main/java/org/apache/commons/collections4/bag/UnmodifiableBag.java
index db4831d55..8d619bf2c 100644
--- a/src/main/java/org/apache/commons/collections4/bag/UnmodifiableBag.java
+++ b/src/main/java/org/apache/commons/collections4/bag/UnmodifiableBag.java
@@ -40,7 +40,9 @@ import org.apache.commons.collections4.set.UnmodifiableSet;
*
* @param <E> The type of elements in this bag
* @since 3.0
+ * @deprecated Since 4.6.0, use {@link
org.apache.commons.collections4.multiset.UnmodifiableMultiSet} instead.
*/
+@Deprecated
public final class UnmodifiableBag<E>
extends AbstractBagDecorator<E> implements Unmodifiable {
diff --git
a/src/main/java/org/apache/commons/collections4/bag/UnmodifiableSortedBag.java
b/src/main/java/org/apache/commons/collections4/bag/UnmodifiableSortedBag.java
index 225d64aad..59e5037ff 100644
---
a/src/main/java/org/apache/commons/collections4/bag/UnmodifiableSortedBag.java
+++
b/src/main/java/org/apache/commons/collections4/bag/UnmodifiableSortedBag.java
@@ -40,7 +40,9 @@ import org.apache.commons.collections4.set.UnmodifiableSet;
*
* @param <E> The type of elements in this bag
* @since 3.0
+ * @deprecated Since 4.6.0, use {@link
org.apache.commons.collections4.multiset.UnmodifiableSortedMultiSet} instead.
*/
+@Deprecated
public final class UnmodifiableSortedBag<E>
extends AbstractSortedBagDecorator<E> implements Unmodifiable {
diff --git
a/src/main/java/org/apache/commons/collections4/bag/package-info.java
b/src/main/java/org/apache/commons/collections4/bag/package-info.java
index cb8284af7..fa9dbd5bf 100644
--- a/src/main/java/org/apache/commons/collections4/bag/package-info.java
+++ b/src/main/java/org/apache/commons/collections4/bag/package-info.java
@@ -36,5 +36,10 @@
* <li>Transformed - transforms each element added to the bag</li>
* <li>Collection - ensures compliance with the java.util.Collection
contract</li>
* </ul>
+ * <p>
+ * This package is deprecated since 4.6.0; use the
+ * {@link org.apache.commons.collections4.multiset} package instead. See the
+ * {@link org.apache.commons.collections4.Bag Bag} Javadoc for migration notes.
+ * </p>
*/
package org.apache.commons.collections4.bag;
diff --git
a/src/main/java/org/apache/commons/collections4/collection/PredicatedCollection.java
b/src/main/java/org/apache/commons/collections4/collection/PredicatedCollection.java
index cc44b06fb..cd0ffbe7e 100644
---
a/src/main/java/org/apache/commons/collections4/collection/PredicatedCollection.java
+++
b/src/main/java/org/apache/commons/collections4/collection/PredicatedCollection.java
@@ -155,7 +155,9 @@ public class PredicatedCollection<E> extends
AbstractCollectionDecorator<E> {
* </p>
*
* @return a new predicated bag.
+ * @deprecated Since 4.6.0, use {@link #createPredicatedMultiSet()}
instead.
*/
+ @Deprecated
public Bag<E> createPredicatedBag() {
return createPredicatedBag(new HashBag<>());
}
@@ -172,7 +174,9 @@ public class PredicatedCollection<E> extends
AbstractCollectionDecorator<E> {
* @return the decorated bag.
* @throws NullPointerException if bag is null.
* @throws IllegalArgumentException if bag contains invalid elements.
+ * @deprecated Since 4.6.0, use {@link
#createPredicatedMultiSet(MultiSet)} instead.
*/
+ @Deprecated
public Bag<E> createPredicatedBag(final Bag<E> bag) {
Objects.requireNonNull(bag, "bag");
final PredicatedBag<E> predicatedBag =
PredicatedBag.predicatedBag(bag, predicate);
