Author: tn
Date: Sun Nov 15 10:06:16 2015
New Revision: 1714424
URL: http://svn.apache.org/viewvc?rev=1714424&view=rev
Log:
[COLLECTIONS-567] Add MultiSetUtils, fix typos, remove references to bag.
Added:
commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/MultiSetUtils.java
(with props)
Modified:
commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/MultiSet.java
commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/collection/PredicatedCollection.java
commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/multiset/AbstractMapMultiSet.java
commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/multiset/HashMultiSet.java
commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/multiset/SynchronizedMultiSet.java
Modified:
commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/MultiSet.java
URL:
http://svn.apache.org/viewvc/commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/MultiSet.java?rev=1714424&r1=1714423&r2=1714424&view=diff
==============================================================================
---
commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/MultiSet.java
(original)
+++
commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/MultiSet.java
Sun Nov 15 10:06:16 2015
@@ -123,8 +123,8 @@ public interface MultiSet<E> extends Col
* <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
*/
Added:
commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/MultiSetUtils.java
URL:
http://svn.apache.org/viewvc/commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/MultiSetUtils.java?rev=1714424&view=auto
==============================================================================
---
commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/MultiSetUtils.java
(added)
+++
commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/MultiSetUtils.java
Sun Nov 15 10:06:16 2015
@@ -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;
+ }
+
+}
Propchange:
commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/MultiSetUtils.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange:
commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/MultiSetUtils.java
------------------------------------------------------------------------------
svn:keywords = Id Revision HeadURL
Propchange:
commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/MultiSetUtils.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Modified:
commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/collection/PredicatedCollection.java
URL:
http://svn.apache.org/viewvc/commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/collection/PredicatedCollection.java?rev=1714424&r1=1714423&r2=1714424&view=diff
==============================================================================
---
commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/collection/PredicatedCollection.java
(original)
+++
commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/collection/PredicatedCollection.java
Sun Nov 15 10:06:16 2015
@@ -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;
@@ -328,6 +331,40 @@ public class PredicatedCollection<E> ext
}
/**
+ * 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>
* The builder is not modified by this method, so it is possible to
create more collections
Modified:
commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/multiset/AbstractMapMultiSet.java
URL:
http://svn.apache.org/viewvc/commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/multiset/AbstractMapMultiSet.java?rev=1714424&r1=1714423&r2=1714424&view=diff
==============================================================================
---
commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/multiset/AbstractMapMultiSet.java
(original)
+++
commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/multiset/AbstractMapMultiSet.java
Sun Nov 15 10:06:16 2015
@@ -555,9 +555,9 @@ public abstract class AbstractMapMultiSe
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;
Modified:
commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/multiset/HashMultiSet.java
URL:
http://svn.apache.org/viewvc/commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/multiset/HashMultiSet.java?rev=1714424&r1=1714423&r2=1714424&view=diff
==============================================================================
---
commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/multiset/HashMultiSet.java
(original)
+++
commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/multiset/HashMultiSet.java
Sun Nov 15 10:06:16 2015
@@ -47,9 +47,9 @@ public class HashMultiSet<E> extends Abs
}
/**
- * 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 Abs
//-----------------------------------------------------------------------
/**
- * 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 Abs
}
/**
- * 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();
Modified:
commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/multiset/SynchronizedMultiSet.java
URL:
http://svn.apache.org/viewvc/commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/multiset/SynchronizedMultiSet.java?rev=1714424&r1=1714423&r2=1714424&view=diff
==============================================================================
---
commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/multiset/SynchronizedMultiSet.java
(original)
+++
commons/proper/collections/trunk/src/main/java/org/apache/commons/collections4/multiset/SynchronizedMultiSet.java
Sun Nov 15 10:06:16 2015
@@ -44,7 +44,7 @@ public class SynchronizedMultiSet<E> ext
* @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);
}
