Apache
/
commons-collections
mirror of https://github.com/apache/commons-collections.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[COLLECTIONS-567] Add MultiSetUtils, fix typos, remove references to bag. 

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/collections/trunk@1714424 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Thomas Neidhart 2015-11-15 10:06:16 +00:00
parent 78d47d4d09
commit e58963b51e
6 changed files with 165 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
src/main/java/org/apache/commons/collections4/MultiSet.java
View File

@ -123,8 +123,8 @@ public interface MultiSet<E> extends Collection<E> {
* <p>
* The returned set is backed by this multiset, so any change to either
* is immediately reflected in the other. Only removal operations are
* supporting, in which case all occurrences of the removed elements
* are removed from the backing multiset.
* supported, in which case all occurrences of the element are removed
* from the backing multiset.
*
* @return the Set of unique MultiSet elements
*/

119
src/main/java/org/apache/commons/collections4/MultiSetUtils.java Normal file
View File

@ -0,0 +1,119 @@
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.commons.collections4;
import org.apache.commons.collections4.multiset.HashMultiSet;
import org.apache.commons.collections4.multiset.PredicatedMultiSet;
import org.apache.commons.collections4.multiset.SynchronizedMultiSet;
import org.apache.commons.collections4.multiset.UnmodifiableMultiSet;
/**
* Provides utility methods and decorators for {@link MultiSet} instances.
*
* @since 4.1
* @version $Id$
*/
public class MultiSetUtils {
/**
* An empty unmodifiable multiset.
*/
@SuppressWarnings("rawtypes") // OK, empty multiset is compatible with any type
public static final MultiSet EMPTY_MULTISET =
UnmodifiableMultiSet.unmodifiableMultiSet(new HashMultiSet<Object>());
/**
* Instantiation of MultiSetUtils is not intended or required.
*/
private MultiSetUtils() {}
//-----------------------------------------------------------------------
/**
* Returns a synchronized (thread-safe) multiset backed by the given multiset.
* In order to guarantee serial access, it is critical that all access to the
* backing multiset is accomplished through the returned multiset.
* <p>
* It is imperative that the user manually synchronize on the returned multiset
* when iterating over it:
*
* <pre>
* MultiSet multiset = MultiSetUtils.synchronizedMultiSet(new HashMultiSet());
* ...
* synchronized(multiset) {
* Iterator i = multiset.iterator(); // Must be in synchronized block
* while (i.hasNext())
* foo(i.next());
* }
* }
* </pre>
*
* Failure to follow this advice may result in non-deterministic behavior.
*
* @param <E> the element type
* @param multiset the multiset to synchronize, must not be null
* @return a synchronized multiset backed by that multiset
* @throws NullPointerException if the MultiSet is null
*/
public static <E> MultiSet<E> synchronizedMultiSet(final MultiSet<E> multiset) {
return SynchronizedMultiSet.synchronizedMultiSet(multiset);
}
/**
* Returns an unmodifiable view of the given multiset. Any modification attempts
* to the returned multiset will raise an {@link UnsupportedOperationException}.
*
* @param <E> the element type
* @param multiset the multiset whose unmodifiable view is to be returned, must not be null
* @return an unmodifiable view of that multiset
* @throws NullPointerException if the MultiSet is null
*/
public static <E> MultiSet<E> unmodifiableMultiSet(final MultiSet<? extends E> multiset) {
return UnmodifiableMultiSet.unmodifiableMultiSet(multiset);
}
/**
* Returns a predicated (validating) multiset backed by the given multiset.
* <p>
* Only objects that pass the test in the given predicate can be added to
* the multiset. Trying to add an invalid object results in an
* IllegalArgumentException. It is important not to use the original multiset
* after invoking this method, as it is a backdoor for adding invalid
* objects.
*
* @param <E> the element type
* @param multiset the multiset to predicate, must not be null
* @param predicate the predicate for the multiset, must not be null
* @return a predicated multiset backed by the given multiset
* @throws NullPointerException if the MultiSet or Predicate is null
*/
public static <E> MultiSet<E> predicatedMultiSet(final MultiSet<E> multiset,
final Predicate<? super E> predicate) {
return PredicatedMultiSet.predicatedMultiSet(multiset, predicate);
}
/**
* Get an empty <code>MultiSet</code>.
*
* @param <E> the element type
* @return an empty MultiSet
*/
@SuppressWarnings("unchecked") // OK, empty multiset is compatible with any type
public static <E> MultiSet<E> emptyMultiSet() {
return EMPTY_MULTISET;
}
}

37
src/main/java/org/apache/commons/collections4/collection/PredicatedCollection.java
View File

@ -26,11 +26,14 @@ import java.util.Queue;
import java.util.Set;
import org.apache.commons.collections4.Bag;
import org.apache.commons.collections4.MultiSet;
import org.apache.commons.collections4.Predicate;
import org.apache.commons.collections4.bag.HashBag;
import org.apache.commons.collections4.bag.PredicatedBag;
import org.apache.commons.collections4.functors.NotNullPredicate;
import org.apache.commons.collections4.list.PredicatedList;
import org.apache.commons.collections4.multiset.HashMultiSet;
import org.apache.commons.collections4.multiset.PredicatedMultiSet;
import org.apache.commons.collections4.queue.PredicatedQueue;
import org.apache.commons.collections4.set.PredicatedSet;
@ -327,6 +330,40 @@ public class PredicatedCollection<E> extends AbstractCollectionDecorator<E> {
return predicatedSet;
}
/**
* Create a new predicated multiset filled with the accepted elements.
* <p>
* The builder is not modified by this method, so it is possible to create more collections
* or add more elements afterwards. Further changes will not propagate to the returned multiset.
*
* @return a new predicated multiset.
*/
public MultiSet<E> createPredicatedMultiSet() {
return createPredicatedMultiSet(new HashMultiSet<E>());
}
/**
* Decorates the given multiset with validating behavior using the predicate. All accepted elements
* are appended to the multiset. If the multiset already contains elements, they are validated.
* <p>
* The builder is not modified by this method, so it is possible to create more collections
* or add more elements afterwards. Further changes will not propagate to the returned multiset.
*
* @param bag the multiset to decorate, must not be null
* @return the decorated multiset.
* @throws NullPointerException if multiset is null
* @throws IllegalArgumentException if multiset contains invalid elements
*/
public MultiSet<E> createPredicatedMultiSet(final MultiSet<E> multiset) {
if (multiset == null) {
throw new NullPointerException("MultiSet must not be null.");
}
final PredicatedMultiSet<E> predicatedMultiSet =
PredicatedMultiSet.predicatedMultiSet(multiset, predicate);
predicatedMultiSet.addAll(accepted);
return predicatedMultiSet;
}
/**
* Create a new predicated bag filled with the accepted elements.
* <p>

4
src/main/java/org/apache/commons/collections4/multiset/AbstractMapMultiSet.java
View File

@ -555,9 +555,9 @@ public abstract class AbstractMapMultiSet<E> extends AbstractCollection<E> imple
private final AbstractMapMultiSet<E> parent;
/**
* Constructs a new view of the BidiMap.
* Constructs a new view of the MultiSet.
*
* @param parent the parent BidiMap
* @param parent the parent MultiSet
*/
protected EntrySet(final AbstractMapMultiSet<E> parent) {
this.parent = parent;

8
src/main/java/org/apache/commons/collections4/multiset/HashMultiSet.java
View File

@ -47,9 +47,9 @@ public class HashMultiSet<E> extends AbstractMapMultiSet<E> implements Serializa
}
/**
* Constructs a bag containing all the members of the given collection.
* Constructs a multiset containing all the members of the given collection.
*
* @param coll a collection to copy into this bag
* @param coll a collection to copy into this multiset
*/
public HashMultiSet(final Collection<? extends E> coll) {
this();
@ -58,7 +58,7 @@ public class HashMultiSet<E> extends AbstractMapMultiSet<E> implements Serializa
//-----------------------------------------------------------------------
/**
* Write the bag out using a custom routine.
* Write the multiset out using a custom routine.
*/
private void writeObject(final ObjectOutputStream out) throws IOException {
out.defaultWriteObject();
@ -66,7 +66,7 @@ public class HashMultiSet<E> extends AbstractMapMultiSet<E> implements Serializa
}
/**
* Read the bag in using a custom routine.
* Read the multiset in using a custom routine.
*/
private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {
in.defaultReadObject();

2
src/main/java/org/apache/commons/collections4/multiset/SynchronizedMultiSet.java
View File

@ -44,7 +44,7 @@ public class SynchronizedMultiSet<E> extends SynchronizedCollection<E> implement
* @return a new synchronized MultiSet
* @throws NullPointerException if multiset is null
*/
public static <E> SynchronizedMultiSet<E> synchronizedBag(final MultiSet<E> multiset) {
public static <E> SynchronizedMultiSet<E> synchronizedMultiSet(final MultiSet<E> multiset) {
return new SynchronizedMultiSet<E>(multiset);
}