You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by gg...@apache.org on 2026/07/22 14:17:47 UTC
(commons-collections) branch master updated (fe8eb4989 -> 8a8d68813)
This is an automated email from the ASF dual-hosted git repository.
garydgregory pushed a change to branch master
in repository https://gitbox.apache.org/repos/asf/commons-collections.git
from fe8eb4989 Increment modCount after the bounds check in TreeList add and remove (#716)
new f1947d87c Increment modCount after the bounds check in TreeList add and remove (#716).
new 8a8d68813 Javadoc
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
src/changes/changes.xml | 1 +
.../java/org/apache/commons/collections4/Bag.java | 44 ++--
.../org/apache/commons/collections4/BidiMap.java | 111 ++++------
.../apache/commons/collections4/BoundedMap.java | 15 +-
.../org/apache/commons/collections4/Closure.java | 19 +-
.../org/apache/commons/collections4/Factory.java | 15 +-
.../java/org/apache/commons/collections4/Get.java | 20 +-
.../apache/commons/collections4/IterableGet.java | 2 +-
.../apache/commons/collections4/IterableMap.java | 4 +-
.../commons/collections4/IterableSortedMap.java | 4 +-
.../org/apache/commons/collections4/KeyValue.java | 15 +-
.../apache/commons/collections4/ListValuedMap.java | 33 ++-
.../apache/commons/collections4/MapIterator.java | 64 +++---
.../org/apache/commons/collections4/MultiMap.java | 118 +++++------
.../commons/collections4/MultiValuedMap.java | 225 +++++++++------------
.../commons/collections4/OrderedBidiMap.java | 25 +--
.../commons/collections4/OrderedIterator.java | 6 +-
.../apache/commons/collections4/OrderedMap.java | 30 ++-
.../commons/collections4/OrderedMapIterator.java | 8 +-
.../org/apache/commons/collections4/Predicate.java | 26 +--
.../java/org/apache/commons/collections4/Put.java | 30 ++-
.../commons/collections4/ResettableIterator.java | 5 +-
.../apache/commons/collections4/SetValuedMap.java | 33 ++-
.../org/apache/commons/collections4/SortedBag.java | 23 +--
.../apache/commons/collections4/SortedBidiMap.java | 22 +-
.../commons/collections4/SortedMultiSet.java | 6 +-
.../apache/commons/collections4/Transformer.java | 29 ++-
.../java/org/apache/commons/collections4/Trie.java | 10 +-
.../apache/commons/collections4/Unmodifiable.java | 11 +-
29 files changed, 413 insertions(+), 541 deletions(-)
(commons-collections) 01/02: Increment modCount after the bounds check in TreeList add and remove (#716).
Posted by gg...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
garydgregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-collections.git
commit f1947d87c7f3d7177e42a6cce49a3553374ed3c2
Author: Gary Gregory <ga...@gmail.com>
AuthorDate: Wed Jul 22 10:05:44 2026 -0400
Increment modCount after the bounds check in TreeList add and remove
(#716).
---
src/changes/changes.xml | 1 +
1 file changed, 1 insertion(+)
diff --git a/src/changes/changes.xml b/src/changes/changes.xml
index f208dafa6..63e91eaa0 100644
--- a/src/changes/changes.xml
+++ b/src/changes/changes.xml
@@ -83,6 +83,7 @@
<action type="fix" dev="ggregory" due-to="Naveed Khan, Gary Gregory">SetUniqueList and ListOrderedSet leave the backing collection inconsistent when add(int, Object) or addAll(int, Collection) is called with an out-of-range index.</action>
<action type="fix" dev="ggregory" due-to="Naveed Khan, Gary Gregory">CollectionUtils.collate(Iterable, Iterable, Comparator, boolean) does not remove duplicate null elements when includeDuplicates is false (#715).</action>
<action type="fix" dev="ggregory" due-to="Naveed Khan, Gary Gregory">Do not register a value collection until an add succeeds (#717).</action>
+ <action type="fix" dev="ggregory" due-to="Naveed Khan, Gary Gregory">Increment modCount after the bounds check in TreeList add and remove (#716).</action>
<!-- ADD -->
<action type="add" dev="ggregory" due-to="Gary Gregory">Add generics to UnmodifiableIterator for the wrapped type.</action>
<action type="add" dev="ggregory" due-to="Gary Gregory">Add a Maven benchmark profile for JMH.</action>
(commons-collections) 02/02: Javadoc
Posted by gg...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
garydgregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-collections.git
commit 8a8d68813575093e3075a419bf51987eade48486
Author: Gary Gregory <ga...@gmail.com>
AuthorDate: Wed Jul 22 10:17:41 2026 -0400
Javadoc
---
.../java/org/apache/commons/collections4/Bag.java | 44 ++--
.../org/apache/commons/collections4/BidiMap.java | 111 ++++------
.../apache/commons/collections4/BoundedMap.java | 15 +-
.../org/apache/commons/collections4/Closure.java | 19 +-
.../org/apache/commons/collections4/Factory.java | 15 +-
.../java/org/apache/commons/collections4/Get.java | 20 +-
.../apache/commons/collections4/IterableGet.java | 2 +-
.../apache/commons/collections4/IterableMap.java | 4 +-
.../commons/collections4/IterableSortedMap.java | 4 +-
.../org/apache/commons/collections4/KeyValue.java | 15 +-
.../apache/commons/collections4/ListValuedMap.java | 33 ++-
.../apache/commons/collections4/MapIterator.java | 64 +++---
.../org/apache/commons/collections4/MultiMap.java | 118 +++++------
.../commons/collections4/MultiValuedMap.java | 225 +++++++++------------
.../commons/collections4/OrderedBidiMap.java | 25 +--
.../commons/collections4/OrderedIterator.java | 6 +-
.../apache/commons/collections4/OrderedMap.java | 30 ++-
.../commons/collections4/OrderedMapIterator.java | 8 +-
.../org/apache/commons/collections4/Predicate.java | 26 +--
.../java/org/apache/commons/collections4/Put.java | 30 ++-
.../commons/collections4/ResettableIterator.java | 5 +-
.../apache/commons/collections4/SetValuedMap.java | 33 ++-
.../org/apache/commons/collections4/SortedBag.java | 23 +--
.../apache/commons/collections4/SortedBidiMap.java | 22 +-
.../commons/collections4/SortedMultiSet.java | 6 +-
.../apache/commons/collections4/Transformer.java | 29 ++-
.../java/org/apache/commons/collections4/Trie.java | 10 +-
.../apache/commons/collections4/Unmodifiable.java | 11 +-
28 files changed, 412 insertions(+), 541 deletions(-)
diff --git a/src/main/java/org/apache/commons/collections4/Bag.java b/src/main/java/org/apache/commons/collections4/Bag.java
index 89844bedd..7105db142 100644
--- a/src/main/java/org/apache/commons/collections4/Bag.java
+++ b/src/main/java/org/apache/commons/collections4/Bag.java
@@ -89,8 +89,8 @@ public interface Bag<E> extends Collection<E> {
* {@code false}, this method violates the contract.
* </p>
*
- * @param object The object to add
- * @return {@code true} if the object was not already in the {@code uniqueSet}
+ * @param object The object to add.
+ * @return {@code true} if the object was not already in the {@code uniqueSet}.
*/
@Override
boolean add(E object);
@@ -103,10 +103,10 @@ public interface Bag<E> extends Collection<E> {
* {@link #uniqueSet()} and report its count as {@code nCopies}.
* </p>
*
- * @param object The object to add
- * @param nCopies The number of copies to add
- * @return {@code true} if the object was not already in the {@code uniqueSet}
- * @throws ClassCastException if the class of the specified element prevents it from being added to this collection
+ * @param object The object to add.
+ * @param nCopies The number of copies to add.
+ * @return {@code true} if the object was not already in the {@code uniqueSet}.
+ * @throws ClassCastException if the class of the specified element prevents it from being added to this collection.
*/
boolean add(E object, int nCopies);
@@ -125,8 +125,8 @@ public interface Bag<E> extends Collection<E> {
* in the given collection.
* </p>
*
- * @param coll The collection to check against
- * @return {@code true} if the Bag contains all the collection
+ * @param coll The collection to check against.
+ * @return {@code true} if the Bag contains all the collection.
*/
@Override
boolean containsAll(Collection<?> coll);
@@ -136,8 +136,8 @@ public interface Bag<E> extends Collection<E> {
* object currently in the bag. If the object does not exist in the
* bag, return 0.
*
- * @param object The object to search for
- * @return The number of occurrences of the object, zero if not found
+ * @param object The object to search for.
+ * @return The number of occurrences of the object, zero if not found.
*/
int getCount(Object object);
@@ -146,7 +146,7 @@ public interface Bag<E> extends Collection<E> {
* including copies due to cardinality. This iterator is fail-fast
* and will not tolerate concurrent modifications.
*
- * @return iterator over all elements in the Bag
+ * @return iterator over all elements in the Bag.
*/
@Override
Iterator<E> iterator();
@@ -163,8 +163,8 @@ public interface Bag<E> extends Collection<E> {
* given object, not <em>all</em> occurrences.
* </p>
*
- * @param object The object to remove
- * @return {@code true} if this call changed the collection
+ * @param object The object to remove.
+ * @return {@code true} if this call changed the collection.
*/
@Override
boolean remove(Object object);
@@ -176,9 +176,9 @@ public interface Bag<E> extends Collection<E> {
* copies in the Bag, no error is thrown.
* </p>
*
- * @param object The object to remove
- * @param nCopies The number of copies to remove
- * @return {@code true} if this call changed the collection
+ * @param object The object to remove.
+ * @param nCopies The number of copies to remove.
+ * @return {@code true} if this call changed the collection.
*/
boolean remove(Object object, int nCopies);
@@ -197,8 +197,8 @@ public interface Bag<E> extends Collection<E> {
* given collection.
* </p>
*
- * @param coll The collection to remove
- * @return {@code true} if this call changed the collection
+ * @param coll The collection to remove.
+ * @return {@code true} if this call changed the collection.
*/
@Override
boolean removeAll(Collection<?> coll);
@@ -221,8 +221,8 @@ public interface Bag<E> extends Collection<E> {
* given collection.
* </p>
*
- * @param coll The collection to retain
- * @return {@code true} if this call changed the collection
+ * @param coll The collection to retain.
+ * @return {@code true} if this call changed the collection.
*/
@Override
boolean retainAll(Collection<?> coll);
@@ -230,7 +230,7 @@ public interface Bag<E> extends Collection<E> {
/**
* Returns the total number of items in the bag across all types.
*
- * @return The total size of the Bag
+ * @return The total size of the Bag.
*/
@Override
int size();
@@ -241,7 +241,7 @@ public interface Bag<E> extends Collection<E> {
* Uniqueness constraints are the same as those in {@link Set}.
* </p>
*
- * @return The Set of unique Bag elements
+ * @return The Set of unique Bag elements.
*/
Set<E> uniqueSet();
diff --git a/src/main/java/org/apache/commons/collections4/BidiMap.java b/src/main/java/org/apache/commons/collections4/BidiMap.java
index 87158e54b..80d5cb88d 100644
--- a/src/main/java/org/apache/commons/collections4/BidiMap.java
+++ b/src/main/java/org/apache/commons/collections4/BidiMap.java
@@ -14,6 +14,7 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
+
package org.apache.commons.collections4;
import java.util.Set;
@@ -21,21 +22,16 @@ import java.util.Set;
/**
* Defines a map that allows bidirectional lookup between key and values.
* <p>
- * This extended {@code Map} represents a mapping where a key may
- * lookup a value and a value may lookup a key with equal ease.
- * This interface extends {@code Map} and so may be used anywhere a map
- * is required. The interface provides an inverse map view, enabling
- * full access to both directions of the {@code BidiMap}.
+ * This extended {@code Map} represents a mapping where a key may lookup a value and a value may lookup a key with equal ease. This interface extends
+ * {@code Map} and so may be used anywhere a map is required. The interface provides an inverse map view, enabling full access to both directions of the
+ * {@code BidiMap}.
* </p>
* <p>
- * Implementations should allow a value to be looked up from a key and
- * a key to be looked up from a value with equal performance.
+ * Implementations should allow a value to be looked up from a key and a key to be looked up from a value with equal performance.
* </p>
* <p>
- * This map enforces the restriction that there is a 1:1 relation between
- * keys and values, meaning that multiple keys cannot map to the same value.
- * This is required so that "inverting" the map results in a map without
- * duplicate keys. See the {@link #put} method description for more information.
+ * This map enforces the restriction that there is a 1:1 relation between keys and values, meaning that multiple keys cannot map to the same value. This is
+ * required so that "inverting" the map results in a map without duplicate keys. See the {@link #put} method description for more information.
* </p>
*
* @param <K> The type of the keys in the map
@@ -50,29 +46,24 @@ public interface BidiMap<K, V> extends IterableMap<K, V> {
* If the value is not contained in the map, {@code null} is returned.
* </p>
* <p>
- * Implementations should seek to make this method perform equally as well
- * as {@code get(Object)}.
+ * Implementations should seek to make this method perform equally as well as {@code get(Object)}.
* </p>
*
- * @param value The value to find the key for
- * @return The mapped key, or {@code null} if not found
- * @throws ClassCastException (optional) if the map limits the type of the
- * value and the specified value is inappropriate
- * @throws NullPointerException (optional) if the map limits the values to
- * non-null and null was specified
+ * @param value The value to find the key for.
+ * @return The mapped key, or {@code null} if not found.
+ * @throws ClassCastException (optional) if the map limits the type of the value and the specified value is inappropriate.
+ * @throws NullPointerException (optional) if the map limits the values to non-null and null was specified.
*/
K getKey(Object value);
/**
* Gets a view of this map where the keys and values are reversed.
* <p>
- * Changes to one map will be visible in the other and vice versa.
- * This enables both directions of the map to be accessed as a {@code Map}.
+ * Changes to one map will be visible in the other and vice versa. This enables both directions of the map to be accessed as a {@code Map}.
* </p>
* <p>
- * Implementations should seek to avoid creating a new object every time this
- * method is called. See {@code AbstractMap.values()} etc. Calling this
- * method on the inverse map should return the original.
+ * Implementations should seek to avoid creating a new object every time this method is called. See {@code AbstractMap.values()} etc. Calling this method on
+ * the inverse map should return the original.
* </p>
*
* @return An inverted bidirectional map
@@ -82,69 +73,55 @@ public interface BidiMap<K, V> extends IterableMap<K, V> {
/**
* Puts the key-value pair into the map, replacing any previous pair.
* <p>
- * When adding a key-value pair, the value may already exist in the map
- * against a different key. That mapping is removed, to ensure that the
- * value only occurs once in the inverse map.
+ * When adding a key-value pair, the value may already exist in the map against a different key. That mapping is removed, to ensure that the value only
+ * occurs once in the inverse map.
* </p>
- * <pre>
- * BidiMap map1 = new DualHashBidiMap();
- * map.put("A","B"); // contains A mapped to B, as per Map
- * map.put("A","C"); // contains A mapped to C, as per Map
*
- * BidiMap map2 = new DualHashBidiMap();
- * map.put("A","B"); // contains A mapped to B, as per Map
- * map.put("C","B"); // contains C mapped to B, key A is removed
+ * <pre>
+ * BidiMap map1 = new DualHashBidiMap();
+ * map.put("A", "B"); // contains A mapped to B, as per Map
+ * map.put("A", "C"); // contains A mapped to C, as per Map
+ * BidiMap map2 = new DualHashBidiMap();
+ * map.put("A", "B"); // contains A mapped to B, as per Map
+ * map.put("C", "B"); // contains C mapped to B, key A is removed
* </pre>
*
- * @param key The key to store
- * @param value The value to store
- * @return The previous value mapped to this key
- * @throws UnsupportedOperationException if the {@code put} method is not supported
- * @throws ClassCastException (optional) if the map limits the type of the
- * value and the specified value is inappropriate
- * @throws IllegalArgumentException (optional) if the map limits the values
- * in some way and the value was invalid
- * @throws NullPointerException (optional) if the map limits the values to
- * non-null and null was specified
+ * @param key The key to store.
+ * @param value The value to store.
+ * @return The previous value mapped to this key.
+ * @throws UnsupportedOperationException if the {@code put} method is not supported.
+ * @throws ClassCastException (optional) if the map limits the type of the value and the specified value is inappropriate.
+ * @throws IllegalArgumentException (optional) if the map limits the values in some way and the value was invalid.
+ * @throws NullPointerException (optional) if the map limits the values to non-null and null was specified.
*/
@Override
V put(K key, V value);
/**
- * Removes the key-value pair that is currently mapped to the specified
- * value (optional operation).
+ * Removes the key-value pair that is currently mapped to the specified value (optional operation).
* <p>
* If the value is not contained in the map, {@code null} is returned.
* </p>
* <p>
- * Implementations should seek to make this method perform equally as well
- * as {@code remove(Object)}.
+ * Implementations should seek to make this method perform equally as well as {@code remove(Object)}.
* </p>
*
- * @param value The value to find the key-value pair for
- * @return The key that was removed, {@code null} if nothing removed
- * @throws ClassCastException (optional) if the map limits the type of the
- * value and the specified value is inappropriate
- * @throws NullPointerException (optional) if the map limits the values to
- * non-null and null was specified
- * @throws UnsupportedOperationException if this method is not supported
- * by the implementation
+ * @param value The value to find the key-value pair for.
+ * @return The key that was removed, {@code null} if nothing removed.
+ * @throws ClassCastException (optional) if the map limits the type of the value and the specified value is inappropriate.
+ * @throws NullPointerException (optional) if the map limits the values to non-null and null was specified.
+ * @throws UnsupportedOperationException if this method is not supported by the implementation.
*/
K removeValue(Object value);
/**
- * Returns a {@link Set} view of the values contained in this map.
- * The set is backed by the map, so changes to the map are reflected
- * in the set, and vice-versa. If the map is modified while an iteration
- * over the set is in progress (except through the iterator's own
- * {@code remove} operation), the results of the iteration are undefined.
- * The set supports element removal, which removes the corresponding
- * mapping from the map, via the {@code Iterator.remove},
- * {@code Collection.remove}, {@code removeAll},
- * {@code retainAll} and {@code clear} operations. It does not
- * support the {@code add} or {@code addAll} operations.
+ * Returns a {@link Set} view of the values contained in this map. The set is backed by the map, so changes to the map are reflected in the set, and
+ * vice-versa. If the map is modified while an iteration over the set is in progress (except through the iterator's own {@code remove} operation), the
+ * results of the iteration are undefined. The set supports element removal, which removes the corresponding mapping from the map, via the
+ * {@code Iterator.remove}, {@code Collection.remove}, {@code removeAll}, {@code retainAll} and {@code clear} operations. It does not support the
+ * {@code add} or {@code addAll} operations.
*
- * @return A set view of the values contained in this map
+ * @return A set view of the values contained in this map.
*/
@Override
Set<V> values();
diff --git a/src/main/java/org/apache/commons/collections4/BoundedMap.java b/src/main/java/org/apache/commons/collections4/BoundedMap.java
index 935f731f1..39870a07d 100644
--- a/src/main/java/org/apache/commons/collections4/BoundedMap.java
+++ b/src/main/java/org/apache/commons/collections4/BoundedMap.java
@@ -14,18 +14,18 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
+
package org.apache.commons.collections4;
/**
* Defines a map that is bounded in size.
* <p>
- * The size of the map can vary, but it can never exceed a preset
- * maximum number of elements. This interface allows the querying of details
- * associated with the maximum number of elements.
+ * The size of the map can vary, but it can never exceed a preset maximum number of elements. This interface allows the querying of details associated with the
+ * maximum number of elements.
* </p>
*
- * @param <K> The type of the keys in this map
- * @param <V> The type of the values in this map
+ * @param <K> The type of the keys in this map.
+ * @param <V> The type of the values in this map.
* @since 3.0
*/
public interface BoundedMap<K, V> extends IterableMap<K, V> {
@@ -33,15 +33,14 @@ public interface BoundedMap<K, V> extends IterableMap<K, V> {
/**
* Returns true if this map is full and no new elements can be added.
*
- * @return {@code true} if the map is full
+ * @return {@code true} if the map is full.
*/
boolean isFull();
/**
* Gets the maximum size of the map (the bound).
*
- * @return The maximum number of elements the map can hold
+ * @return The maximum number of elements the map can hold.
*/
int maxSize();
-
}
diff --git a/src/main/java/org/apache/commons/collections4/Closure.java b/src/main/java/org/apache/commons/collections4/Closure.java
index 925cf681c..0cd6289f4 100644
--- a/src/main/java/org/apache/commons/collections4/Closure.java
+++ b/src/main/java/org/apache/commons/collections4/Closure.java
@@ -14,6 +14,7 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
+
package org.apache.commons.collections4;
import java.util.function.Consumer;
@@ -22,17 +23,14 @@ import java.util.function.Supplier;
/**
* Defines a functor interface implemented by classes that do something.
* <p>
- * A {@code Closure} represents a block of code which is executed from
- * inside some block, function or iteration. It operates an input object.
+ * A {@code Closure} represents a block of code which is executed from inside some block, function or iteration. It operates an input object.
* </p>
* <p>
- * Standard implementations of common closures are provided by
- * {@link ClosureUtils}. These include method invocation and for/while loops.
+ * Standard implementations of common closures are provided by {@link ClosureUtils}. These include method invocation and for/while loops.
* </p>
*
* @param <T> The type of the input to the operation.
- * @since 1.0
- * This will be deprecated in 5.0 in favor of {@link Supplier}.
+ * @since 1.0 This will be deprecated in 5.0 in favor of {@link Supplier}.
*/
//@Deprecated
public interface Closure<T> extends Consumer<T> {
@@ -45,11 +43,10 @@ public interface Closure<T> extends Consumer<T> {
/**
* Performs an action on the specified input object.
*
- * @param input The input to execute on
- * @throws ClassCastException (runtime) if the input is the wrong class
- * @throws IllegalArgumentException (runtime) if the input is invalid
- * @throws FunctorException (runtime) if any other error occurs
+ * @param input The input to execute on.
+ * @throws ClassCastException (runtime) if the input is the wrong class.
+ * @throws IllegalArgumentException (runtime) if the input is invalid.
+ * @throws FunctorException (runtime) if any other error occurs.
*/
void execute(T input);
-
}
diff --git a/src/main/java/org/apache/commons/collections4/Factory.java b/src/main/java/org/apache/commons/collections4/Factory.java
index 1d9ac3fc7..2ee42ba2d 100644
--- a/src/main/java/org/apache/commons/collections4/Factory.java
+++ b/src/main/java/org/apache/commons/collections4/Factory.java
@@ -14,6 +14,7 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
+
package org.apache.commons.collections4;
import java.util.function.Supplier;
@@ -21,18 +22,15 @@ import java.util.function.Supplier;
/**
* Defines a functor interface implemented by classes that create objects.
* <p>
- * A {@code Factory} creates an object without using an input parameter.
- * If an input parameter is required, then {@link Transformer} is more appropriate.
+ * A {@code Factory} creates an object without using an input parameter. If an input parameter is required, then {@link Transformer} is more appropriate.
* </p>
* <p>
- * Standard implementations of common factories are provided by
- * {@link FactoryUtils}. These include factories that return a constant,
- * a copy of a prototype or a new instance.
+ * Standard implementations of common factories are provided by {@link FactoryUtils}. These include factories that return a constant, a copy of a prototype or a
+ * new instance.
* </p>
*
* @param <T> The type of results supplied by this supplier.
- * @since 2.1
- * This will be deprecated in 5.0 in favor of {@link Supplier}.
+ * @since 2.1 This will be deprecated in 5.0 in favor of {@link Supplier}.
*/
//@Deprecated
public interface Factory<T> extends Supplier<T> {
@@ -41,7 +39,7 @@ public interface Factory<T> extends Supplier<T> {
* Create a new object.
*
* @return A new object
- * @throws FunctorException (runtime) if the factory cannot create an object
+ * @throws FunctorException (runtime) if the factory cannot create an object.
*/
T create();
@@ -49,5 +47,4 @@ public interface Factory<T> extends Supplier<T> {
default T get() {
return create();
}
-
}
diff --git a/src/main/java/org/apache/commons/collections4/Get.java b/src/main/java/org/apache/commons/collections4/Get.java
index f3473bd2a..33a16bcfc 100644
--- a/src/main/java/org/apache/commons/collections4/Get.java
+++ b/src/main/java/org/apache/commons/collections4/Get.java
@@ -14,6 +14,7 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
+
package org.apache.commons.collections4;
import java.util.Collection;
@@ -33,8 +34,8 @@ public interface Get<K, V> {
/**
* Tests for presence of a given key.
*
- * @param key key whose presence in this map is to be tested
- * @return {@code true} if this map contains a mapping for the specified key
+ * @param key key whose presence in this map is to be tested.
+ * @return {@code true} if this map contains a mapping for the specified key.
* @see Map#containsKey(Object)
*/
boolean containsKey(Object key);
@@ -42,8 +43,8 @@ public interface Get<K, V> {
/**
* Tests for presence of a given value.
*
- * @param value value whose presence in this map is to be tested
- * @return {@code true} if this map maps one or more keys to the specified value
+ * @param value value whose presence in this map is to be tested.
+ * @return {@code true} if this map maps one or more keys to the specified value.
* @see Map#containsValue(Object)
*/
boolean containsValue(Object value);
@@ -59,8 +60,8 @@ public interface Get<K, V> {
/**
* Gets a value at a given key.
*
- * @param key The key whose associated value is to be returned
- * @return The value to which the specified key is mapped, or {@code null} if this map contains no mapping for the key
+ * @param key The key whose associated value is to be returned.
+ * @return The value to which the specified key is mapped, or {@code null} if this map contains no mapping for the key.
* @see Map#get(Object)
*/
V get(Object key);
@@ -68,7 +69,7 @@ public interface Get<K, V> {
/**
* Tests whether this instance contains any key-value mappings.
*
- * @return {@code true} if this map contains no key-value mappings
+ * @return {@code true} if this map contains no key-value mappings.
* @see Map#isEmpty()
*/
boolean isEmpty();
@@ -76,7 +77,7 @@ public interface Get<K, V> {
/**
* Gets a view of the keys contained in this map.
*
- * @return A set view of the keys contained in this map
+ * @return A set view of the keys contained in this map.
* @see Map#keySet()
*/
Set<K> keySet();
@@ -84,7 +85,7 @@ public interface Get<K, V> {
/**
* Remove a key-value mappings.
*
- * @param key key whose mapping is to be removed from the map
+ * @param key key whose mapping is to be removed from the map.
* @return The previous value associated with {@code key}, or {@code null} if there was no mapping for {@code key}.
* @see Map#remove(Object)
*/
@@ -105,5 +106,4 @@ public interface Get<K, V> {
* @see Map#values()
*/
Collection<V> values();
-
}
diff --git a/src/main/java/org/apache/commons/collections4/IterableGet.java b/src/main/java/org/apache/commons/collections4/IterableGet.java
index 3826811b8..190a51de4 100644
--- a/src/main/java/org/apache/commons/collections4/IterableGet.java
+++ b/src/main/java/org/apache/commons/collections4/IterableGet.java
@@ -43,7 +43,7 @@ public interface IterableGet<K, V> extends Get<K, V> {
* }
* </pre>
*
- * @return A map iterator
+ * @return A map iterator.
*/
MapIterator<K, V> mapIterator();
diff --git a/src/main/java/org/apache/commons/collections4/IterableMap.java b/src/main/java/org/apache/commons/collections4/IterableMap.java
index cccf67b00..60ff283fd 100644
--- a/src/main/java/org/apache/commons/collections4/IterableMap.java
+++ b/src/main/java/org/apache/commons/collections4/IterableMap.java
@@ -34,8 +34,8 @@ import java.util.Map;
* }
* </pre>
*
- * @param <K> The type of the keys in this map
- * @param <V> The type of the values in this map
+ * @param <K> The type of the keys in this map.
+ * @param <V> The type of the values in this map.
* @since 3.0
*/
public interface IterableMap<K, V> extends Map<K, V>, Put<K, V>, IterableGet<K, V> {
diff --git a/src/main/java/org/apache/commons/collections4/IterableSortedMap.java b/src/main/java/org/apache/commons/collections4/IterableSortedMap.java
index 59adbe6cd..28c260e72 100644
--- a/src/main/java/org/apache/commons/collections4/IterableSortedMap.java
+++ b/src/main/java/org/apache/commons/collections4/IterableSortedMap.java
@@ -21,8 +21,8 @@ import java.util.SortedMap;
/**
* {@link SortedMap} + {@link OrderedMap}.
*
- * @param <K> The type of the keys in the map
- * @param <V> The type of the values in the map
+ * @param <K> The type of the keys in the map.
+ * @param <V> The type of the values in the map.
* @since 4.0
*/
public interface IterableSortedMap<K, V> extends SortedMap<K, V>, OrderedMap<K, V> {
diff --git a/src/main/java/org/apache/commons/collections4/KeyValue.java b/src/main/java/org/apache/commons/collections4/KeyValue.java
index 00db82e3f..877748470 100644
--- a/src/main/java/org/apache/commons/collections4/KeyValue.java
+++ b/src/main/java/org/apache/commons/collections4/KeyValue.java
@@ -14,18 +14,18 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
+
package org.apache.commons.collections4;
/**
* Defines a simple key value pair.
* <p>
- * A Map Entry has considerable additional semantics over and above a simple
- * key-value pair. This interface defines the minimum key value, with just the
- * two get methods.
+ * A Map Entry has considerable additional semantics over and above a simple key-value pair. This interface defines the minimum key value, with just the two get
+ * methods.
* </p>
*
- * @param <K> The type of the key
- * @param <V> The type of the value
+ * @param <K> The type of the key.
+ * @param <V> The type of the value.
* @since 3.0
*/
public interface KeyValue<K, V> {
@@ -33,15 +33,14 @@ public interface KeyValue<K, V> {
/**
* Gets the key from the pair.
*
- * @return The key
+ * @return The key.
*/
K getKey();
/**
* Gets the value from the pair.
*
- * @return The value
+ * @return The value.
*/
V getValue();
-
}
diff --git a/src/main/java/org/apache/commons/collections4/ListValuedMap.java b/src/main/java/org/apache/commons/collections4/ListValuedMap.java
index 0e3759829..8fbd4853d 100644
--- a/src/main/java/org/apache/commons/collections4/ListValuedMap.java
+++ b/src/main/java/org/apache/commons/collections4/ListValuedMap.java
@@ -14,6 +14,7 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
+
package org.apache.commons.collections4;
import java.util.List;
@@ -24,8 +25,8 @@ import java.util.List;
* A {@code ListValuedMap} is a Map with slightly different semantics:
* </p>
* <ul>
- * <li>Putting a value into the map will add the value to a {@link List} at that key.</li>
- * <li>Getting a value will return a {@link List}, holding all the values put to that key.</li>
+ * <li>Putting a value into the map will add the value to a {@link List} at that key.</li>
+ * <li>Getting a value will return a {@link List}, holding all the values put to that key.</li>
* </ul>
*
* @param <K> The type of the keys in this map
@@ -37,16 +38,13 @@ public interface ListValuedMap<K, V> extends MultiValuedMap<K, V> {
/**
* Gets the list of values associated with the specified key.
* <p>
- * This method will return an <strong>empty</strong> list if
- * {@link #containsKey(Object)} returns {@code false}. Changes to the
- * returned list will update the underlying {@code ListValuedMap} and
- * vice-versa.
+ * This method will return an <strong>empty</strong> list if {@link #containsKey(Object)} returns {@code false}. Changes to the returned list will update
+ * the underlying {@code ListValuedMap} and vice-versa.
* </p>
*
- * @param key The key to retrieve
- * @return The {@code List} of values, implementations should return an
- * empty {@code List} for no mapping
- * @throws NullPointerException if the key is null and null keys are invalid
+ * @param key The key to retrieve.
+ * @return The {@code List} of values, implementations should return an empty {@code List} for no mapping.
+ * @throws NullPointerException if the key is null and null keys are invalid.
*/
@Override
List<V> get(K key);
@@ -54,18 +52,15 @@ public interface ListValuedMap<K, V> extends MultiValuedMap<K, V> {
/**
* Removes all values associated with the specified key.
* <p>
- * The returned list <em>may</em> be modifiable, but updates will not be
- * propagated to this list-valued map. In case no mapping was stored for the
- * specified key, an empty, unmodifiable list will be returned.
+ * The returned list <em>may</em> be modifiable, but updates will not be propagated to this list-valued map. In case no mapping was stored for the specified
+ * key, an empty, unmodifiable list will be returned.
* </p>
*
- * @param key The key to remove values from
- * @return The {@code List} of values removed, implementations
- * typically return an empty, unmodifiable {@code List} for no mapping found
- * @throws UnsupportedOperationException if the map is unmodifiable
- * @throws NullPointerException if the key is null and null keys are invalid
+ * @param key The key to remove values from.
+ * @return The {@code List} of values removed, implementations typically return an empty, unmodifiable {@code List} for no mapping found.
+ * @throws UnsupportedOperationException if the map is unmodifiable.
+ * @throws NullPointerException if the key is null and null keys are invalid.
*/
@Override
List<V> remove(Object key);
-
}
diff --git a/src/main/java/org/apache/commons/collections4/MapIterator.java b/src/main/java/org/apache/commons/collections4/MapIterator.java
index 788c193d6..af830c908 100644
--- a/src/main/java/org/apache/commons/collections4/MapIterator.java
+++ b/src/main/java/org/apache/commons/collections4/MapIterator.java
@@ -14,6 +14,7 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
+
package org.apache.commons.collections4;
import java.util.Iterator;
@@ -21,49 +22,45 @@ import java.util.Iterator;
/**
* Defines an iterator that operates over a {@code Map}.
* <p>
- * This iterator is a special version designed for maps. It can be more
- * efficient to use this rather than an entry set iterator where the option
- * is available, and it is certainly more convenient.
+ * This iterator is a special version designed for maps. It can be more efficient to use this rather than an entry set iterator where the option is available,
+ * and it is certainly more convenient.
* </p>
* <p>
- * A map that provides this interface may not hold the data internally using
- * Map Entry objects, thus this interface can avoid lots of object creation.
+ * A map that provides this interface may not hold the data internally using Map Entry objects, thus this interface can avoid lots of object creation.
* </p>
* <p>
- * In use, this iterator iterates through the keys in the map. After each call
- * to {@code next()}, the {@code getValue()} method provides direct
- * access to the value. The value can also be set using {@code setValue()}.
+ * In use, this iterator iterates through the keys in the map. After each call to {@code next()}, the {@code getValue()} method provides direct access to the
+ * value. The value can also be set using {@code setValue()}.
* </p>
+ *
* <pre>{@code
- * MapIterator<String,Integer> it = map.mapIterator();
+ * MapIterator<String, Integer> it = map.mapIterator();
* while (it.hasNext()) {
- * String key = it.next();
- * Integer value = it.getValue();
- * it.setValue(value + 1);
+ * String key = it.next();
+ * Integer value = it.getValue();
+ * it.setValue(value + 1);
* }
* }</pre>
*
- * @param <K> The type of the keys in the map
- * @param <V> The type of the values in the map
+ * @param <K> The type of the keys in the map.
+ * @param <V> The type of the values in the map.
* @since 3.0
*/
public interface MapIterator<K, V> extends Iterator<K> {
/**
- * Gets the current key, which is the key returned by the last call
- * to {@code next()}.
+ * Gets the current key, which is the key returned by the last call to {@code next()}.
*
- * @return The current key
- * @throws IllegalStateException if {@code next()} has not yet been called
+ * @return The current key.
+ * @throws IllegalStateException if {@code next()} has not yet been called.
*/
K getKey();
/**
- * Gets the current value, which is the value associated with the last key
- * returned by {@code next()}.
+ * Gets the current value, which is the value associated with the last key returned by {@code next()}.
*
- * @return The current value
- * @throws IllegalStateException if {@code next()} has not yet been called
+ * @return The current value.
+ * @throws IllegalStateException if {@code next()} has not yet been called.
*/
V getValue();
@@ -78,8 +75,8 @@ public interface MapIterator<K, V> extends Iterator<K> {
/**
* Gets the next <em>key</em> from the {@code Map}.
*
- * @return The next key in the iteration
- * @throws java.util.NoSuchElementException if the iteration is finished
+ * @return The next key in the iteration.
+ * @throws java.util.NoSuchElementException if the iteration is finished.
*/
@Override
K next();
@@ -90,10 +87,9 @@ public interface MapIterator<K, V> extends Iterator<K> {
* This method can be called once per call to {@code next()}.
* </p>
*
- * @throws UnsupportedOperationException if remove is not supported by the map
- * @throws IllegalStateException if {@code next()} has not yet been called
- * @throws IllegalStateException if {@code remove()} has already been called
- * since the last call to {@code next()}
+ * @throws UnsupportedOperationException if remove is not supported by the map.
+ * @throws IllegalStateException if {@code next()} has not yet been called.
+ * @throws IllegalStateException if {@code remove()} has already been called since the last call to {@code next()}.
*/
@Override
void remove();
@@ -101,13 +97,11 @@ public interface MapIterator<K, V> extends Iterator<K> {
/**
* Sets the value associated with the current key (optional operation).
*
- * @param value The new value
- * @return The previous value
- * @throws UnsupportedOperationException if setValue is not supported by the map
- * @throws IllegalStateException if {@code next()} has not yet been called
- * @throws IllegalStateException if {@code remove()} has been called since the
- * last call to {@code next()}
+ * @param value The new value.
+ * @return The previous value.
+ * @throws UnsupportedOperationException if setValue is not supported by the map.
+ * @throws IllegalStateException if {@code next()} has not yet been called.
+ * @throws IllegalStateException if {@code remove()} has been called since the last call to {@code next()}.
*/
V setValue(V value);
-
}
diff --git a/src/main/java/org/apache/commons/collections4/MultiMap.java b/src/main/java/org/apache/commons/collections4/MultiMap.java
index d1801912e..505cc9aaa 100644
--- a/src/main/java/org/apache/commons/collections4/MultiMap.java
+++ b/src/main/java/org/apache/commons/collections4/MultiMap.java
@@ -14,6 +14,7 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
+
package org.apache.commons.collections4;
import java.util.Collection;
@@ -21,30 +22,30 @@ import java.util.Collection;
/**
* Defines a map that holds a collection of values against each key.
* <p>
- * A {@code MultiMap} is a Map with slightly different semantics.
- * Putting a value into the map will add the value to a Collection at that key.
- * Getting a value will return a Collection, holding all the values put to that key.
+ * A {@code MultiMap} is a Map with slightly different semantics. Putting a value into the map will add the value to a Collection at that key. Getting a value
+ * will return a Collection, holding all the values put to that key.
* </p>
* <p>
* For example:
* </p>
+ *
* <pre>
* MultiMap mhm = new MultiValueMap();
* mhm.put(key, "A");
* mhm.put(key, "B");
* mhm.put(key, "C");
- * Collection coll = (Collection) mhm.get(key);</pre>
+ * Collection coll = (Collection) mhm.get(key);
+ * </pre>
* <p>
* {@code coll} will be a collection containing "A", "B", "C".
* </p>
* <p>
- * NOTE: Additional methods were added to this interface in Commons Collections 3.1.
- * These were added solely for documentation purposes and do not change the interface
- * as they were defined in the superinterface {@code Map} anyway.
+ * NOTE: Additional methods were added to this interface in Commons Collections 3.1. These were added solely for documentation purposes and do not change the
+ * interface as they were defined in the superinterface {@code Map} anyway.
* </p>
*
- * @param <K> The type of the keys in this map
- * @param <V> The type of the values in this map
+ * @param <K> The type of the keys in this map.
+ * @param <V> The type of the values in this map.
* @since 2.0
* @deprecated Since 4.1, use {@link MultiValuedMap} instead
*/
@@ -54,14 +55,13 @@ public interface MultiMap<K, V> extends IterableMap<K, Object> {
/**
* Checks whether the map contains the value specified.
* <p>
- * Implementations typically check all collections against all keys for the value.
- * This cannot be mandated due to backwards compatibility of this interface.
+ * Implementations typically check all collections against all keys for the value. This cannot be mandated due to backwards compatibility of this interface.
* </p>
*
- * @param value The value to search for
- * @return true if the map contains the value
- * @throws ClassCastException if the value is of an invalid type
- * @throws NullPointerException if the value is null and null value are invalid
+ * @param value The value to search for.
+ * @return true if the map contains the value.
+ * @throws ClassCastException if the value is of an invalid type.
+ * @throws NullPointerException if the value is null and null value are invalid.
*/
@Override
boolean containsValue(Object value);
@@ -69,24 +69,21 @@ public interface MultiMap<K, V> extends IterableMap<K, Object> {
/**
* Gets the collection of values associated with the specified key.
* <p>
- * The returned value will implement {@code Collection}. Implementations
- * are free to declare that they return {@code Collection} subclasses
- * such as {@code List} or {@code Set}.
+ * The returned value will implement {@code Collection}. Implementations are free to declare that they return {@code Collection} subclasses such as
+ * {@code List} or {@code Set}.
* </p>
* <p>
- * Implementations typically return {@code null} if no values have
- * been mapped to the key, however the implementation may choose to
- * return an empty collection.
+ * Implementations typically return {@code null} if no values have been mapped to the key, however the implementation may choose to return an empty
+ * collection.
* </p>
* <p>
* Implementations may choose to return a clone of the internal collection.
* </p>
*
- * @param key The key to retrieve
- * @return The {@code Collection} of values, implementations should
- * return {@code null} for no mapping, but may return an empty collection
- * @throws ClassCastException if the key is of an invalid type
- * @throws NullPointerException if the key is null and null keys are invalid
+ * @param key The key to retrieve.
+ * @return The {@code Collection} of values, implementations should return {@code null} for no mapping, but may return an empty collection.
+ * @throws ClassCastException if the key is of an invalid type.
+ * @throws NullPointerException if the key is null and null keys are invalid.
*/
@Override
Object get(Object key); // Cannot use get(K key) as that does not properly implement Map#get
@@ -94,19 +91,17 @@ public interface MultiMap<K, V> extends IterableMap<K, Object> {
/**
* Adds the value to the collection associated with the specified key.
* <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.
- * The collection may be a {@code List}, {@code Set} or other
- * collection dependent on implementation.
+ * Unlike a normal {@code Map} the previous value is not replaced. Instead, the new value is added to the collection stored against the key. The collection
+ * may be a {@code List}, {@code Set} or other collection dependent on implementation.
* </p>
*
- * @param key The key to store against
- * @param value The value to add to the collection at the key
- * @return typically the value added if the map changed and null if the map did not change
- * @throws UnsupportedOperationException if the map is unmodifiable
- * @throws ClassCastException if the key or value is of an invalid type
- * @throws NullPointerException if the key or value is null and null is invalid
- * @throws IllegalArgumentException if the key or value is invalid
+ * @param key The key to store against.
+ * @param value The value to add to the collection at the key.
+ * @return typically the value added if the map changed and null if the map did not change.
+ * @throws UnsupportedOperationException if the map is unmodifiable.
+ * @throws ClassCastException if the key or value is of an invalid type.
+ * @throws NullPointerException if the key or value is null and null is invalid.
+ * @throws IllegalArgumentException if the key or value is invalid.
*/
@Override
Object put(K key, Object value);
@@ -114,16 +109,14 @@ public interface MultiMap<K, V> extends IterableMap<K, Object> {
/**
* Removes all values associated with the specified key.
* <p>
- * Implementations typically return {@code null} from a subsequent
- * {@code get(Object)}, however they may choose to return an empty collection.
+ * Implementations typically return {@code null} from a subsequent {@code get(Object)}, however they may choose to return an empty collection.
* </p>
*
- * @param key The key to remove values from
- * @return The {@code Collection} of values removed, implementations should
- * return {@code null} for no mapping found, but may return an empty collection
- * @throws UnsupportedOperationException if the map is unmodifiable
- * @throws ClassCastException if the key is of an invalid type
- * @throws NullPointerException if the key is null and null keys are invalid
+ * @param key The key to remove values from.
+ * @return The {@code Collection} of values removed, implementations should return {@code null} for no mapping found, but may return an empty collection.
+ * @throws UnsupportedOperationException if the map is unmodifiable.
+ * @throws ClassCastException if the key is of an invalid type.
+ * @throws NullPointerException if the key is null and null keys are invalid.
*/
@Override
Object remove(Object key); // Cannot use remove(K key) as that does not properly implement Map#remove
@@ -131,33 +124,30 @@ public interface MultiMap<K, V> extends IterableMap<K, Object> {
/**
* Removes a specific value from map.
* <p>
- * The item is removed from the collection mapped to the specified key.
- * Other values attached to that key are unaffected.
+ * 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, implementations typically
- * return {@code null} from a subsequent {@code get(Object)}, however
- * they may choose to return an empty collection.
+ * If the last value for a key is removed, implementations typically return {@code null} from a subsequent {@code get(Object)}, however they may choose to
+ * return an empty collection.
* </p>
*
- * @param key The key to remove from
- * @param item The item to remove
- * @return {@code true} if the mapping was removed, {@code false} otherwise
- * @throws UnsupportedOperationException if the map is unmodifiable
- * @throws ClassCastException if the key or value is of an invalid type
- * @throws NullPointerException if the key or value is null and null is invalid
- * @since 4.0 (signature in previous releases: V remove(K, V))
+ * @param key The key to remove from.
+ * @param item The item to remove.
+ * @return {@code true} if the mapping was removed, {@code false} otherwise.
+ * @throws UnsupportedOperationException if the map is unmodifiable.
+ * @throws ClassCastException if the key or value is of an invalid type.
+ * @throws NullPointerException if the key or value is null and null is invalid.
+ * @since 4.0 (signature in previous releases: V remove(K, V)).
*/
boolean removeMapping(K key, V item);
/**
* Gets the number of keys in this map.
* <p>
- * Implementations typically return only the count of keys in the map
- * This cannot be mandated due to backwards compatibility of this interface.
+ * Implementations typically return only the count of keys in the map This cannot be mandated due to backwards compatibility of this interface.
* </p>
*
- * @return The number of key-collection mappings in this map
+ * @return The number of key-collection mappings in this map.
*/
@Override
int size();
@@ -165,14 +155,12 @@ public interface MultiMap<K, V> extends IterableMap<K, Object> {
/**
* Gets a collection containing all the values in the map.
* <p>
- * Implementations typically return a collection containing the combination
- * of values from all keys.
- * This cannot be mandated due to backwards compatibility of this interface.
+ * Implementations typically return a collection containing the combination of values from all keys. This cannot be mandated due to backwards compatibility
+ * of this interface.
* </p>
*
- * @return A collection view of the values contained in this map
+ * @return A collection view of the values contained in this map.
*/
@Override
Collection<Object> values();
-
}
diff --git a/src/main/java/org/apache/commons/collections4/MultiValuedMap.java b/src/main/java/org/apache/commons/collections4/MultiValuedMap.java
index 2cb8c58f1..d7401987a 100644
--- a/src/main/java/org/apache/commons/collections4/MultiValuedMap.java
+++ b/src/main/java/org/apache/commons/collections4/MultiValuedMap.java
@@ -14,6 +14,7 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
+
package org.apache.commons.collections4;
import java.util.Collection;
@@ -27,12 +28,13 @@ import java.util.Set;
* A {@code MultiValuedMap} is a Map with slightly different semantics:
* </p>
* <ul>
- * <li>Putting a value into the map will add the value to a {@link Collection} at that key.</li>
- * <li>Getting a value will return a {@link Collection}, holding all the values put to that key.</li>
+ * <li>Putting a value into the map will add the value to a {@link Collection} at that key.</li>
+ * <li>Getting a value will return a {@link Collection}, holding all the values put to that key.</li>
* </ul>
* <p>
* For example:
* </p>
+ *
* <pre>{@code
* MultiValuedMap<Integer, String> map = new ArrayListValuedHashMap<>();
* map.put(1, "A");
@@ -52,21 +54,17 @@ public interface MultiValuedMap<K, V> {
// Query operations
/**
- * Returns a view of this multivalued map as a {@code Map} from each distinct
- * key to the non-empty collection of that key's associated values.
+ * Returns a view of this multivalued map as a {@code Map} from each distinct key to the non-empty collection of that key's associated values.
* <p>
- * Note that {@code this.asMap().get(k)} is equivalent to {@code this.get(k)}
- * only when {@code k} is a key contained in the multivalued map; otherwise it
+ * Note that {@code this.asMap().get(k)} is equivalent to {@code this.get(k)} only when {@code k} is a key contained in the multivalued map; otherwise it
* returns {@code null} as opposed to an empty collection.
* </p>
* <p>
- * Changes to the returned map or the collections that serve as its values
- * will update the underlying multivalued map, and vice versa. The map does
- * not support {@code put} or {@code putAll}, nor do its entries support
- * {@link java.util.Map.Entry#setValue(Object) setValue}.
+ * Changes to the returned map or the collections that serve as its values will update the underlying multivalued map, and vice versa. The map does not
+ * support {@code put} or {@code putAll}, nor do its entries support {@link java.util.Map.Entry#setValue(Object) setValue}.
* </p>
*
- * @return A map view of the mappings in this multivalued map
+ * @return A map view of the mappings in this multivalued map.
*/
Map<K, Collection<V>> asMap();
@@ -76,67 +74,59 @@ public interface MultiValuedMap<K, V> {
* The map will be empty after this call returns.
* </p>
*
- * @throws UnsupportedOperationException if the map is unmodifiable
+ * @throws UnsupportedOperationException if the map is unmodifiable.
*/
void clear();
/**
- * Returns {@code true} if this map contains a mapping for the specified
- * key. More formally, returns {@code true} if and only if this map contains
- * a mapping for a key {@code k} such that {@code (key==null ? k==null : key.equals(k))}.
- * (There can be at most one such mapping.)
+ * Returns {@code true} if this map contains a mapping for the specified key. More formally, returns {@code true} if and only if this map contains a mapping
+ * for a key {@code k} such that {@code (key==null ? k==null : key.equals(k))}. (There can be at most one such mapping.)
*
- * @param key key whose presence in this map is to be tested
- * @return true if this map contains a mapping for the specified key
- * @throws NullPointerException if the specified key is null and this map
- * does not permit null keys (optional)
+ * @param key key whose presence in this map is to be tested.
+ * @return true if this map contains a mapping for the specified key.
+ * @throws NullPointerException if the specified key is null and this map does not permit null keys (optional).
*/
boolean containsKey(Object key);
/**
* Checks whether the map contains a mapping for the specified key and value.
*
- * @param key The key to search for
- * @param value The value to search for
- * @return true if the map contains the value
+ * @param key The key to search for.
+ * @param value The value to search for.
+ * @return true if the map contains the value.
*/
boolean containsMapping(Object key, Object value);
/**
* Checks whether the map contains at least one mapping for the specified value.
*
- * @param value The value to search for
- * @return true if the map contains the value
- * @throws NullPointerException if the value is null and null values are not supported
- * by the used collection types (optional)
+ * @param value The value to search for.
+ * @return true if the map contains the value.
+ * @throws NullPointerException if the value is null and null values are not supported by the used collection types (optional).
*/
boolean containsValue(Object value);
/**
* Returns a {@link Collection} view of the mappings contained in this multivalued map.
* <p>
- * The collection is backed by the map, so changes to the map are reflected
- * in the collection, and vice-versa.
+ * The collection is backed by the map, so changes to the map are reflected in the collection, and vice-versa.
* </p>
*
- * @return A set view of the mappings contained in this map
+ * @return A set view of the mappings contained in this map.
*/
Collection<Entry<K, V>> entries();
-
// Modification operations
/**
* Gets a view collection of the values associated with the specified key.
* <p>
- * This method will return an <strong>empty</strong> collection if {@link #containsKey(Object)}
- * returns {@code false}. Changes to the returned collection will update the underlying
- * {@code MultiValuedMap} and vice-versa.
+ * This method will return an <strong>empty</strong> collection if {@link #containsKey(Object)} returns {@code false}. Changes to the returned collection
+ * will update the underlying {@code MultiValuedMap} and vice-versa.
* </p>
*
- * @param key The key to retrieve
- * @return The {@code Collection} of values, implementations should
- * return an empty collection for no mapping
- * @throws NullPointerException if the key is null and null keys are invalid (optional)
+ * @param key The key to retrieve.
+ * @return The {@code Collection} of values, implementations should return an empty collection for no mapping.
+ * @throws NullPointerException if the key is null and null keys are invalid (optional).
*/
Collection<V> get(K key);
@@ -154,198 +144,165 @@ public interface MultiValuedMap<K, V> {
/**
* Returns {@code true} if this map contains no key-value mappings.
*
- * @return {@code true} if this map contains no key-value mappings
+ * @return {@code true} if this map contains no key-value mappings.
*/
boolean isEmpty();
/**
* Returns a {@link MultiSet} view of the keys contained in this multivalued map.
* <p>
- * The {@link MultiSet#getCount(Object)} method of the returned multiset will give
- * the same result a calling {@code get(Object).size()} for the same key.
+ * The {@link MultiSet#getCount(Object)} method of the returned multiset will give the same result a calling {@code get(Object).size()} for the same key.
* </p>
* <p>
- * This multiset is backed by the map, so any changes in the map are reflected in
- * the multiset.
+ * This multiset is backed by the map, so any changes in the map are reflected in the multiset.
* </p>
*
- * @return A multiset view of the keys contained in this map
+ * @return A multiset view of the keys contained in this map.
*/
MultiSet<K> keys();
/**
* Returns a {@link Set} view of the keys contained in this multivalued map.
* <p>
- * The set is backed by the map, so changes to the map are reflected
- * in the set, and vice-versa.
+ * The set is backed by the map, so changes to the map are reflected in the set, and vice-versa.
* </p>
* <p>
- * If the map is modified while an iteration over the set is in
- * progress (except through the iterator's own {@code remove} operation),
- * the result of the iteration is undefined. The set supports element
- * removal, which removes the corresponding mapping from the map, via the
- * {@code Iterator.remove}, {@code Set.remove}, {@code removeAll},
- * {@code retainAll}, and {@code clear} operations. It does not support
- * the {@code add} or {@code addAll} operations.
+ * If the map is modified while an iteration over the set is in progress (except through the iterator's own {@code remove} operation), the result of the
+ * iteration is undefined. The set supports element removal, which removes the corresponding mapping from the map, via the {@code Iterator.remove},
+ * {@code Set.remove}, {@code removeAll}, {@code retainAll}, and {@code clear} operations. It does not support the {@code add} or {@code addAll} operations.
* </p>
*
- * @return A set view of the keys contained in this map
+ * @return A set view of the keys contained in this map.
*/
Set<K> keySet();
/**
* Obtains a {@code MapIterator} over this multivalued map.
* <p>
- * A map iterator is an efficient way of iterating over maps. There is no
- * need to access the entries collection or use {@code Map.Entry} objects.
+ * A map iterator is an efficient way of iterating over maps. There is no need to access the entries collection or use {@code Map.Entry} objects.
* </p>
*
- * @return A map iterator
+ * @return A map iterator.
*/
MapIterator<K, V> mapIterator();
/**
* Adds a key-value mapping to this multivalued map.
* <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.
- * Depending on the collection type used, duplicate key-value mappings may
- * be allowed.
+ * Unlike a normal {@code Map} the previous value is not replaced. Instead, the new value is added to the collection stored against the key. Depending on
+ * the collection type used, duplicate key-value mappings may be allowed.
* </p>
* <p>
- * The method will return {@code true} if the size of the multivalued map
- * has been increased because of this operation.
+ * The method will return {@code true} if the size of the multivalued map has been increased because of this operation.
* </p>
*
- * @param key The key to store against
- * @param value The value to add to the collection at the key
- * @return true if the map changed as a result of this put operation, or false
- * if the map already contained the key-value mapping and the collection
- * type does not allow duplicate values, for example when using a Set
- * @throws UnsupportedOperationException if the put operation is not supported by
- * this multivalued map, for example if it is unmodifiable
- * @throws NullPointerException if the key or value is null and null is invalid (optional)
- * @throws IllegalArgumentException if some aspect of the specified key or value prevents
- * it from being stored in this multivalued map
+ * @param key The key to store against.
+ * @param value The value to add to the collection at the key.
+ * @return true if the map changed as a result of this put operation, or false if the map already contained the key-value mapping and the collection type
+ * does not allow duplicate values, for example when using a Set.
+ * @throws UnsupportedOperationException if the put operation is not supported by this multivalued map, for example if it is unmodifiable.
+ * @throws NullPointerException if the key or value is null and null is invalid (optional).
+ * @throws IllegalArgumentException if some aspect of the specified key or value prevents it from being stored in this multivalued map.
*/
boolean put(K key, V value);
/**
* Adds a mapping to the specified key for all values contained in the given Iterable.
*
- * @param key The key to store against
- * @param values The values to add to the collection at the key, may not be null
- * @return true if the map changed as a result of this operation
- * @throws NullPointerException if the specified iterable is null, or if this map
- * does not permit null keys or values, and the specified key or values contain
- * null (optional)
+ * @param key The key to store against.
+ * @param values The values to add to the collection at the key, may not be null.
+ * @return true if the map changed as a result of this operation.
+ * @throws NullPointerException if the specified iterable is null, or if this map does not permit null keys or values, and the specified key or values
+ * contain null (optional).
*/
boolean putAll(K key, Iterable<? extends V> values);
/**
- * Copies all mappings from the specified map to this multivalued map
- * (optional operation).
+ * Copies all mappings from the specified map to this multivalued map (optional operation).
* <p>
- * The effect of this call is equivalent to that of calling
- * {@link #put(Object,Object) put(k, v)} on this map once for each mapping
- * from key {@code k} to value {@code v} in the specified map.
+ * The effect of this call is equivalent to that of calling {@link #put(Object,Object) put(k, v)} on this map once for each mapping from key {@code k} to
+ * value {@code v} in the specified map.
* </p>
* <p>
- * The behavior of this operation is undefined if the specified map is modified
- * while the operation is in progress.
+ * The behavior of this operation is undefined if the specified map is modified while the operation is in progress.
* </p>
*
- * @param map mappings to be stored in this map, may not be null
- * @return true if the map changed as a result of this operation
- * @throws UnsupportedOperationException if the {@code putAll} operation is
- * not supported by this map
- * @throws NullPointerException if the specified map is null, or if this map
- * does not permit null keys or values, and the specified map
- * contains null keys or values (optional)
- * @throws IllegalArgumentException if some property of a key or value in
- * the specified map prevents it from being stored in this map
+ * @param map mappings to be stored in this map, may not be null.
+ * @return true if the map changed as a result of this operation.
+ * @throws UnsupportedOperationException if the {@code putAll} operation is not supported by this map.
+ * @throws NullPointerException if the specified map is null, or if this map does not permit null keys or values, and the specified map contains
+ * null keys or values (optional).
+ * @throws IllegalArgumentException if some property of a key or value in the specified map prevents it from being stored in this map.
*/
boolean putAll(Map<? extends K, ? extends V> map);
/**
- * Copies all mappings from the specified map to this multivalued map
- * (optional operation).
+ * Copies all mappings from the specified map to this multivalued map (optional operation).
* <p>
- * The effect of this call is equivalent to that of calling
- * {@link #put(Object,Object) put(k, v)} on this map once for each
- * mapping from key {@code k} to value {@code v} in the specified map.
+ * The effect of this call is equivalent to that of calling {@link #put(Object,Object) put(k, v)} on this map once for each mapping from key {@code k} to
+ * value {@code v} in the specified map.
* </p>
* <p>
- * The behavior of this operation is undefined if the specified map is modified
- * while the operation is in progress.
+ * The behavior of this operation is undefined if the specified map is modified while the operation is in progress.
* </p>
*
- * @param map mappings to be stored in this map, may not be null
- * @return true if the map changed as a result of this operation
- * @throws UnsupportedOperationException if the {@code putAll} operation is
- * not supported by this map
- * @throws NullPointerException if the specified map is null, or if this map
- * does not permit null keys or values, and the specified map
- * contains null keys or values (optional)
- * @throws IllegalArgumentException if some property of a key or value in
- * the specified map prevents it from being stored in this map
+ * @param map mappings to be stored in this map, may not be null.
+ * @return true if the map changed as a result of this operation.
+ * @throws UnsupportedOperationException if the {@code putAll} operation is not supported by this map.
+ * @throws NullPointerException if the specified map is null, or if this map does not permit null keys or values, and the specified map contains
+ * null keys or values (optional).
+ * @throws IllegalArgumentException if some property of a key or value in the specified map prevents it from being stored in this map.
*/
boolean putAll(MultiValuedMap<? extends K, ? extends V> map);
/**
* Removes all values associated with the specified key.
* <p>
- * The returned collection <em>may</em> be modifiable, but updates will not be propagated
- * to this multivalued map. In case no mapping was stored for the specified
- * key, an empty, unmodifiable collection will be returned.
+ * The returned collection <em>may</em> be modifiable, but updates will not be propagated to this multivalued map. In case no mapping was stored for the
+ * specified key, an empty, unmodifiable collection will be returned.
* </p>
*
- * @param key The key to remove values from
- * @return The values that were removed
- * @throws UnsupportedOperationException if the map is unmodifiable
- * @throws NullPointerException if the key is null and null keys are invalid (optional)
+ * @param key The key to remove values from.
+ * @return The values that were removed.
+ * @throws UnsupportedOperationException if the map is unmodifiable.
+ * @throws NullPointerException if the key is null and null keys are invalid (optional).
*/
Collection<V> remove(Object key);
/**
* Removes a key-value mapping from the map.
* <p>
- * The item is removed from the collection mapped to the specified key.
- * Other values attached to that key are unaffected.
+ * 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, implementations typically return
- * an empty collection from a subsequent {@code get(Object)}.
+ * If the last value for a key is removed, implementations typically return an empty collection from a subsequent {@code get(Object)}.
* </p>
*
- * @param key The key to remove from
- * @param item The item to remove
- * @return true if the mapping was removed, false otherwise
- * @throws UnsupportedOperationException if the map is unmodifiable
- * @throws NullPointerException if the key or value is null and null is invalid (optional)
+ * @param key The key to remove from.
+ * @param item The item to remove.
+ * @return true if the mapping was removed, false otherwise.
+ * @throws UnsupportedOperationException if the map is unmodifiable.
+ * @throws NullPointerException if the key or value is null and null is invalid (optional).
*/
boolean removeMapping(Object key, Object item);
/**
* Gets the total size of the map.
* <p>
- * Implementations would return the total size of the map which is the count
- * of the values from all keys.
+ * Implementations would return the total size of the map which is the count of the values from all keys.
* </p>
*
- * @return The total size of the map
+ * @return The total size of the map.
*/
int size();
/**
* Gets a {@link Collection} view of all values contained in this multivalued map.
* <p>
- * Implementations typically return a collection containing the combination
- * of values from all keys.
+ * Implementations typically return a collection containing the combination of values from all keys.
* </p>
*
- * @return A collection view of the values contained in this multivalued map
+ * @return A collection view of the values contained in this multivalued map.
*/
Collection<V> values();
-
}
diff --git a/src/main/java/org/apache/commons/collections4/OrderedBidiMap.java b/src/main/java/org/apache/commons/collections4/OrderedBidiMap.java
index 6d3c034da..bdcfc2146 100644
--- a/src/main/java/org/apache/commons/collections4/OrderedBidiMap.java
+++ b/src/main/java/org/apache/commons/collections4/OrderedBidiMap.java
@@ -14,18 +14,17 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
+
package org.apache.commons.collections4;
/**
- * Defines a map that allows bidirectional lookup between key and values
- * and retains and provides access to an ordering.
+ * Defines a map that allows bidirectional lookup between key and values and retains and provides access to an ordering.
* <p>
- * Implementations should allow a value to be looked up from a key and
- * a key to be looked up from a value with equal performance.
+ * Implementations should allow a value to be looked up from a key and a key to be looked up from a value with equal performance.
* </p>
*
- * @param <K> The type of the keys in the map
- * @param <V> The type of the values in the map
+ * @param <K> The type of the keys in the map.
+ * @param <V> The type of the values in the map.
* @since 3.0
*/
public interface OrderedBidiMap<K, V> extends BidiMap<K, V>, OrderedMap<K, V> {
@@ -33,22 +32,18 @@ public interface OrderedBidiMap<K, V> extends BidiMap<K, V>, OrderedMap<K, V> {
/**
* Gets a view of this map where the keys and values are reversed.
* <p>
- * Changes to one map will be visible in the other and vice versa.
- * This enables both directions of the map to be accessed equally.
+ * Changes to one map will be visible in the other and vice versa. This enables both directions of the map to be accessed equally.
* </p>
* <p>
- * Implementations should seek to avoid creating a new object every time this
- * method is called. See {@code AbstractMap.values()} etc. Calling this
- * method on the inverse map should return the original.
+ * Implementations should seek to avoid creating a new object every time this method is called. See {@code AbstractMap.values()} etc. Calling this method on
+ * the inverse map should return the original.
* </p>
* <p>
- * Implementations must return an {@code OrderedBidiMap} instance,
- * usually by forwarding to {@code inverseOrderedBidiMap()}.
+ * Implementations must return an {@code OrderedBidiMap} instance, usually by forwarding to {@code inverseOrderedBidiMap()}.
* </p>
*
- * @return An inverted bidirectional map
+ * @return An inverted bidirectional map.
*/
@Override
OrderedBidiMap<V, K> inverseBidiMap();
-
}
diff --git a/src/main/java/org/apache/commons/collections4/OrderedIterator.java b/src/main/java/org/apache/commons/collections4/OrderedIterator.java
index e21512552..bc5a29359 100644
--- a/src/main/java/org/apache/commons/collections4/OrderedIterator.java
+++ b/src/main/java/org/apache/commons/collections4/OrderedIterator.java
@@ -32,15 +32,15 @@ public interface OrderedIterator<E> extends Iterator<E> {
/**
* Checks to see if there is a previous element that can be iterated to.
*
- * @return {@code true} if the iterator has a previous element
+ * @return {@code true} if the iterator has a previous element.
*/
boolean hasPrevious();
/**
* Gets the previous element from the container.
*
- * @return The previous element in the iteration
- * @throws java.util.NoSuchElementException if the iteration is finished
+ * @return The previous element in the iteration.
+ * @throws java.util.NoSuchElementException if the iteration is finished.
*/
E previous();
diff --git a/src/main/java/org/apache/commons/collections4/OrderedMap.java b/src/main/java/org/apache/commons/collections4/OrderedMap.java
index 9c85eda96..1156e87db 100644
--- a/src/main/java/org/apache/commons/collections4/OrderedMap.java
+++ b/src/main/java/org/apache/commons/collections4/OrderedMap.java
@@ -14,14 +14,14 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
+
package org.apache.commons.collections4;
/**
- * Defines a map that maintains order and allows both forward and backward
- * iteration through that order.
+ * Defines a map that maintains order and allows both forward and backward iteration through that order.
*
- * @param <K> The type of the keys in the map
- * @param <V> The type of the values in the map
+ * @param <K> The type of the keys in the map.
+ * @param <V> The type of the values in the map.
* @since 3.0
*/
public interface OrderedMap<K, V> extends IterableMap<K, V> {
@@ -29,27 +29,26 @@ public interface OrderedMap<K, V> extends IterableMap<K, V> {
/**
* Gets the first key currently in this map.
*
- * @return The first key currently in this map
- * @throws java.util.NoSuchElementException if this map is empty
+ * @return The first key currently in this map.
+ * @throws java.util.NoSuchElementException if this map is empty.
*/
K firstKey();
/**
* Gets the last key currently in this map.
*
- * @return The last key currently in this map
- * @throws java.util.NoSuchElementException if this map is empty
+ * @return The last key currently in this map.
+ * @throws java.util.NoSuchElementException if this map is empty.
*/
K lastKey();
/**
* Obtains an {@code OrderedMapIterator} over the map.
* <p>
- * An ordered map iterator is an efficient way of iterating over maps
- * in both directions.
+ * An ordered map iterator is an efficient way of iterating over maps in both directions.
* </p>
*
- * @return A map iterator
+ * @return A map iterator.
*/
@Override
OrderedMapIterator<K, V> mapIterator();
@@ -57,17 +56,16 @@ public interface OrderedMap<K, V> extends IterableMap<K, V> {
/**
* Gets the next key after the one specified.
*
- * @param key The key to search for next from
- * @return The next key, null if no match or at end
+ * @param key The key to search for next from.
+ * @return The next key, null if no match or at end.
*/
K nextKey(K key);
/**
* Gets the previous key before the one specified.
*
- * @param key The key to search for previous from
- * @return The previous key, null if no match or at start
+ * @param key The key to search for previous from.
+ * @return The previous key, null if no match or at start.
*/
K previousKey(K key);
-
}
diff --git a/src/main/java/org/apache/commons/collections4/OrderedMapIterator.java b/src/main/java/org/apache/commons/collections4/OrderedMapIterator.java
index cb7b448b6..9aab935be 100644
--- a/src/main/java/org/apache/commons/collections4/OrderedMapIterator.java
+++ b/src/main/java/org/apache/commons/collections4/OrderedMapIterator.java
@@ -14,6 +14,7 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
+
package org.apache.commons.collections4;
/**
@@ -31,7 +32,7 @@ public interface OrderedMapIterator<K, V> extends MapIterator<K, V>, OrderedIter
/**
* Checks to see if there is a previous entry that can be iterated to.
*
- * @return {@code true} if the iterator has a previous element
+ * @return {@code true} if the iterator has a previous element.
*/
@Override
boolean hasPrevious();
@@ -39,10 +40,9 @@ public interface OrderedMapIterator<K, V> extends MapIterator<K, V>, OrderedIter
/**
* Gets the previous <em>key</em> from the {@code Map}.
*
- * @return The previous key in the iteration
- * @throws java.util.NoSuchElementException if the iteration is finished
+ * @return The previous key in the iteration.
+ * @throws java.util.NoSuchElementException if the iteration is finished.
*/
@Override
K previous();
-
}
diff --git a/src/main/java/org/apache/commons/collections4/Predicate.java b/src/main/java/org/apache/commons/collections4/Predicate.java
index 653365156..aca1a6f70 100644
--- a/src/main/java/org/apache/commons/collections4/Predicate.java
+++ b/src/main/java/org/apache/commons/collections4/Predicate.java
@@ -14,25 +14,22 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
+
package org.apache.commons.collections4;
/**
- * Defines a functor interface implemented by classes that perform a predicate
- * test on an object.
+ * Defines a functor interface implemented by classes that perform a predicate test on an object.
* <p>
- * A {@code Predicate} is the object equivalent of an {@code if} statement.
- * It uses the input object to return a true or false value, and is often used in
+ * A {@code Predicate} is the object equivalent of an {@code if} statement. It uses the input object to return a true or false value, and is often used in
* validation or filtering.
* </p>
* <p>
- * Standard implementations of common predicates are provided by
- * {@link PredicateUtils}. These include true, false, instanceof, equals, and,
- * or, not, method invocation and null testing.
+ * Standard implementations of common predicates are provided by {@link PredicateUtils}. These include true, false, instanceof, equals, and, or, not, method
+ * invocation and null testing.
* </p>
*
* @param <T> The type of the input to the predicate.
- * @since 1.0
- * This will be deprecated in 5.0 in favor of {@link Predicate}.
+ * @since 1.0 This will be deprecated in 5.0 in favor of {@link Predicate}.
*/
//@Deprecated
public interface Predicate<T> extends java.util.function.Predicate<T> {
@@ -40,11 +37,11 @@ public interface Predicate<T> extends java.util.function.Predicate<T> {
/**
* Use the specified parameter to perform a test that returns true or false.
*
- * @param object The object to evaluate, should not be changed
- * @return true or false
- * @throws ClassCastException (runtime) if the input is the wrong class
- * @throws IllegalArgumentException (runtime) if the input is invalid
- * @throws FunctorException (runtime) if the predicate encounters a problem
+ * @param object The object to evaluate, should not be changed.
+ * @return true or false.
+ * @throws ClassCastException (runtime) if the input is the wrong class.
+ * @throws IllegalArgumentException (runtime) if the input is invalid.
+ * @throws FunctorException (runtime) if the predicate encounters a problem.
*/
boolean evaluate(T object);
@@ -52,5 +49,4 @@ public interface Predicate<T> extends java.util.function.Predicate<T> {
default boolean test(final T t) {
return evaluate(t);
}
-
}
diff --git a/src/main/java/org/apache/commons/collections4/Put.java b/src/main/java/org/apache/commons/collections4/Put.java
index a0f3fc136..e8c17d440 100644
--- a/src/main/java/org/apache/commons/collections4/Put.java
+++ b/src/main/java/org/apache/commons/collections4/Put.java
@@ -14,6 +14,7 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
+
package org.apache.commons.collections4;
import java.util.Map;
@@ -21,15 +22,13 @@ import java.util.Map;
/**
* The "write" subset of the {@link Map} interface.
* <p>
- * NOTE: in the original {@link Map} interface, {@link Map#put(Object, Object)} is known
- * to have the same return type as {@link Map#get(Object)}, namely {@code V}. {@link Put}
- * makes no assumptions in this regard (there is no association with, nor even knowledge
- * of, a "reading" interface) and thus defines {@link #put(Object, Object)} as returning
- * {@link Object}.
+ * NOTE: in the original {@link Map} interface, {@link Map#put(Object, Object)} is known to have the same return type as {@link Map#get(Object)}, namely
+ * {@code V}. {@link Put} makes no assumptions in this regard (there is no association with, nor even knowledge of, a "reading" interface) and thus defines
+ * {@link #put(Object, Object)} as returning {@link Object}.
* </p>
*
- * @param <K> The type of the keys in this map
- * @param <V> The type of the values in this map
+ * @param <K> The type of the keys in this map.
+ * @param <V> The type of the values in this map.
* @since 4.0
* @see Get
*/
@@ -45,17 +44,13 @@ public interface Put<K, V> {
/**
* Associates the specified value with the specified key in this map.
* <p>
- * Note that the return type is Object, rather than V as in the Map interface.
- * See the class Javadoc for further info.
+ * Note that the return type is Object, rather than V as in the Map interface. See the class Javadoc for further info.
* </p>
*
- * @param key key with which the specified value is to be associated
- * @param value value to be associated with the specified key
- * @return The previous value associated with {@code key}, or
- * {@code null} if there was no mapping for {@code key}.
- * (A {@code null} return can also indicate that the map
- * previously associated {@code null} with {@code key},
- * if the implementation supports {@code null} values.)
+ * @param key key with which the specified value is to be associated.
+ * @param value value to be associated with the specified key.
+ * @return The previous value associated with {@code key}, or {@code null} if there was no mapping for {@code key}. (A {@code null} return can also indicate
+ * that the map previously associated {@code null} with {@code key}, if the implementation supports {@code null} values.)
* @see Map#put(Object, Object)
*/
Object put(K key, V value);
@@ -63,9 +58,8 @@ public interface Put<K, V> {
/**
* Copies all of the mappings from the specified map to this map.
*
- * @param t mappings to be stored in this map
+ * @param t mappings to be stored in this map.
* @see Map#putAll(Map)
*/
void putAll(Map<? extends K, ? extends V> t);
-
}
diff --git a/src/main/java/org/apache/commons/collections4/ResettableIterator.java b/src/main/java/org/apache/commons/collections4/ResettableIterator.java
index bdcd8f76b..055cba6d3 100644
--- a/src/main/java/org/apache/commons/collections4/ResettableIterator.java
+++ b/src/main/java/org/apache/commons/collections4/ResettableIterator.java
@@ -14,6 +14,7 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
+
package org.apache.commons.collections4;
import java.util.Iterator;
@@ -30,9 +31,7 @@ import java.util.Iterator;
public interface ResettableIterator<E> extends Iterator<E> {
/**
- * Resets the iterator back to the position at which the iterator
- * was created.
+ * Resets the iterator back to the position at which the iterator was created.
*/
void reset();
-
}
diff --git a/src/main/java/org/apache/commons/collections4/SetValuedMap.java b/src/main/java/org/apache/commons/collections4/SetValuedMap.java
index 5f27dd4a9..8dce45fdd 100644
--- a/src/main/java/org/apache/commons/collections4/SetValuedMap.java
+++ b/src/main/java/org/apache/commons/collections4/SetValuedMap.java
@@ -14,6 +14,7 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
+
package org.apache.commons.collections4;
import java.util.Set;
@@ -24,12 +25,12 @@ import java.util.Set;
* A {@code SetValuedMap} is a Map with slightly different semantics:
* </p>
* <ul>
- * <li>Putting a value into the map will add the value to a {@link Set} at that key.</li>
- * <li>Getting a value will return a {@link Set}, holding all the values put to that key.</li>
+ * <li>Putting a value into the map will add the value to a {@link Set} at that key.</li>
+ * <li>Getting a value will return a {@link Set}, holding all the values put to that key.</li>
* </ul>
*
- * @param <K> The type of the keys in this map
- * @param <V> The type of the values in this map
+ * @param <K> The type of the keys in this map.
+ * @param <V> The type of the values in this map.
* @since 4.1
*/
public interface SetValuedMap<K, V> extends MultiValuedMap<K, V> {
@@ -37,14 +38,12 @@ public interface SetValuedMap<K, V> extends MultiValuedMap<K, V> {
/**
* Gets the set of values associated with the specified key.
* <p>
- * Implementations typically return an empty {@code Set} if no values
- * have been mapped to the key.
+ * Implementations typically return an empty {@code Set} if no values have been mapped to the key.
* </p>
*
- * @param key The key to retrieve
- * @return The {@code Set} of values, implementations should return an
- * empty {@code Set} for no mapping
- * @throws NullPointerException if the key is null and null keys are invalid
+ * @param key The key to retrieve.
+ * @return The {@code Set} of values, implementations should return an empty {@code Set} for no mapping.
+ * @throws NullPointerException if the key is null and null keys are invalid.
*/
@Override
Set<V> get(K key);
@@ -52,16 +51,14 @@ public interface SetValuedMap<K, V> extends MultiValuedMap<K, V> {
/**
* Removes all values associated with the specified key.
* <p>
- * The returned set <em>may</em> be modifiable, but updates will not be
- * propagated to this set-valued map. In case no mapping was stored for the
- * specified key, an empty, unmodifiable set will be returned.
+ * The returned set <em>may</em> be modifiable, but updates will not be propagated to this set-valued map. In case no mapping was stored for the specified
+ * key, an empty, unmodifiable set will be returned.
* </p>
*
- * @param key The key to remove values from
- * @return The {@code Set} of values removed, implementations should
- * return null for no mapping found, but may return an empty collection
- * @throws UnsupportedOperationException if the map is unmodifiable
- * @throws NullPointerException if the key is null and null keys are invalid
+ * @param key The key to remove values from.
+ * @return The {@code Set} of values removed, implementations should return null for no mapping found, but may return an empty collection.
+ * @throws UnsupportedOperationException if the map is unmodifiable.
+ * @throws NullPointerException if the key is null and null keys are invalid.
*/
@Override
Set<V> remove(Object key);
diff --git a/src/main/java/org/apache/commons/collections4/SortedBag.java b/src/main/java/org/apache/commons/collections4/SortedBag.java
index b0ee78e83..4aaee8025 100644
--- a/src/main/java/org/apache/commons/collections4/SortedBag.java
+++ b/src/main/java/org/apache/commons/collections4/SortedBag.java
@@ -14,21 +14,20 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
+
package org.apache.commons.collections4;
import java.util.Collection;
import java.util.Comparator;
+
/**
- * Defines a type of {@code Bag} that maintains a sorted order among
- * its unique representative members.
+ * Defines a type of {@code Bag} that maintains a sorted order among its unique representative members.
* <p>
- * The {@link SortedMultiSet} interface provides the same functionality
- * while complying with the {@link Collection Collection}
- * contract, and should be preferred for new code; see the {@link Bag}
- * documentation for migration notes.
+ * The {@link SortedMultiSet} interface provides the same functionality while complying with the {@link Collection Collection} contract, and should be preferred
+ * for new code; see the {@link Bag} documentation for migration notes.
* </p>
*
- * @param <E> The type of elements in this bag
+ * @param <E> The type of elements in this bag.
* @see SortedMultiSet
* @since 2.0
* @deprecated Since 4.6.0, use {@link SortedMultiSet} instead; see the {@link Bag} Javadoc for migration notes.
@@ -37,25 +36,23 @@ import java.util.Comparator;
public interface SortedBag<E> extends Bag<E> {
/**
- * Returns the comparator associated with this sorted set, or null
- * if it uses its elements' natural ordering.
+ * Returns the comparator associated with this sorted set, or null if it uses its elements' natural ordering.
*
- * @return The comparator in use, or null if natural ordering
+ * @return The comparator in use, or null if natural ordering.
*/
Comparator<? super E> comparator();
/**
* Returns the first (lowest) member.
*
- * @return The first element in the sorted bag
+ * @return The first element in the sorted bag.
*/
E first();
/**
* Returns the last (highest) member.
*
- * @return The last element in the sorted bag
+ * @return The last element in the sorted bag.
*/
E last();
-
}
diff --git a/src/main/java/org/apache/commons/collections4/SortedBidiMap.java b/src/main/java/org/apache/commons/collections4/SortedBidiMap.java
index 9fd6440cc..1bf6a33ca 100644
--- a/src/main/java/org/apache/commons/collections4/SortedBidiMap.java
+++ b/src/main/java/org/apache/commons/collections4/SortedBidiMap.java
@@ -14,17 +14,16 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
+
package org.apache.commons.collections4;
import java.util.Comparator;
import java.util.SortedMap;
/**
- * Defines a map that allows bidirectional lookup between key and values
- * and retains both keys and values in sorted order.
+ * Defines a map that allows bidirectional lookup between key and values and retains both keys and values in sorted order.
* <p>
- * Implementations should allow a value to be looked up from a key and
- * a key to be looked up from a value with equal performance.
+ * Implementations should allow a value to be looked up from a key and a key to be looked up from a value with equal performance.
* </p>
*
* @param <K> The type of the keys in the map
@@ -36,20 +35,17 @@ public interface SortedBidiMap<K, V> extends OrderedBidiMap<K, V>, SortedMap<K,
/**
* Gets a view of this map where the keys and values are reversed.
* <p>
- * Changes to one map will be visible in the other and vice versa.
- * This enables both directions of the map to be accessed equally.
+ * Changes to one map will be visible in the other and vice versa. This enables both directions of the map to be accessed equally.
* </p>
* <p>
- * Implementations should seek to avoid creating a new object every time this
- * method is called. See {@code AbstractMap.values()} etc. Calling this
- * method on the inverse map should return the original.
+ * Implementations should seek to avoid creating a new object every time this method is called. See {@code AbstractMap.values()} etc. Calling this method on
+ * the inverse map should return the original.
* </p>
* <p>
- * Implementations must return a {@code SortedBidiMap} instance,
- * usually by forwarding to {@code inverseSortedBidiMap()}.
+ * Implementations must return a {@code SortedBidiMap} instance, usually by forwarding to {@code inverseSortedBidiMap()}.
* </p>
*
- * @return An inverted bidirectional map
+ * @return An inverted bidirectional map.
*/
@Override
SortedBidiMap<V, K> inverseBidiMap();
@@ -57,7 +53,7 @@ public interface SortedBidiMap<K, V> extends OrderedBidiMap<K, V>, SortedMap<K,
/**
* Gets the comparator used for the values in the value-to-key map aspect.
*
- * @return Comparator<? super V>
+ * @return Comparator<? super V>.
*/
Comparator<? super V> valueComparator();
}
diff --git a/src/main/java/org/apache/commons/collections4/SortedMultiSet.java b/src/main/java/org/apache/commons/collections4/SortedMultiSet.java
index da96f5b65..9a3e644b0 100644
--- a/src/main/java/org/apache/commons/collections4/SortedMultiSet.java
+++ b/src/main/java/org/apache/commons/collections4/SortedMultiSet.java
@@ -31,21 +31,21 @@ public interface SortedMultiSet<E> extends MultiSet<E> {
* Returns the comparator associated with this sorted multiset, or null
* if it uses its elements' natural ordering.
*
- * @return The comparator in use, or null if natural ordering
+ * @return The comparator in use, or null if natural ordering.
*/
Comparator<? super E> comparator();
/**
* Returns the first (lowest) member.
*
- * @return The first element in the sorted multiset
+ * @return The first element in the sorted multiset.
*/
E first();
/**
* Returns the last (highest) member.
*
- * @return The last element in the sorted multiset
+ * @return The last element in the sorted multiset.
*/
E last();
diff --git a/src/main/java/org/apache/commons/collections4/Transformer.java b/src/main/java/org/apache/commons/collections4/Transformer.java
index c4f14c4c6..11f498c92 100644
--- a/src/main/java/org/apache/commons/collections4/Transformer.java
+++ b/src/main/java/org/apache/commons/collections4/Transformer.java
@@ -14,29 +14,25 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
+
package org.apache.commons.collections4;
import java.util.function.Function;
/**
- * Defines a functor interface implemented by classes that transform one
- * object into another.
+ * Defines a functor interface implemented by classes that transform one object into another.
* <p>
- * A {@code Transformer} converts the input object to the output object.
- * The input object SHOULD be left unchanged.
- * Transformers are typically used for type conversions, or extracting data
- * from an object.
+ * A {@code Transformer} converts the input object to the output object. The input object SHOULD be left unchanged. Transformers are typically used for type
+ * conversions, or extracting data from an object.
* </p>
* <p>
- * Standard implementations of common transformers are provided by
- * {@link TransformerUtils}. These include method invocation, returning a constant,
- * cloning and returning the string value.
+ * Standard implementations of common transformers are provided by {@link TransformerUtils}. These include method invocation, returning a constant, cloning and
+ * returning the string value.
* </p>
*
* @param <T> The type of the input to the function.
* @param <R> The type of the result of the function.
- * @since 1.0
- * This will be deprecated in 5.0 in favor of {@link Function}.
+ * @since 1.0 This will be deprecated in 5.0 in favor of {@link Function}.
*/
//@Deprecated
@FunctionalInterface
@@ -53,12 +49,11 @@ public interface Transformer<T, R> extends Function<T, R> {
* The input object SHOULD be left unchanged.
* </p>
*
- * @param input The object to be transformed, should be left unchanged
- * @return A transformed object
- * @throws ClassCastException (runtime) if the input is the wrong class
- * @throws IllegalArgumentException (runtime) if the input is invalid
- * @throws FunctorException (runtime) if the transform cannot be completed
+ * @param input The object to be transformed, should be left unchanged.
+ * @return A transformed object.
+ * @throws ClassCastException (runtime) if the input is the wrong class.
+ * @throws IllegalArgumentException (runtime) if the input is invalid.
+ * @throws FunctorException (runtime) if the transform cannot be completed.
*/
R transform(T input);
-
}
diff --git a/src/main/java/org/apache/commons/collections4/Trie.java b/src/main/java/org/apache/commons/collections4/Trie.java
index 0e5195a8f..2023f7586 100644
--- a/src/main/java/org/apache/commons/collections4/Trie.java
+++ b/src/main/java/org/apache/commons/collections4/Trie.java
@@ -14,6 +14,7 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
+
package org.apache.commons.collections4;
import java.util.SortedMap;
@@ -21,8 +22,8 @@ import java.util.SortedMap;
/**
* Defines the interface for a prefix tree, an ordered tree data structure. For more information, see <a href="https://en.wikipedia.org/wiki/Trie">Tries</a>.
*
- * @param <K> The type of the keys in this map
- * @param <V> The type of the values in this map
+ * @param <K> The type of the keys in this map.
+ * @param <V> The type of the values in this map.
* @since 4.0
*/
public interface Trie<K, V> extends IterableSortedMap<K, V> {
@@ -37,9 +38,8 @@ public interface Trie<K, V> extends IterableSortedMap<K, V> {
* 'Andreas', 'Andrea', and 'Andres'.
* </p>
*
- * @param key The key used in the search
- * @return A {@link SortedMap} view of this {@link Trie} with all elements whose key is prefixed by the search key
+ * @param key The key used in the search.
+ * @return A {@link SortedMap} view of this {@link Trie} with all elements whose key is prefixed by the search key.
*/
SortedMap<K, V> prefixMap(K key);
-
}
diff --git a/src/main/java/org/apache/commons/collections4/Unmodifiable.java b/src/main/java/org/apache/commons/collections4/Unmodifiable.java
index df9d98486..8cb79d946 100644
--- a/src/main/java/org/apache/commons/collections4/Unmodifiable.java
+++ b/src/main/java/org/apache/commons/collections4/Unmodifiable.java
@@ -14,6 +14,7 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
+
package org.apache.commons.collections4;
/**
@@ -21,20 +22,20 @@ package org.apache.commons.collections4;
* <p>
* This interface enables testing such as:
* </p>
+ *
* <pre>
* if (coll instanceof Unmodifiable) {
- * coll = new ArrayList(coll);
+ * coll = new ArrayList(coll);
* }
* // now we know coll is modifiable
* </pre>
* <p>
- * Of course all this only works if you use the Unmodifiable classes defined
- * in this library. If you use the JDK unmodifiable class via {@code java.util Collections}
- * then the interface won't be there.
+ * Of course all this only works if you use the Unmodifiable classes defined in this library. If you use the JDK unmodifiable class via
+ * {@code java.util Collections} then the interface won't be there.
* </p>
*
* @since 3.0
*/
public interface Unmodifiable {
- // marker interface - no methods to implement
+ // marker interface - no methods to implement.
}