Paul King created COLLECTIONS-893:
-------------------------------------
Summary: Bring MultiSet to feature parity with Bag to enable Bag
deprecation
Key: COLLECTIONS-893
URL: https://issues.apache.org/jira/browse/COLLECTIONS-893
Project: Commons Collections
Issue Type: Improvement
Reporter: Paul King
h2. Background
COLLECTIONS-567 added {{MultiSet}} in 4.1 as a Collection-compliant
alternative to {{Bag}}, with the stated intent that "the old Bag could
then be deprecated". That deprecation never happened, and a recent
dev@ discussion [1] concluded we should finish the transition.
{{Bag}} deviates from the {{Collection}} contract in four documented
places ({{add()}} sometimes returns false after changing the
collection, {{remove()}} removes all occurrences, and
{{containsAll}}/{{removeAll}}/{{retainAll}} respect cardinality),
which is why its javadoc warns "Exercise caution when using a bag as
a Collection". Guava and Eclipse Collections both use the
Collection-compliant design, exposing cardinality-aware operations
under dedicated method names instead.
Before {{Bag}} can be deprecated, {{MultiSet}} needs feature parity.
This issue tracks the gaps as sub-tasks.
h2. Sub-task 1: Add SortedMultiSet interface and TreeMultiSet implementation
The {{multiset}} package currently provides only {{HashMultiSet}} plus
predicated/synchronized/unmodifiable decorators. {{Bag}} users of
{{SortedBag}}/{{TreeBag}}/{{CollectionSortedBag}} have nowhere to
migrate. Add:
* {{SortedMultiSet}} interface (analogous to {{SortedBag}})
* {{TreeMultiSet}} implementation (analogous to {{TreeBag}})
* matching decorator support where applicable
h2. Sub-task 2: Add occurrence-aware helpers and migration documentation
{{Bag}}'s contract violations provided genuinely useful behaviour;
preserve it under explicit names rather than overridden
{{Collection}} methods:
* {{MultiSetUtils}} helpers analogous to Guava's
{{Multisets.containsOccurrences}}/{{removeOccurrences}}/{{retainOccurrences}}
* migration notes mapping old semantics to explicit calls, e.g.
{{bag.remove(x)}} -> {{multiSet.setCount(x, 0)}}
* cross-reference {{MultiSet}} from the {{Bag}} javadoc as the
preferred alternative
h2. Follow-up (out of scope here)
Once parity exists: deprecate {{Bag}} in a subsequent 4.x minor and
remove it in 5.0, with a generous deprecation window given how widely
{{Bag}} is used.
[1] https://lists.apache.org/thread/p54t06sod48bkr5hjklvq1jjg3msgwpn
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
