[
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
h2. Follow-up (out of scope here)
Once parity exists: deprecate {{Bag}} in a subsequent 4.x minor andremove it in
5.0, with a generous deprecation window given how widely {{Bag}} is used.
[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
h2. Follow-up (out of scope here)
Once parity exists: deprecate {{Bag}} in a subsequent 4.x minor andremove it in
5.0, with a generous deprecation window given how widely {{Bag}} is used.
[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
> h2. Follow-up (out of scope here)
> Once parity exists: deprecate {{Bag}} in a subsequent 4.x minor andremove 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)
