[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

src/main/java/org/apache/commons/collections4/MultiSet.java

@@ -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
+     * supported, in which case all occurrences of the element are removed
-     * are removed from the backing multiset.
+     * from the backing multiset.
      *
      * @return the Set of unique MultiSet elements
      */

src/main/java/org/apache/commons/collections4/MultiSetUtils.java

@@ -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;
+    }
+
+}

src/main/java/org/apache/commons/collections4/collection/PredicatedCollection.java

@@ -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>

src/main/java/org/apache/commons/collections4/multiset/AbstractMapMultiSet.java

@@ -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;

src/main/java/org/apache/commons/collections4/multiset/HashMultiSet.java

@@ -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();

src/main/java/org/apache/commons/collections4/multiset/SynchronizedMultiSet.java

@@ -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);
     }