This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-collections.git
The following commit(s) were added to refs/heads/master by this push:
new 346c8e7e9 Javadoc
346c8e7e9 is described below
commit 346c8e7e9e63f70a90cd4d17be567695a4826468
Author: Gary Gregory <garydgreg...@gmail.com>
AuthorDate: Sun Oct 20 17:01:23 2024 -0400
Javadoc
- Close HTML tags
- Use longer lines
- Whitespace before tags
- Remove dead inline comments
---
.../collections4/map/AbstractHashedMap.java | 23 ++++++++++++
.../collections4/map/AbstractLinkedMap.java | 6 +++-
.../collections4/map/AbstractReferenceMap.java | 12 +++++++
.../commons/collections4/map/CompositeMap.java | 1 +
.../commons/collections4/map/DefaultedMap.java | 3 ++
.../apache/commons/collections4/map/Flat3Map.java | 13 +++++++
.../apache/commons/collections4/map/LRUMap.java | 13 ++++++-
.../apache/commons/collections4/map/LinkedMap.java | 2 ++
.../commons/collections4/map/ListOrderedMap.java | 12 ++++++-
.../commons/collections4/map/MultiKeyMap.java | 4 +++
.../commons/collections4/map/MultiValueMap.java | 14 ++++++--
.../collections4/map/PassiveExpiringMap.java | 11 +++---
.../commons/collections4/map/PredicatedMap.java | 1 +
.../collections4/map/PredicatedSortedMap.java | 1 +
.../collections4/map/ReferenceIdentityMap.java | 4 +++
.../commons/collections4/map/SingletonMap.java | 2 ++
.../commons/collections4/map/StaticBucketMap.java | 41 ++++++++++------------
.../commons/collections4/map/TransformedMap.java | 5 +++
.../collections4/map/TransformedSortedMap.java | 5 ++-
.../multimap/AbstractListValuedMap.java | 1 +
.../multimap/AbstractSetValuedMap.java | 1 +
.../multimap/TransformedMultiValuedMap.java | 5 +++
.../multimap/UnmodifiableMultiValuedMap.java | 1 +
.../collections4/multiset/AbstractMapMultiSet.java | 3 +-
.../collections4/multiset/PredicatedMultiSet.java | 1 +
.../multiset/UnmodifiableMultiSet.java | 1 +
26 files changed, 152 insertions(+), 34 deletions(-)
diff --git
a/src/main/java/org/apache/commons/collections4/map/AbstractHashedMap.java
b/src/main/java/org/apache/commons/collections4/map/AbstractHashedMap.java
index a47fe87b7..96c7eb885 100644
--- a/src/main/java/org/apache/commons/collections4/map/AbstractHashedMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/AbstractHashedMap.java
@@ -45,14 +45,17 @@ import
org.apache.commons.collections4.iterators.EmptyMapIterator;
* Key-value entries are stored in instances of the {@code HashEntry} class,
* which can be overridden and replaced. The iterators can similarly be
replaced,
* without the need to replace the KeySet, EntrySet and Values view classes.
+ * </p>
* <p>
* Overridable methods are provided to change the default hashing behavior, and
* to change how entries are added to and removed from the map. Hopefully, all
you
* need for unusual subclasses is here.
+ * </p>
* <p>
* NOTE: From Commons Collections 3.1 this class extends AbstractMap.
* This is to provide backwards compatibility for ReferenceMap between v3.0
and v3.1.
* This extends clause will be removed in v5.0.
+ * </p>
*
* @param <K> the type of the keys in this map
* @param <V> the type of the values in this map
@@ -651,6 +654,7 @@ public class AbstractHashedMap<K, V> extends AbstractMap<K,
V> implements Iterab
* <p>
* This implementation adds the entry to the data storage table.
* Subclasses could override to handle changes to the map.
+ * </p>
*
* @param entry the entry to add
* @param hashIndex the index into the data array to store at
@@ -666,6 +670,7 @@ public class AbstractHashedMap<K, V> extends AbstractMap<K,
V> implements Iterab
* and {@code checkCapacity()}.
* It also handles changes to {@code modCount} and {@code size}.
* Subclasses could override to fully control adds to the map.
+ * </p>
*
* @param hashIndex the index into the data array to store at
* @param hashCode the hash code of the key to add
@@ -718,6 +723,7 @@ public class AbstractHashedMap<K, V> extends AbstractMap<K,
V> implements Iterab
* Checks the capacity of the map and enlarges it if necessary.
* <p>
* This implementation uses the threshold to check if the map needs
enlarging
+ * </p>
*/
protected void checkCapacity() {
if (size >= threshold) {
@@ -745,6 +751,7 @@ public class AbstractHashedMap<K, V> extends AbstractMap<K,
V> implements Iterab
* <p>
* To implement {@code clone()}, a subclass must implement the
* {@code Cloneable} interface and make this method public.
+ * </p>
*
* @return a shallow clone
* @throws InternalError if {@link AbstractMap#clone()} failed
@@ -827,6 +834,7 @@ public class AbstractHashedMap<K, V> extends AbstractMap<K,
V> implements Iterab
* <p>
* The reverse conversion can be changed, if required, by overriding the
* getKey() method in the hash entry.
+ * </p>
*
* @param key the key convert
* @return the converted key
@@ -841,6 +849,7 @@ public class AbstractHashedMap<K, V> extends AbstractMap<K,
V> implements Iterab
* This implementation creates a new HashEntry instance.
* Subclasses can override this to return a different storage class,
* or implement caching.
+ * </p>
*
* @param next the next entry in sequence
* @param hashCode the hash code to use
@@ -896,6 +905,7 @@ public class AbstractHashedMap<K, V> extends AbstractMap<K,
V> implements Iterab
* <p>
* This implementation prepares the HashEntry for garbage collection.
* Subclasses can override this to implement caching (override clear as
well).
+ * </p>
*
* @param entry the entry to destroy
*/
@@ -913,13 +923,16 @@ public class AbstractHashedMap<K, V> extends
AbstractMap<K, V> implements Iterab
* initialize the superclass before the subclass. Sometimes however, this
isn't
* what you want, as in this case the {@code put()} method on read can be
* affected by subclass state.
+ * </p>
* <p>
* The solution adopted here is to deserialize the state data of this
class in
* this protected method. This method must be called by the
* {@code readObject()} of the first serializable subclass.
+ * </p>
* <p>
* Subclasses may override if the subclass has a specific field that must
be present
* before {@code put()} or {@code calculateThreshold()} will work
correctly.
+ * </p>
*
* @param in the input stream
* @throws IOException if an error occurs while reading from the stream
@@ -948,14 +961,17 @@ public class AbstractHashedMap<K, V> extends
AbstractMap<K, V> implements Iterab
* initialize the superclass before the subclass. Sometimes however, this
isn't
* what you want, as in this case the {@code put()} method on read can be
* affected by subclass state.
+ * </p>
* <p>
* The solution adopted here is to serialize the state data of this class
in
* this protected method. This method must be called by the
* {@code writeObject()} of the first serializable subclass.
+ * </p>
* <p>
* Subclasses may override if they have a specific field that must be
present
* on read before this implementation will work. Generally, the read
determines
* what must be serialized here, if anything.
+ * </p>
*
* @param out the output stream
* @throws IOException if an error occurs while writing to the stream
@@ -1137,6 +1153,7 @@ public class AbstractHashedMap<K, V> extends
AbstractMap<K, V> implements Iterab
* This method exists for subclasses that may need to perform a multi-step
* process accessing the entry. The public methods in this class don't use
this
* method to gain a small performance boost.
+ * </p>
*
* @param key the key
* @return the entry, null if no match
@@ -1266,6 +1283,7 @@ public class AbstractHashedMap<K, V> extends
AbstractMap<K, V> implements Iterab
* methods to get the key and value, and set the value.
* It avoids the need to create an entrySet/keySet/values object.
* It also avoids creating the Map.Entry object.
+ * </p>
*
* @return the map iterator
*/
@@ -1308,6 +1326,7 @@ public class AbstractHashedMap<K, V> extends
AbstractMap<K, V> implements Iterab
* <p>
* This implementation iterates around the specified map and
* uses {@link #put(Object, Object)}.
+ * </p>
*
* @param map the map to add
* @throws NullPointerException if the map is null
@@ -1356,6 +1375,7 @@ public class AbstractHashedMap<K, V> extends
AbstractMap<K, V> implements Iterab
* This implementation removes the entry from the data storage table.
* The size is not updated.
* Subclasses could override to handle changes to the map.
+ * </p>
*
* @param entry the entry to remove
* @param hashIndex the index into the data structure
@@ -1375,6 +1395,7 @@ public class AbstractHashedMap<K, V> extends
AbstractMap<K, V> implements Iterab
* This implementation calls {@code removeEntry()} and {@code
destroyEntry()}.
* It also handles changes to {@code modCount} and {@code size}.
* Subclasses could override to fully control removals from the map.
+ * </p>
*
* @param entry the entry to remove
* @param hashIndex the index into the data structure
@@ -1392,6 +1413,7 @@ public class AbstractHashedMap<K, V> extends
AbstractMap<K, V> implements Iterab
* <p>
* This implementation sets all the data fields on the entry.
* Subclasses could populate additional entry fields.
+ * </p>
*
* @param entry the entry to update, not null
* @param hashIndex the index in the data array
@@ -1454,6 +1476,7 @@ public class AbstractHashedMap<K, V> extends
AbstractMap<K, V> implements Iterab
* <p>
* This implementation calls {@code setValue()} on the entry.
* Subclasses could override to handle changes to the map.
+ * </p>
*
* @param entry the entry to update
* @param newValue the new value to store
diff --git
a/src/main/java/org/apache/commons/collections4/map/AbstractLinkedMap.java
b/src/main/java/org/apache/commons/collections4/map/AbstractLinkedMap.java
index e4b81ec86..e350f3e79 100644
--- a/src/main/java/org/apache/commons/collections4/map/AbstractLinkedMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/AbstractLinkedMap.java
@@ -426,6 +426,7 @@ public abstract class AbstractLinkedMap<K, V> extends
AbstractHashedMap<K, V> im
* <p>
* This implementation adds the entry to the data storage table and
* to the end of the linked list.
+ * </p>
*
* @param entry the entry to add
* @param hashIndex the index into the data array to store at
@@ -480,6 +481,7 @@ public abstract class AbstractLinkedMap<K, V> extends
AbstractHashedMap<K, V> im
* Creates an entry to store the data.
* <p>
* This implementation creates a new LinkEntry instance.
+ * </p>
*
* @param next the next entry in sequence
* @param hashCode the hash code to use
@@ -612,9 +614,10 @@ public abstract class AbstractLinkedMap<K, V> extends
AbstractHashedMap<K, V> im
/**
* Initialize this subclass during construction.
* <p>
- * NOTE: As from v3.2 this method calls
+ * Note: As from v3.2 this method calls
* {@link #createEntry(HashEntry, int, Object, Object)} to create
* the map entry object.
+ * </p>
*/
@Override
protected void init() {
@@ -675,6 +678,7 @@ public abstract class AbstractLinkedMap<K, V> extends
AbstractHashedMap<K, V> im
* <p>
* This implementation removes the entry from the linked list chain, then
* calls the superclass implementation.
+ * </p>
*
* @param entry the entry to remove
* @param hashIndex the index into the data structure
diff --git
a/src/main/java/org/apache/commons/collections4/map/AbstractReferenceMap.java
b/src/main/java/org/apache/commons/collections4/map/AbstractReferenceMap.java
index 86b4bfbca..4e5e3fac6 100644
---
a/src/main/java/org/apache/commons/collections4/map/AbstractReferenceMap.java
+++
b/src/main/java/org/apache/commons/collections4/map/AbstractReferenceMap.java
@@ -221,6 +221,7 @@ public abstract class AbstractReferenceMap<K, V> extends
AbstractHashedMap<K, V>
* <p>
* This implementation uses {@code isEqualKey} and
* {@code isEqualValue} on the main map for comparison.
+ * </p>
*
* @param obj the other map entry to compare to
* @return true if equal, false if not
@@ -797,13 +798,16 @@ public abstract class AbstractReferenceMap<K, V> extends
AbstractHashedMap<K, V>
* initialize the superclass before the subclass. Sometimes however, this
isn't
* what you want, as in this case the {@code put()} method on read can be
* affected by subclass state.
+ * </p>
* <p>
* The solution adopted here is to deserialize the state data of this
class in
* this protected method. This method must be called by the
* {@code readObject()} of the first serializable subclass.
+ * </p>
* <p>
* Subclasses may override if the subclass has a specific field that must
be present
* before {@code put()} or {@code calculateThreshold()} will work
correctly.
+ * </p>
*
* @param in the input stream
* @throws IOException if an error occurs while reading from the stream
@@ -846,14 +850,17 @@ public abstract class AbstractReferenceMap<K, V> extends
AbstractHashedMap<K, V>
* initialize the superclass before the subclass. Sometimes however, this
isn't
* what you want, as in this case the {@code put()} method on read can be
* affected by subclass state.
+ * </p>
* <p>
* The solution adopted here is to serialize the state data of this class
in
* this protected method. This method must be called by the
* {@code writeObject()} of the first serializable subclass.
+ * </p>
* <p>
* Subclasses may override if they have a specific field that must be
present
* on read before this implementation will work. Generally, the read
determines
* what must be serialized here, if anything.
+ * </p>
*
* @param out the output stream
* @throws IOException if an error occurs while writing to the stream
@@ -955,6 +962,7 @@ public abstract class AbstractReferenceMap<K, V> extends
AbstractHashedMap<K, V>
* <p>
* This implementation converts the key from the entry to a real reference
* before comparison.
+ * </p>
*
* @param key1 the first key to compare passed in from outside
* @param key2 the second key extracted from the entry via {@code
entry.key}
@@ -969,6 +977,7 @@ public abstract class AbstractReferenceMap<K, V> extends
AbstractHashedMap<K, V>
/**
* Provided protected read-only access to the key type.
+ *
* @param type the type to check against.
* @return true if keyType has the specified type
*/
@@ -978,6 +987,7 @@ public abstract class AbstractReferenceMap<K, V> extends
AbstractHashedMap<K, V>
/**
* Provided protected read-only access to the value type.
+ *
* @param type the type to check against.
* @return true if valueType has the specified type
*/
@@ -1016,6 +1026,7 @@ public abstract class AbstractReferenceMap<K, V> extends
AbstractHashedMap<K, V>
* care must be taken if, for instance, you want stale
* mappings to be removed on a periodic basis by some
* background thread.
+ * </p>
*/
protected void purge() {
Reference<?> ref = queue.poll();
@@ -1073,6 +1084,7 @@ public abstract class AbstractReferenceMap<K, V> extends
AbstractHashedMap<K, V>
* Purges stale mappings from this map before write operations.
* <p>
* This implementation calls {@link #purge()} to maintain a consistent
state.
+ * </p>
*/
protected void purgeBeforeWrite() {
purge();
diff --git
a/src/main/java/org/apache/commons/collections4/map/CompositeMap.java
b/src/main/java/org/apache/commons/collections4/map/CompositeMap.java
index 7f3a806f6..d6ee47cf4 100644
--- a/src/main/java/org/apache/commons/collections4/map/CompositeMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/CompositeMap.java
@@ -387,6 +387,7 @@ public class CompositeMap<K, V> extends
AbstractIterableMap<K, V> implements Ser
* <p>
* This implementation returns a {@code CompositeSet} which
* composites the key sets from all of the composited maps.
+ * </p>
*
* @return a set view of the keys contained in this map.
*/
diff --git
a/src/main/java/org/apache/commons/collections4/map/DefaultedMap.java
b/src/main/java/org/apache/commons/collections4/map/DefaultedMap.java
index 86fe2fa9c..8803029bd 100644
--- a/src/main/java/org/apache/commons/collections4/map/DefaultedMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/DefaultedMap.java
@@ -99,6 +99,7 @@ public class DefaultedMap<K, V> extends
AbstractMapDecorator<K, V> implements Se
* The transformer specified is called when a missing key is found.
* The key is passed to the transformer as the input, and the result
* will be returned as the result of the map get(key) method.
+ * </p>
*
* @param <K> the key type
* @param <V> the value type
@@ -117,6 +118,7 @@ public class DefaultedMap<K, V> extends
AbstractMapDecorator<K, V> implements Se
* Factory method to create a defaulting map.
* <p>
* The value specified is returned when a missing key is found.
+ * </p>
*
* @param <K> the key type
* @param <V> the value type
@@ -160,6 +162,7 @@ public class DefaultedMap<K, V> extends
AbstractMapDecorator<K, V> implements Se
* <p>
* The object passed in will be returned by the map whenever an
* unknown key is requested.
+ * </p>
*
* @param defaultValue the default value to return when the key is not
found
*/
diff --git a/src/main/java/org/apache/commons/collections4/map/Flat3Map.java
b/src/main/java/org/apache/commons/collections4/map/Flat3Map.java
index 328fa5569..0bfa253d6 100644
--- a/src/main/java/org/apache/commons/collections4/map/Flat3Map.java
+++ b/src/main/java/org/apache/commons/collections4/map/Flat3Map.java
@@ -287,6 +287,7 @@ public class Flat3Map<K, V> implements IterableMap<K, V>,
Serializable, Cloneabl
}
}
+
/**
* FlatMapIterator
*/
@@ -392,10 +393,12 @@ public class Flat3Map<K, V> implements IterableMap<K, V>,
Serializable, Cloneabl
return "Iterator[]";
}
}
+
/**
* KeySet
*/
static class KeySet<K> extends AbstractSet<K> {
+
private final Flat3Map<K, ?> parent;
KeySet(final Flat3Map<K, ?> parent) {
@@ -435,6 +438,7 @@ public class Flat3Map<K, V> implements IterableMap<K, V>,
Serializable, Cloneabl
return parent.size();
}
}
+
/**
* KeySetIterator
*/
@@ -450,10 +454,12 @@ public class Flat3Map<K, V> implements IterableMap<K, V>,
Serializable, Cloneabl
return nextEntry().getKey();
}
}
+
/**
* Values
*/
static class Values<V> extends AbstractCollection<V> {
+
private final Flat3Map<?, V> parent;
Values(final Flat3Map<?, V> parent) {
@@ -486,6 +492,7 @@ public class Flat3Map<K, V> implements IterableMap<K, V>,
Serializable, Cloneabl
return parent.size();
}
}
+
/**
* ValuesIterator
*/
@@ -501,10 +508,13 @@ public class Flat3Map<K, V> implements IterableMap<K, V>,
Serializable, Cloneabl
return nextEntry().getValue();
}
}
+
/** Serialization version */
private static final long serialVersionUID = -6701087419741928296L;
+
/** The size of the map, used while in flat mode */
private transient int size;
+
/** Hash, used while in flat mode */
private transient int hash1;
@@ -709,6 +719,7 @@ public class Flat3Map<K, V> implements IterableMap<K, V>,
Serializable, Cloneabl
* This can be overridden by subclasses to provide a different map
implementation.
* Not every AbstractHashedMap is suitable, identity and reference based
maps
* would be poor choices.
+ * </p>
*
* @return a new AbstractHashedMap or subclass
* @since 3.1
@@ -724,6 +735,7 @@ public class Flat3Map<K, V> implements IterableMap<K, V>,
Serializable, Cloneabl
* NOTE: from 4.0, the returned Map Entry will be an independent object
and will
* not change anymore as the iterator progresses. To avoid this additional
object
* creation and simply iterate through the entries, use {@link
#mapIterator()}.
+ * </p>
*
* @return the entrySet view
*/
@@ -895,6 +907,7 @@ public class Flat3Map<K, V> implements IterableMap<K, V>,
Serializable, Cloneabl
* methods to get the key and value, and set the value.
* It avoids the need to create an entrySet/keySet/values object.
* It also avoids creating the Map Entry object.
+ * </p>
*
* @return the map iterator
*/
diff --git a/src/main/java/org/apache/commons/collections4/map/LRUMap.java
b/src/main/java/org/apache/commons/collections4/map/LRUMap.java
index 9cd375a59..f2e9151f4 100644
--- a/src/main/java/org/apache/commons/collections4/map/LRUMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/LRUMap.java
@@ -193,6 +193,7 @@ public class LRUMap<K, V>
* Constructor copying elements from another map.
* <p>
* The maximum size is set from the map's size.
+ * </p>
*
* @param map the map to copy
* @throws NullPointerException if the map is null
@@ -223,10 +224,12 @@ public class LRUMap<K, V>
* <p>
* This implementation checks the LRU size and determines whether to
* discard an entry or not using {@link
#removeLRU(AbstractLinkedMap.LinkEntry)}.
+ * </p>
* <p>
* From Commons Collections 3.1 this method uses {@link #isFull()} rather
* than accessing {@code size} and {@code maxSize} directly.
* It also handles the scanUntilRemovable functionality.
+ * </p>
*
* @param hashIndex the index into the data array to store at
* @param hashCode the hash code of the key to add
@@ -327,6 +330,7 @@ public class LRUMap<K, V>
* If {@code updateToMRU} is {@code true}, the position of the key in the
map
* is changed to the most recently used position (last), otherwise the
iteration
* order is not changed by this operation.
+ * </p>
*
* @param key the key
* @param updateToMRU whether the key shall be updated to the
@@ -380,6 +384,7 @@ public class LRUMap<K, V>
* Moves an entry to the MRU position at the end of the list.
* <p>
* This implementation moves the updated entry to the end of the list.
+ * </p>
*
* @param entry the entry to update
*/
@@ -421,6 +426,7 @@ public class LRUMap<K, V>
* <p>
* This method exists for subclasses to override. A subclass may wish to
* provide cleanup of resources when an entry is removed. For example:
+ * </p>
* <pre>
* protected boolean removeLRU(LinkEntry entry) {
* releaseResources(entry.getValue()); // release resources held by
entry
@@ -430,6 +436,7 @@ public class LRUMap<K, V>
* <p>
* Alternatively, a subclass may choose to not remove the entry or
selectively
* keep certain LRU entries. For example:
+ * </p>
* <pre>
* protected boolean removeLRU(LinkEntry entry) {
* if (entry.getKey().toString().startsWith("System.")) {
@@ -439,13 +446,16 @@ public class LRUMap<K, V>
* }
* }
* </pre>
+ * <p>
* The effect of returning false is dependent on the scanUntilRemovable
flag.
* If the flag is true, the next LRU entry will be passed to this method
and so on
* until one returns false and is removed, or every entry in the map has
been passed.
* If the scanUntilRemovable flag is false, the map will exceed the
maximum size.
+ * </p>
* <p>
- * NOTE: Commons Collections 3.0 passed the wrong entry to this method.
+ * Note: Commons Collections 3.0 passed the wrong entry to this method.
* This is fixed in version 3.1 onwards.
+ * </p>
*
* @param entry the entry to be removed
* @return {@code true}
@@ -502,6 +512,7 @@ public class LRUMap<K, V>
* <p>
* This implementation moves the updated entry to the end of the list
* using {@link #moveToMRU(AbstractLinkedMap.LinkEntry)}.
+ * </p>
*
* @param entry the entry to update
* @param newValue the new value to store
diff --git a/src/main/java/org/apache/commons/collections4/map/LinkedMap.java
b/src/main/java/org/apache/commons/collections4/map/LinkedMap.java
index 6bfc2a848..0683720c3 100644
--- a/src/main/java/org/apache/commons/collections4/map/LinkedMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/LinkedMap.java
@@ -227,8 +227,10 @@ public class LinkedMap<K, V> extends AbstractLinkedMap<K,
V> implements Serializ
* the end of the list, which is an unexpected side effect of changing the
* value of a list. This occurs because changing the key, changes when the
* mapping is added to the map and thus where it appears in the list.
+ * </p>
* <p>
* An alternative to this method is to use {@link #keySet()}.
+ * </p>
*
* @see #keySet()
* @return The ordered list of keys.
diff --git
a/src/main/java/org/apache/commons/collections4/map/ListOrderedMap.java
b/src/main/java/org/apache/commons/collections4/map/ListOrderedMap.java
index f08dcb1af..b1d855850 100644
--- a/src/main/java/org/apache/commons/collections4/map/ListOrderedMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/ListOrderedMap.java
@@ -380,6 +380,7 @@ public class ListOrderedMap<K, V>
* Factory method to create an ordered map.
* <p>
* An {@code ArrayList} is used to retain order.
+ * </p>
*
* @param <K> the key type
* @param <V> the value type
@@ -425,9 +426,11 @@ public class ListOrderedMap<K, V>
* the end of the list, which is an unexpected side effect of changing the
* value of a list. This occurs because changing the key, changes when the
* mapping is added to the map and thus where it appears in the list.
+ * </p>
* <p>
* An alternative to this method is to use the better named
* {@link #keyList()} or {@link #keySet()}.
+ * </p>
*
* @see #keyList()
* @see #keySet()
@@ -447,6 +450,7 @@ public class ListOrderedMap<K, V>
* Gets a view over the entries in the map.
* <p>
* The Set will be ordered by object insertion into the map.
+ * </p>
*
* @return the fully modifiable set view over the entries
*/
@@ -506,6 +510,7 @@ public class ListOrderedMap<K, V>
* <p>
* The List will be ordered by object insertion into the map.
* The List is unmodifiable.
+ * </p>
*
* @see #keySet()
* @return the unmodifiable list view over the keys
@@ -519,6 +524,7 @@ public class ListOrderedMap<K, V>
* Gets a view over the keys in the map.
* <p>
* The Collection will be ordered by object insertion into the map.
+ * </p>
*
* @see #keyList()
* @return the fully modifiable collection view over the keys
@@ -542,7 +548,6 @@ public class ListOrderedMap<K, V>
return insertOrder.get(size() - 1);
}
- // Implement OrderedMap
@Override
public OrderedMapIterator<K, V> mapIterator() {
return new ListOrderedMapIterator<>(this);
@@ -587,10 +592,12 @@ public class ListOrderedMap<K, V>
* is removed and the new mapping added at the specified index.
* The remove may change the effect of the index. The index is
* always calculated relative to the original state of the map.
+ * </p>
* <p>
* Thus, the steps are: (1) remove the existing key-value mapping,
* then (2) insert the new key-value mapping at the position it
* would have been inserted had the remove not occurred.
+ * </p>
*
* @param index the index at which the mapping should be inserted
* @param key the key
@@ -751,6 +758,7 @@ public class ListOrderedMap<K, V>
* <p>
* The List will be ordered by object insertion into the map.
* The List supports remove and set, but does not support add.
+ * </p>
*
* @see #values()
* @return the partially modifiable list view over the values
@@ -764,9 +772,11 @@ public class ListOrderedMap<K, V>
* Gets a view over the values in the map.
* <p>
* The Collection will be ordered by object insertion into the map.
+ * </p>
* <p>
* From Commons Collections 3.2, this Collection can be cast
* to a list, see {@link #valueList()}
+ * </p>
*
* @see #valueList()
* @return the fully modifiable collection view over the values
diff --git a/src/main/java/org/apache/commons/collections4/map/MultiKeyMap.java
b/src/main/java/org/apache/commons/collections4/map/MultiKeyMap.java
index 76d330181..6d9e6e9b7 100644
--- a/src/main/java/org/apache/commons/collections4/map/MultiKeyMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/MultiKeyMap.java
@@ -684,6 +684,7 @@ public class MultiKeyMap<K, V> extends
AbstractMapDecorator<MultiKey<? extends K
* <p>
* This method removes all the mappings where the {@code MultiKey}
* has one or more keys, and the first matches that specified.
+ * </p>
*
* @param key1 the first key
* @return true if any elements were removed
@@ -707,6 +708,7 @@ public class MultiKeyMap<K, V> extends
AbstractMapDecorator<MultiKey<? extends K
* <p>
* This method removes all the mappings where the {@code MultiKey}
* has two or more keys, and the first two match those specified.
+ * </p>
*
* @param key1 the first key
* @param key2 the second key
@@ -732,6 +734,7 @@ public class MultiKeyMap<K, V> extends
AbstractMapDecorator<MultiKey<? extends K
* <p>
* This method removes all the mappings where the {@code MultiKey}
* has three or more keys, and the first three match those specified.
+ * </p>
*
* @param key1 the first key
* @param key2 the second key
@@ -759,6 +762,7 @@ public class MultiKeyMap<K, V> extends
AbstractMapDecorator<MultiKey<? extends K
* <p>
* This method removes all the mappings where the {@code MultiKey}
* has four or more keys, and the first four match those specified.
+ * </p>
*
* @param key1 the first key
* @param key2 the second key
diff --git
a/src/main/java/org/apache/commons/collections4/map/MultiValueMap.java
b/src/main/java/org/apache/commons/collections4/map/MultiValueMap.java
index 566ebea21..779d7a026 100644
--- a/src/main/java/org/apache/commons/collections4/map/MultiValueMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/MultiValueMap.java
@@ -273,6 +273,7 @@ public class MultiValueMap<K, V> extends
AbstractMapDecorator<K, Object> impleme
* Checks whether the map contains the value specified.
* <p>
* This checks all collections against all keys for the value, and thus
could be slow.
+ * </p>
*
* @param value the value to search for
* @return true if the map contains the value
@@ -312,6 +313,7 @@ public class MultiValueMap<K, V> extends
AbstractMapDecorator<K, Object> impleme
* <p>
* This method can be overridden to perform your own processing
* instead of using the factory.
+ * </p>
*
* @param size the collection size that is about to be added
* @return the new collection
@@ -323,9 +325,10 @@ public class MultiValueMap<K, V> extends
AbstractMapDecorator<K, Object> impleme
/**
* {@inheritDoc}
* <p>
- * NOTE: the returned Entry objects will contain as value a {@link
Collection}
+ * Note: the returned Entry objects will contain as value a {@link
Collection}
* of all values that are mapped to the given key. To get a "flattened"
version
* of all mappings contained in this map, use {@link #iterator()}.
+ * </p>
*
* @see #iterator()
*/
@@ -351,9 +354,11 @@ public class MultiValueMap<K, V> extends
AbstractMapDecorator<K, Object> impleme
* <p>
* The iterator will return multiple Entry objects with the same key
* if there are multiple values mapped to this key.
+ * </p>
* <p>
- * NOTE: calling {@link java.util.Map.Entry#setValue(Object)} on any of
the returned
+ * Note: calling {@link java.util.Map.Entry#setValue(Object)} on any of
the returned
* elements will result in a {@link UnsupportedOperationException}.
+ * </p>
*
* @return the iterator of all mappings in this map
* @since 4.0
@@ -408,6 +413,7 @@ public class MultiValueMap<K, V> extends
AbstractMapDecorator<K, Object> impleme
* <p>
* Unlike a normal {@code Map} the previous value is not replaced.
* Instead, the new value is added to the collection stored against the
key.
+ * </p>
*
* @param key the key to store against
* @param value the value to add to the collection at the key
@@ -468,6 +474,7 @@ public class MultiValueMap<K, V> extends
AbstractMapDecorator<K, Object> impleme
* added using {@code put(Object,Object)}.
* If you call this method with a multi map, each entry is
* added using {@code putAll(Object,Collection)}.
+ * </p>
*
* @param map the map to copy (either a normal or multi map)
*/
@@ -504,9 +511,11 @@ public class MultiValueMap<K, V> extends
AbstractMapDecorator<K, Object> impleme
* <p>
* The item is removed from the collection mapped to the specified key.
* Other values attached to that key are unaffected.
+ * </p>
* <p>
* If the last value for a key is removed, {@code null} will be returned
* from a subsequent {@code get(key)}.
+ * </p>
*
* @param key the key to remove from
* @param value the value to remove
@@ -559,6 +568,7 @@ public class MultiValueMap<K, V> extends
AbstractMapDecorator<K, Object> impleme
* Gets a collection containing all the values in the map.
* <p>
* This returns a collection containing the combination of values from all
keys.
+ * </p>
*
* @return a collection view of the values contained in this map
*/
diff --git
a/src/main/java/org/apache/commons/collections4/map/PassiveExpiringMap.java
b/src/main/java/org/apache/commons/collections4/map/PassiveExpiringMap.java
index 414b9bba3..fb0b0b5dd 100644
--- a/src/main/java/org/apache/commons/collections4/map/PassiveExpiringMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/PassiveExpiringMap.java
@@ -419,11 +419,12 @@ public class PassiveExpiringMap<K, V>
}
/**
- * Add the given key-value pair to this map as well as recording the
entry's expiration time based on
- * the current time in milliseconds and this map's {@link #expiringPolicy}.
- * <p>
- * {@inheritDoc}
- */
+ * {@inheritDoc}
+ * <p>
+ * Add the given key-value pair to this map as well as recording the
entry's expiration time based on the current time in milliseconds and this map's
+ * {@link #expiringPolicy}.
+ * </p>
+ */
@Override
public V put(final K key, final V value) {
// remove the previous record
diff --git
a/src/main/java/org/apache/commons/collections4/map/PredicatedMap.java
b/src/main/java/org/apache/commons/collections4/map/PredicatedMap.java
index 7e7f6455d..ae61ee807 100644
--- a/src/main/java/org/apache/commons/collections4/map/PredicatedMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/PredicatedMap.java
@@ -63,6 +63,7 @@ public class PredicatedMap<K, V>
* <p>
* If there are any elements already in the list being decorated, they
* are validated.
+ * </p>
*
* @param <K> the key type
* @param <V> the value type
diff --git
a/src/main/java/org/apache/commons/collections4/map/PredicatedSortedMap.java
b/src/main/java/org/apache/commons/collections4/map/PredicatedSortedMap.java
index 840ad4c96..f1a0f2c93 100644
--- a/src/main/java/org/apache/commons/collections4/map/PredicatedSortedMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/PredicatedSortedMap.java
@@ -63,6 +63,7 @@ public class PredicatedSortedMap<K, V> extends
PredicatedMap<K, V> implements So
* <p>
* If there are any elements already in the list being decorated, they
* are validated.
+ * </p>
*
* @param <K> the key type
* @param <V> the value type
diff --git
a/src/main/java/org/apache/commons/collections4/map/ReferenceIdentityMap.java
b/src/main/java/org/apache/commons/collections4/map/ReferenceIdentityMap.java
index 062ea2364..f56d04d2a 100644
---
a/src/main/java/org/apache/commons/collections4/map/ReferenceIdentityMap.java
+++
b/src/main/java/org/apache/commons/collections4/map/ReferenceIdentityMap.java
@@ -173,6 +173,7 @@ public class ReferenceIdentityMap<K, V> extends
AbstractReferenceMap<K, V> imple
* Gets the hash code for the key specified.
* <p>
* This implementation uses the identity hash code.
+ * </p>
*
* @param key the key to get a hash code for
* @return the hash code
@@ -186,6 +187,7 @@ public class ReferenceIdentityMap<K, V> extends
AbstractReferenceMap<K, V> imple
* Gets the hash code for a MapEntry.
* <p>
* This implementation uses the identity hash code.
+ * </p>
*
* @param key the key to get a hash code for, may be null
* @param value the value to get a hash code for, may be null
@@ -202,6 +204,7 @@ public class ReferenceIdentityMap<K, V> extends
AbstractReferenceMap<K, V> imple
* <p>
* This implementation converts the key from the entry to a real reference
* before comparison and uses {@code ==}.
+ * </p>
*
* @param key1 the first key to compare passed in from outside
* @param key2 the second key extracted from the entry via {@code
entry.key}
@@ -217,6 +220,7 @@ public class ReferenceIdentityMap<K, V> extends
AbstractReferenceMap<K, V> imple
* Compares two values for equals.
* <p>
* This implementation uses {@code ==}.
+ * </p>
*
* @param value1 the first value to compare passed in from outside
* @param value2 the second value extracted from the entry via {@code
getValue()}
diff --git
a/src/main/java/org/apache/commons/collections4/map/SingletonMap.java
b/src/main/java/org/apache/commons/collections4/map/SingletonMap.java
index 4922cfd7b..7dd8ef446 100644
--- a/src/main/java/org/apache/commons/collections4/map/SingletonMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/SingletonMap.java
@@ -488,6 +488,7 @@ public class SingletonMap<K, V>
* <p>
* An IllegalArgumentException is thrown if the key does not match as the
map
* is fixed size.
+ * </p>
*
* @param key the key to set, must be the key of the map
* @param value the value to set
@@ -508,6 +509,7 @@ public class SingletonMap<K, V>
* The map must be of size 0 or size 1.
* If it is size 1, the key must match the key of this map otherwise an
* IllegalArgumentException is thrown.
+ * </p>
*
* @param map the map to add, must be size 0 or 1, and the key must match
* @throws NullPointerException if the map is null
diff --git
a/src/main/java/org/apache/commons/collections4/map/StaticBucketMap.java
b/src/main/java/org/apache/commons/collections4/map/StaticBucketMap.java
index 861141280..a33af9c60 100644
--- a/src/main/java/org/apache/commons/collections4/map/StaticBucketMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/StaticBucketMap.java
@@ -383,21 +383,20 @@ public final class StaticBucketMap<K, V> extends
AbstractIterableMap<K, V> {
}
/**
- * Prevents any operations from occurring on this map while the
- * given {@link Runnable} executes. This method can be used, for
- * instance, to execute a bulk operation atomically:
- *
- * <pre>
- * staticBucketMapInstance.atomic(new Runnable() {
- * public void run() {
- * staticBucketMapInstance.putAll(map);
- * }
- * });
- * </pre>
- *
- * It can also be used if you need a reliable iterator:
+ * Prevents any operations from occurring on this map while the given
{@link Runnable} executes. This method can be used, for instance, to execute a
bulk
+ * operation atomically:
+ * <pre>
+ * staticBucketMapInstance.atomic(new Runnable() {
+ * public void run() {
+ * staticBucketMapInstance.putAll(map);
+ * }
+ * });
+ * </pre>
+ * <p>
+ * It can also be used if you need a reliable iterator:
+ * </p>
*
- * <pre>
+ * <pre>
* staticBucketMapInstance.atomic(new Runnable() {
* public void run() {
* Iterator iterator = staticBucketMapInstance.iterator();
@@ -406,15 +405,13 @@ public final class StaticBucketMap<K, V> extends
AbstractIterableMap<K, V> {
* }
* }
* });
- * </pre>
- *
- * <b>Implementation note:</b> This method requires a lot of time
- * and a ton of stack space. Essentially a recursive algorithm is used
- * to enter each bucket's monitor. If you have twenty thousand buckets
- * in your map, then the recursive method will be invoked twenty thousand
- * times. You have been warned.
+ * </pre>
+ * <p>
+ * <b>Implementation note:</b> This method requires a lot of time and a
ton of stack space. Essentially a recursive algorithm is used to enter each
bucket's
+ * monitor. If you have twenty thousand buckets in your map, then the
recursive method will be invoked twenty thousand times. You have been warned.
+ * </p>
*
- * @param runnable the code to execute atomically
+ * @param runnable the code to execute atomically
*/
public void atomic(final Runnable runnable) {
atomic(Objects.requireNonNull(runnable, "runnable"), 0);
diff --git
a/src/main/java/org/apache/commons/collections4/map/TransformedMap.java
b/src/main/java/org/apache/commons/collections4/map/TransformedMap.java
index f7e1768f2..ab6d28362 100644
--- a/src/main/java/org/apache/commons/collections4/map/TransformedMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/TransformedMap.java
@@ -63,6 +63,7 @@ public class TransformedMap<K, V>
* If there are any elements already in the map being decorated, they
* will be transformed by this method.
* Contrast this with {@link #transformingMap(Map, Transformer,
Transformer)}.
+ * </p>
*
* @param <K> the key type
* @param <V> the value type
@@ -90,6 +91,7 @@ public class TransformedMap<K, V>
* If there are any elements already in the map being decorated, they
* are NOT transformed.
* Contrast this with {@link #transformedMap(Map, Transformer,
Transformer)}.
+ * </p>
*
* @param <K> the key type
* @param <V> the value type
@@ -117,6 +119,7 @@ public class TransformedMap<K, V>
* <p>
* If there are any elements already in the collection being decorated,
they
* are NOT transformed.
+ * </p>
*
* @param map the map to decorate, must not be null
* @param keyTransformer the transformer to use for key conversion, null
means no conversion
@@ -199,6 +202,7 @@ public class TransformedMap<K, V>
* Transforms a map.
* <p>
* The transformer itself may throw an exception if necessary.
+ * </p>
*
* @param map the map to transform
* @return the transformed object
@@ -220,6 +224,7 @@ public class TransformedMap<K, V>
* Transforms a value.
* <p>
* The transformer itself may throw an exception if necessary.
+ * </p>
*
* @param object the object to transform
* @return the transformed object
diff --git
a/src/main/java/org/apache/commons/collections4/map/TransformedSortedMap.java
b/src/main/java/org/apache/commons/collections4/map/TransformedSortedMap.java
index 982b36fd8..fb5bdc891 100644
---
a/src/main/java/org/apache/commons/collections4/map/TransformedSortedMap.java
+++
b/src/main/java/org/apache/commons/collections4/map/TransformedSortedMap.java
@@ -59,6 +59,7 @@ public class TransformedSortedMap<K, V>
* If there are any elements already in the map being decorated, they
* will be transformed by this method.
* Contrast this with {@link #transformingSortedMap(SortedMap,
Transformer, Transformer)}.
+ * </p>
*
* @param <K> the key type
* @param <V> the value type
@@ -88,6 +89,7 @@ public class TransformedSortedMap<K, V>
* <p>
* If there are any elements already in the map being decorated, they are
NOT transformed.
* Contrast this with {@link #transformedSortedMap(SortedMap, Transformer,
Transformer)}.
+ * </p>
*
* @param <K> the key type
* @param <V> the value type
@@ -108,7 +110,8 @@ public class TransformedSortedMap<K, V>
* Constructor that wraps (not copies).
* <p>
* If there are any elements already in the collection being decorated,
they
- * are NOT transformed.</p>
+ * are NOT transformed.
+ * </p>
*
* @param map the map to decorate, must not be null
* @param keyTransformer the predicate to validate the keys, null means
no transformation
diff --git
a/src/main/java/org/apache/commons/collections4/multimap/AbstractListValuedMap.java
b/src/main/java/org/apache/commons/collections4/multimap/AbstractListValuedMap.java
index bae286526..52e144a35 100644
---
a/src/main/java/org/apache/commons/collections4/multimap/AbstractListValuedMap.java
+++
b/src/main/java/org/apache/commons/collections4/multimap/AbstractListValuedMap.java
@@ -269,6 +269,7 @@ public abstract class AbstractListValuedMap<K, V> extends
AbstractMultiValuedMap
* Removes all values associated with the specified key.
* <p>
* A subsequent {@code get(Object)} would return an empty list.
+ * </p>
*
* @param key the key to remove values from
* @return the {@code List} of values removed, will return an empty,
diff --git
a/src/main/java/org/apache/commons/collections4/multimap/AbstractSetValuedMap.java
b/src/main/java/org/apache/commons/collections4/multimap/AbstractSetValuedMap.java
index 6f11527f0..7f563bcdb 100644
---
a/src/main/java/org/apache/commons/collections4/multimap/AbstractSetValuedMap.java
+++
b/src/main/java/org/apache/commons/collections4/multimap/AbstractSetValuedMap.java
@@ -115,6 +115,7 @@ public abstract class AbstractSetValuedMap<K, V> extends
AbstractMultiValuedMap<
* Removes all values associated with the specified key.
* <p>
* A subsequent {@code get(Object)} would return an empty set.
+ * </p>
*
* @param key the key to remove values from
* @return the {@code Set} of values removed, will return an empty,
diff --git
a/src/main/java/org/apache/commons/collections4/multimap/TransformedMultiValuedMap.java
b/src/main/java/org/apache/commons/collections4/multimap/TransformedMultiValuedMap.java
index 03174edae..6094a46dd 100644
---
a/src/main/java/org/apache/commons/collections4/multimap/TransformedMultiValuedMap.java
+++
b/src/main/java/org/apache/commons/collections4/multimap/TransformedMultiValuedMap.java
@@ -53,6 +53,7 @@ public class TransformedMultiValuedMap<K, V> extends
AbstractMultiValuedMapDecor
* If there are any elements already in the map being decorated, they will
* be transformed by this method. Contrast this with
* {@link #transformingMap(MultiValuedMap, Transformer, Transformer)}.
+ * </p>
*
* @param <K> the key type
* @param <V> the value type
@@ -81,6 +82,7 @@ public class TransformedMultiValuedMap<K, V> extends
AbstractMultiValuedMapDecor
* If there are any elements already in the map being decorated, they are
* NOT transformed. Contrast this with
* {@link #transformedMap(MultiValuedMap, Transformer, Transformer)}.
+ * </p>
*
* @param <K> the key type
* @param <V> the value type
@@ -107,6 +109,7 @@ public class TransformedMultiValuedMap<K, V> extends
AbstractMultiValuedMapDecor
* <p>
* If there are any elements already in the collection being decorated,
they
* are NOT transformed.
+ * </p>
*
* @param map the MultiValuedMap to decorate, may not be null
* @param keyTransformer the transformer to use for key conversion, null
means no conversion
@@ -159,6 +162,7 @@ public class TransformedMultiValuedMap<K, V> extends
AbstractMultiValuedMapDecor
* Transforms a key.
* <p>
* The transformer itself may throw an exception if necessary.
+ * </p>
*
* @param object the object to transform
* @return the transformed object
@@ -174,6 +178,7 @@ public class TransformedMultiValuedMap<K, V> extends
AbstractMultiValuedMapDecor
* Transforms a value.
* <p>
* The transformer itself may throw an exception if necessary.
+ * </p>
*
* @param object the object to transform
* @return the transformed object
diff --git
a/src/main/java/org/apache/commons/collections4/multimap/UnmodifiableMultiValuedMap.java
b/src/main/java/org/apache/commons/collections4/multimap/UnmodifiableMultiValuedMap.java
index 4f9d9838f..537beea17 100644
---
a/src/main/java/org/apache/commons/collections4/multimap/UnmodifiableMultiValuedMap.java
+++
b/src/main/java/org/apache/commons/collections4/multimap/UnmodifiableMultiValuedMap.java
@@ -52,6 +52,7 @@ public final class UnmodifiableMultiValuedMap<K, V>
* Factory method to create an unmodifiable MultiValuedMap.
* <p>
* If the map passed in is already unmodifiable, it is returned.
+ * </p>
*
* @param <K> the type of key elements
* @param <V> the type of value elements
diff --git
a/src/main/java/org/apache/commons/collections4/multiset/AbstractMapMultiSet.java
b/src/main/java/org/apache/commons/collections4/multiset/AbstractMapMultiSet.java
index dfdfaedbd..815172756 100644
---
a/src/main/java/org/apache/commons/collections4/multiset/AbstractMapMultiSet.java
+++
b/src/main/java/org/apache/commons/collections4/multiset/AbstractMapMultiSet.java
@@ -484,7 +484,8 @@ public abstract class AbstractMapMultiSet<E> extends
AbstractMultiSet<E> {
/**
* Sets the map being wrapped.
* <p>
- * <b>NOTE:</b> this method should only be used during deserialization
+ * <b>Note:</b> this method should only be used during deserialization
+ * </p>
*
* @param map the map to wrap
*/
diff --git
a/src/main/java/org/apache/commons/collections4/multiset/PredicatedMultiSet.java
b/src/main/java/org/apache/commons/collections4/multiset/PredicatedMultiSet.java
index 3f2f4504c..89e7a657a 100644
---
a/src/main/java/org/apache/commons/collections4/multiset/PredicatedMultiSet.java
+++
b/src/main/java/org/apache/commons/collections4/multiset/PredicatedMultiSet.java
@@ -71,6 +71,7 @@ public class PredicatedMultiSet<E> extends
PredicatedCollection<E> implements Mu
* <p>
* If there are any elements already in the multiset being decorated, they
* are validated.
+ * </p>
*
* @param multiset the multiset to decorate, must not be null
* @param predicate the predicate to use for validation, must not be null
diff --git
a/src/main/java/org/apache/commons/collections4/multiset/UnmodifiableMultiSet.java
b/src/main/java/org/apache/commons/collections4/multiset/UnmodifiableMultiSet.java
index e593a0a1c..919c6ff65 100644
---
a/src/main/java/org/apache/commons/collections4/multiset/UnmodifiableMultiSet.java
+++
b/src/main/java/org/apache/commons/collections4/multiset/UnmodifiableMultiSet.java
@@ -48,6 +48,7 @@ public final class UnmodifiableMultiSet<E>
* Factory method to create an unmodifiable multiset.
* <p>
* If the multiset passed in is already unmodifiable, it is returned.
+ * </p>
*
* @param <E> the type of the elements in the multiset
* @param multiset the multiset to decorate, may not be null
