[
https://issues.apache.org/jira/browse/COLLECTIONS-893?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Gary D. Gregory resolved COLLECTIONS-893.
-----------------------------------------
Fix Version/s: 4.6.0
Resolution: Fixed
PR merged to git master.
> 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
> Priority: Major
> Fix For: 4.6.0
>
>
> 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
> [1] [https://lists.apache.org/thread/p54t06sod48bkr5hjklvq1jjg3msgwpn]
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
