[
https://issues.apache.org/jira/browse/COLLECTIONS-893?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Paul King updated COLLECTIONS-893:
----------------------------------
Description:
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]
was:
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]
> 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
>
> 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)
