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 <[email protected]> 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. }
