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 4a56d4b8544c284fc4a80687a314657817b6a103 Author: Gary Gregory <[email protected]> AuthorDate: Wed Jun 17 20:28:59 2026 +0000 Javadoc --- .../collection/AbstractCollectionDecorator.java | 13 +- .../collection/CompositeCollection.java | 158 ++++++++++----------- .../collections4/collection/IndexedCollection.java | 28 ++-- .../collection/PredicatedCollection.java | 109 ++++++++------ .../collection/SynchronizedCollection.java | 6 +- .../collection/TransformedCollection.java | 47 +++--- .../collection/UnmodifiableBoundedCollection.java | 29 ++-- .../collection/UnmodifiableCollection.java | 17 +-- 8 files changed, 216 insertions(+), 191 deletions(-) diff --git a/src/main/java/org/apache/commons/collections4/collection/AbstractCollectionDecorator.java b/src/main/java/org/apache/commons/collections4/collection/AbstractCollectionDecorator.java index e764eb556..fa96c8282 100644 --- a/src/main/java/org/apache/commons/collections4/collection/AbstractCollectionDecorator.java +++ b/src/main/java/org/apache/commons/collections4/collection/AbstractCollectionDecorator.java @@ -74,10 +74,10 @@ public abstract class AbstractCollectionDecorator<E> } /** - * Constructor that wraps (not copies). + * Constructs and wraps (not copies). * - * @param collection the collection to decorate, must not be null - * @throws NullPointerException if the collection is null + * @param collection the collection to decorate, must not be null. + * @throws NullPointerException if the collection is null. */ protected AbstractCollectionDecorator(final Collection<E> collection) { this.collection = Objects.requireNonNull(collection, "collection"); @@ -112,7 +112,7 @@ public abstract class AbstractCollectionDecorator<E> * Gets the collection being decorated. * All access to the decorated collection goes via this method. * - * @return the decorated collection + * @return the decorated collection. */ protected Collection<E> decorated() { return collection; @@ -154,9 +154,10 @@ public abstract class AbstractCollectionDecorator<E> /** * Sets the collection being decorated. * <p> - * <strong>NOTE:</strong> this method should only be used during deserialization + * <strong>NOTE:</strong> this method should only be used during deserialization. + * </p> * - * @param collection the decorated collection + * @param collection the decorated collection. */ protected void setCollection(final Collection<E> collection) { this.collection = collection; diff --git a/src/main/java/org/apache/commons/collections4/collection/CompositeCollection.java b/src/main/java/org/apache/commons/collections4/collection/CompositeCollection.java index b94f969eb..cba4bcd27 100644 --- a/src/main/java/org/apache/commons/collections4/collection/CompositeCollection.java +++ b/src/main/java/org/apache/commons/collections4/collection/CompositeCollection.java @@ -54,28 +54,28 @@ public class CompositeCollection<E> implements Collection<E>, Serializable { /** * Called when an object is to be added to the composite. * - * @param composite the CompositeCollection being changed - * @param collections all of the Collection instances in this CompositeCollection - * @param obj the object being added - * @return true if the collection is changed - * @throws UnsupportedOperationException if add is unsupported - * @throws ClassCastException if the object cannot be added due to its type - * @throws NullPointerException if the object cannot be added because its null - * @throws IllegalArgumentException if the object cannot be added + * @param composite the CompositeCollection being changed. + * @param collections all of the Collection instances in this CompositeCollection. + * @param obj the object being added. + * @return true if the collection is changed. + * @throws UnsupportedOperationException if add is unsupported. + * @throws ClassCastException if the object cannot be added due to its type. + * @throws NullPointerException if the object cannot be added because its null. + * @throws IllegalArgumentException if the object cannot be added. */ boolean add(CompositeCollection<E> composite, List<Collection<E>> collections, E obj); /** * Called when a collection is to be added to the composite. * - * @param composite the CompositeCollection being changed - * @param collections all of the Collection instances in this CompositeCollection - * @param coll the collection being added - * @return true if the collection is changed - * @throws UnsupportedOperationException if add is unsupported - * @throws ClassCastException if the object cannot be added due to its type - * @throws NullPointerException if the object cannot be added because its null - * @throws IllegalArgumentException if the object cannot be added + * @param composite the CompositeCollection being changed. + * @param collections all of the Collection instances in this CompositeCollection. + * @param coll the collection being added. + * @return true if the collection is changed. + * @throws UnsupportedOperationException if add is unsupported. + * @throws ClassCastException if the object cannot be added due to its type. + * @throws NullPointerException if the object cannot be added because its null. + * @throws IllegalArgumentException if the object cannot be added. */ boolean addAll(CompositeCollection<E> composite, List<Collection<E>> collections, @@ -84,14 +84,14 @@ public class CompositeCollection<E> implements Collection<E>, Serializable { /** * Called when an object is to be removed to the composite. * - * @param composite the CompositeCollection being changed - * @param collections all of the Collection instances in this CompositeCollection - * @param obj the object being removed - * @return true if the collection is changed - * @throws UnsupportedOperationException if removed is unsupported - * @throws ClassCastException if the object cannot be removed due to its type - * @throws NullPointerException if the object cannot be removed because its null - * @throws IllegalArgumentException if the object cannot be removed + * @param composite the CompositeCollection being changed. + * @param collections all of the Collection instances in this CompositeCollection. + * @param obj the object being removed. + * @return true if the collection is changed. + * @throws UnsupportedOperationException if removed is unsupported. + * @throws ClassCastException if the object cannot be removed due to its type. + * @throws NullPointerException if the object cannot be removed because its null. + * @throws IllegalArgumentException if the object cannot be removed. */ boolean remove(CompositeCollection<E> composite, List<Collection<E>> collections, @@ -99,44 +99,44 @@ public class CompositeCollection<E> implements Collection<E>, Serializable { } - /** Serialization version */ + /** Serialization version. */ private static final long serialVersionUID = 8417515734108306801L; - /** CollectionMutator to handle changes to the collection */ + /** CollectionMutator to handle changes to the collection. */ private CollectionMutator<E> mutator; - /** Collections in the composite */ + /** Collections in the composite. */ private final List<Collection<E>> all = new ArrayList<>(); /** - * Create an empty CompositeCollection. + * Constructs an empty CompositeCollection. */ public CompositeCollection() { } /** - * Create a Composite Collection with one collection. + * Constructs a Composite Collection with one collection. * - * @param compositeCollection the Collection to be appended to the composite + * @param compositeCollection the Collection to be appended to the composite. */ public CompositeCollection(final Collection<E> compositeCollection) { addComposited(compositeCollection); } /** - * Create a Composite Collection with an array of collections. + * Constructs a Composite Collection with an array of collections. * - * @param compositeCollections the collections to composite + * @param compositeCollections the collections to composite. */ public CompositeCollection(final Collection<E>... compositeCollections) { addComposited(compositeCollections); } /** - * Create a Composite Collection with two collections. + * Constructs a Composite Collection with two collections. * - * @param compositeCollection1 the Collection to be appended to the composite - * @param compositeCollection2 the Collection to be appended to the composite + * @param compositeCollection1 the Collection to be appended to the composite. + * @param compositeCollection2 the Collection to be appended to the composite. */ public CompositeCollection(final Collection<E> compositeCollection1, final Collection<E> compositeCollection2) { @@ -147,13 +147,13 @@ public class CompositeCollection<E> implements Collection<E>, Serializable { * Adds an object to the collection, throwing UnsupportedOperationException * unless a CollectionMutator strategy is specified. * - * @param obj the object to add - * @return {@code true} if the collection was modified - * @throws UnsupportedOperationException if CollectionMutator hasn't been set - * @throws UnsupportedOperationException if add is unsupported - * @throws ClassCastException if the object cannot be added due to its type - * @throws NullPointerException if the object cannot be added because its null - * @throws IllegalArgumentException if the object cannot be added + * @param obj the object to add. + * @return {@code true} if the collection was modified. + * @throws UnsupportedOperationException if CollectionMutator hasn't been set. + * @throws UnsupportedOperationException if add is unsupported. + * @throws ClassCastException if the object cannot be added due to its type. + * @throws NullPointerException if the object cannot be added because its null. + * @throws IllegalArgumentException if the object cannot be added. */ @Override public boolean add(final E obj) { @@ -168,13 +168,13 @@ public class CompositeCollection<E> implements Collection<E>, Serializable { * Adds a collection of elements to this collection, throwing * UnsupportedOperationException unless a CollectionMutator strategy is specified. * - * @param coll the collection to add - * @return true if the collection was modified - * @throws UnsupportedOperationException if CollectionMutator hasn't been set - * @throws UnsupportedOperationException if add is unsupported - * @throws ClassCastException if the object cannot be added due to its type - * @throws NullPointerException if the object cannot be added because its null - * @throws IllegalArgumentException if the object cannot be added + * @param coll the collection to add. + * @return true if the collection was modified. + * @throws UnsupportedOperationException if CollectionMutator hasn't been set. + * @throws UnsupportedOperationException if add is unsupported. + * @throws ClassCastException if the object cannot be added due to its type. + * @throws NullPointerException if the object cannot be added because its null. + * @throws IllegalArgumentException if the object cannot be added. */ @Override public boolean addAll(final Collection<? extends E> coll) { @@ -188,7 +188,7 @@ public class CompositeCollection<E> implements Collection<E>, Serializable { /** * Add these Collections to the list of collections in this composite * - * @param compositeCollection the Collection to be appended to the composite + * @param compositeCollection the Collection to be appended to the composite. */ public void addComposited(final Collection<E> compositeCollection) { if (compositeCollection != null) { @@ -199,7 +199,7 @@ public class CompositeCollection<E> implements Collection<E>, Serializable { /** * Add these Collections to the list of collections in this composite * - * @param compositeCollections the Collections to be appended to the composite + * @param compositeCollections the Collections to be appended to the composite. */ public void addComposited(final Collection<E>... compositeCollections) { Stream.of(compositeCollections).filter(Objects::nonNull).forEach(all::add); @@ -208,8 +208,8 @@ public class CompositeCollection<E> implements Collection<E>, Serializable { /** * Add these Collections to the list of collections in this composite * - * @param compositeCollection1 the Collection to be appended to the composite - * @param compositeCollection2 the Collection to be appended to the composite + * @param compositeCollection1 the Collection to be appended to the composite. + * @param compositeCollection2 the Collection to be appended to the composite. */ public void addComposited(final Collection<E> compositeCollection1, final Collection<E> compositeCollection2) { @@ -240,8 +240,8 @@ public class CompositeCollection<E> implements Collection<E>, Serializable { * This implementation calls {@code contains()} on each collection. * </p> * - * @param obj the object to search for - * @return true if obj is contained in any of the contained collections + * @param obj the object to search for. + * @return true if obj is contained in any of the contained collections. */ @Override public boolean contains(final Object obj) { @@ -255,8 +255,8 @@ public class CompositeCollection<E> implements Collection<E>, Serializable { * specified collection. * </p> * - * @param coll the collection to check for - * @return true if all elements contained + * @param coll the collection to check for. + * @return true if all elements contained. */ @Override public boolean containsAll(final Collection<?> coll) { @@ -319,12 +319,12 @@ public class CompositeCollection<E> implements Collection<E>, Serializable { * Removes an object from the collection, throwing UnsupportedOperationException * unless a CollectionMutator strategy is specified. * - * @param obj the object being removed - * @return true if the collection is changed - * @throws UnsupportedOperationException if removed is unsupported - * @throws ClassCastException if the object cannot be removed due to its type - * @throws NullPointerException if the object cannot be removed because its null - * @throws IllegalArgumentException if the object cannot be removed + * @param obj the object being removed. + * @return true if the collection is changed. + * @throws UnsupportedOperationException if removed is unsupported. + * @throws ClassCastException if the object cannot be removed due to its type. + * @throws NullPointerException if the object cannot be removed because its null. + * @throws IllegalArgumentException if the object cannot be removed. */ @Override public boolean remove(final Object obj) { @@ -340,9 +340,9 @@ public class CompositeCollection<E> implements Collection<E>, Serializable { * This implementation calls {@code removeAll} on each collection. * </p> * - * @param coll the collection to remove - * @return true if the collection was modified - * @throws UnsupportedOperationException if removeAll is unsupported + * @param coll the collection to remove. + * @return true if the collection was modified. + * @throws UnsupportedOperationException if removeAll is unsupported. */ @Override public boolean removeAll(final Collection<?> coll) { @@ -359,7 +359,7 @@ public class CompositeCollection<E> implements Collection<E>, Serializable { /** * Removes a collection from the those being decorated in this composite. * - * @param coll collection to be removed + * @param coll collection to be removed. */ public void removeComposited(final Collection<E> coll) { all.remove(coll); @@ -371,9 +371,9 @@ public class CompositeCollection<E> implements Collection<E>, Serializable { * This implementation calls {@code removeIf} on each collection. * </p> * - * @param filter a predicate which returns true for elements to be removed - * @return true if the collection was modified - * @throws UnsupportedOperationException if removeIf is unsupported + * @param filter a predicate which returns true for elements to be removed. + * @return true if the collection was modified. + * @throws UnsupportedOperationException if removeIf is unsupported. * @since 4.4 */ @Override @@ -395,9 +395,9 @@ public class CompositeCollection<E> implements Collection<E>, Serializable { * This implementation calls {@code retainAll()} on each collection. * </p> * - * @param coll the collection to remove - * @return true if the collection was modified - * @throws UnsupportedOperationException if retainAll is unsupported + * @param coll the collection to remove. + * @return true if the collection was modified. + * @throws UnsupportedOperationException if retainAll is unsupported. */ @Override public boolean retainAll(final Collection<?> coll) { @@ -425,7 +425,7 @@ public class CompositeCollection<E> implements Collection<E>, Serializable { * This implementation calls {@code size()} on each collection. * </p> * - * @return total number of elements in all contained containers + * @return total number of elements in all contained containers. */ @Override public int size() { @@ -439,7 +439,7 @@ public class CompositeCollection<E> implements Collection<E>, Serializable { /** * Returns an array containing all of the elements in this composite. * - * @return an object array of all the elements in the collection + * @return an object array of all the elements in the collection. */ @Override public Object[] toArray() { @@ -455,9 +455,9 @@ public class CompositeCollection<E> implements Collection<E>, Serializable { * Returns an object array, populating the supplied array if possible. * See {@code Collection} interface for full details. * - * @param <T> the type of the elements in the collection - * @param array the array to use, populating if possible - * @return an array of all the elements in the collection + * @param <T> the type of the elements in the collection. + * @param array the array to use, populating if possible. + * @return an array of all the elements in the collection. */ @Override @SuppressWarnings("unchecked") @@ -483,7 +483,7 @@ public class CompositeCollection<E> implements Collection<E>, Serializable { } /** - * Returns a new collection containing all of the elements + * Returns a new collection containing all of the elements. * * @return A new ArrayList containing all of the elements in this composite. * The new collection is <em>not</em> backed by this composite. diff --git a/src/main/java/org/apache/commons/collections4/collection/IndexedCollection.java b/src/main/java/org/apache/commons/collections4/collection/IndexedCollection.java index 822b823e5..b65acf24a 100644 --- a/src/main/java/org/apache/commons/collections4/collection/IndexedCollection.java +++ b/src/main/java/org/apache/commons/collections4/collection/IndexedCollection.java @@ -52,7 +52,7 @@ public class IndexedCollection<K, C> extends AbstractCollectionDecorator<C> { private static final long serialVersionUID = -5512610452568370038L; /** - * Create an {@link IndexedCollection} for a non-unique index. + * Creates an {@link IndexedCollection} for a non-unique index. * * @param <K> the index object type. * @param <C> the collection type. @@ -68,10 +68,11 @@ public class IndexedCollection<K, C> extends AbstractCollectionDecorator<C> { } /** - * Create an {@link IndexedCollection} for a unique index. + * Creates an {@link IndexedCollection} for a unique index. * <p> * If an element is added, which maps to an existing key, an {@link IllegalArgumentException} * will be thrown. + * </p> * * @param <K> the index object type. * @param <C> the collection type. @@ -98,10 +99,10 @@ public class IndexedCollection<K, C> extends AbstractCollectionDecorator<C> { /** * Create a {@link IndexedCollection}. * - * @param coll decorated {@link Collection} - * @param keyTransformer {@link Transformer} for generating index keys - * @param map map to use as index - * @param uniqueIndex if the index shall enforce uniqueness of index keys + * @param coll decorated {@link Collection}. + * @param keyTransformer {@link Transformer} for generating index keys. + * @param map map to use as index. + * @param uniqueIndex if the index shall enforce uniqueness of index keys. */ public IndexedCollection(final Collection<C> coll, final Transformer<C, K> keyTransformer, final MultiMap<K, C> map, final boolean uniqueIndex) { @@ -116,7 +117,7 @@ public class IndexedCollection<K, C> extends AbstractCollectionDecorator<C> { * {@inheritDoc} * * @throws IllegalArgumentException if the object maps to an existing key and the index - * enforces a uniqueness constraint + * enforces a uniqueness constraint. */ @Override public boolean add(final C object) { @@ -139,9 +140,9 @@ public class IndexedCollection<K, C> extends AbstractCollectionDecorator<C> { /** * Provides checking for adding the index. * - * @param object the object to index + * @param object the object to index. * @throws IllegalArgumentException if the object maps to an existing key and the index - * enforces a uniqueness constraint + * enforces a uniqueness constraint. */ private void addToIndex(final C object) { final K key = keyTransformer.apply(object); @@ -160,7 +161,7 @@ public class IndexedCollection<K, C> extends AbstractCollectionDecorator<C> { /** * {@inheritDoc} * <p> - * Note: uses the index for fast lookup + * Note: uses the index for fast lookup. */ @SuppressWarnings("unchecked") @Override @@ -171,7 +172,7 @@ public class IndexedCollection<K, C> extends AbstractCollectionDecorator<C> { /** * {@inheritDoc} * <p> - * Note: uses the index for fast lookup + * Note: uses the index for fast lookup. */ @Override public boolean containsAll(final Collection<?> coll) { @@ -189,6 +190,7 @@ public class IndexedCollection<K, C> extends AbstractCollectionDecorator<C> { * In case of a non-unique index, this method will return the first * value associated with the given key. To retrieve all elements associated * with a key, use {@link #values(Object)}. + * </p> * * @param key key to look up * @return element found @@ -272,8 +274,8 @@ public class IndexedCollection<K, C> extends AbstractCollectionDecorator<C> { /** * Gets all elements associated with the given key. * - * @param key key to look up - * @return a collection of elements found, or null if {@code contains(key) == false} + * @param key key to look up. + * @return a collection of elements found, or null if {@code contains(key) == false}. */ @SuppressWarnings("unchecked") // index is a MultiMap which returns a Collection public Collection<C> values(final K key) { diff --git a/src/main/java/org/apache/commons/collections4/collection/PredicatedCollection.java b/src/main/java/org/apache/commons/collections4/collection/PredicatedCollection.java index 16d6095e0..767433058 100644 --- a/src/main/java/org/apache/commons/collections4/collection/PredicatedCollection.java +++ b/src/main/java/org/apache/commons/collections4/collection/PredicatedCollection.java @@ -59,7 +59,7 @@ import org.apache.commons.collections4.set.PredicatedSet; * This class is Serializable from Commons Collections 3.1. * </p> * - * @param <E> the type of the elements in the collection + * @param <E> the type of the elements in the collection. * @since 3.0 */ public class PredicatedCollection<E> extends AbstractCollectionDecorator<E> { @@ -87,7 +87,7 @@ public class PredicatedCollection<E> extends AbstractCollectionDecorator<E> { * More elements can be added to the builder once a predicated collection has been created, * but these elements will not be reflected in already created collections. * - * @param <E> the element type + * @param <E> the element type. * @since 4.1 */ public static class Builder<E> { @@ -104,8 +104,8 @@ public class PredicatedCollection<E> extends AbstractCollectionDecorator<E> { /** * Constructs a PredicatedCollectionBuilder with the specified Predicate. * - * @param predicate the predicate to use - * @throws NullPointerException if predicate is null + * @param predicate the predicate to use. + * @throws NullPointerException if predicate is null. */ public Builder(final Predicate<? super E> predicate) { this.predicate = Objects.requireNonNull(predicate, "predicate"); @@ -116,8 +116,9 @@ public class PredicatedCollection<E> extends AbstractCollectionDecorator<E> { * <p> * If the predicate is true, it is added to the list of accepted elements, * otherwise it is added to the rejected list. + * </p> * - * @param item the element to add + * @param item the element to add. * @return the PredicatedCollectionBuilder. */ public Builder<E> add(final E item) { @@ -134,8 +135,9 @@ public class PredicatedCollection<E> extends AbstractCollectionDecorator<E> { * <p> * All elements for which the predicate evaluates to true will be added to the * list of accepted elements, otherwise they are added to the rejected list. + * </p> * - * @param items the elements to add to the builder + * @param items the elements to add to the builder. * @return the PredicatedCollectionBuilder. */ public Builder<E> addAll(final Collection<? extends E> items) { @@ -150,6 +152,7 @@ public class PredicatedCollection<E> extends AbstractCollectionDecorator<E> { * <p> * The builder is not modified by this method, so it is possible to create more collections * or add more elements afterwards. Further changes will not propagate to the returned bag. + * </p> * * @return a new predicated bag. */ @@ -163,11 +166,12 @@ public class PredicatedCollection<E> extends AbstractCollectionDecorator<E> { * <p> * The builder is not modified by this method, so it is possible to create more collections * or add more elements afterwards. Further changes will not propagate to the returned bag. + * </p> * - * @param bag the bag to decorate, must not be null + * @param bag the bag to decorate, must not be null. * @return the decorated bag. - * @throws NullPointerException if bag is null - * @throws IllegalArgumentException if bag contains invalid elements + * @throws NullPointerException if bag is null. + * @throws IllegalArgumentException if bag contains invalid elements. */ public Bag<E> createPredicatedBag(final Bag<E> bag) { Objects.requireNonNull(bag, "bag"); @@ -181,6 +185,7 @@ public class PredicatedCollection<E> extends AbstractCollectionDecorator<E> { * <p> * The builder is not modified by this method, so it is possible to create more collections * or add more elements afterwards. Further changes will not propagate to the returned list. + * </p> * * @return a new predicated list. */ @@ -194,11 +199,12 @@ public class PredicatedCollection<E> extends AbstractCollectionDecorator<E> { * <p> * The builder is not modified by this method, so it is possible to create more collections * or add more elements afterwards. Further changes will not propagate to the returned list. + * </p> * - * @param list the List to decorate, must not be null + * @param list the List to decorate, must not be null. * @return the decorated list. - * @throws NullPointerException if list is null - * @throws IllegalArgumentException if list contains invalid elements + * @throws NullPointerException if list is null. + * @throws IllegalArgumentException if list contains invalid elements. */ public List<E> createPredicatedList(final List<E> list) { Objects.requireNonNull(list, "list"); @@ -212,6 +218,7 @@ public class PredicatedCollection<E> extends AbstractCollectionDecorator<E> { * <p> * The builder is not modified by this method, so it is possible to create more collections * or add more elements afterwards. Further changes will not propagate to the returned multiset. + * </p> * * @return a new predicated multiset. */ @@ -225,11 +232,12 @@ public class PredicatedCollection<E> extends AbstractCollectionDecorator<E> { * <p> * The builder is not modified by this method, so it is possible to create more collections * or add more elements afterwards. Further changes will not propagate to the returned multiset. + * </p> * - * @param multiset the multiset to decorate, must not be null + * @param multiset the multiset to decorate, must not be null. * @return the decorated multiset. - * @throws NullPointerException if multiset is null - * @throws IllegalArgumentException if multiset contains invalid elements + * @throws NullPointerException if multiset is null. + * @throws IllegalArgumentException if multiset contains invalid elements. */ public MultiSet<E> createPredicatedMultiSet(final MultiSet<E> multiset) { Objects.requireNonNull(multiset, "multiset"); @@ -243,6 +251,7 @@ public class PredicatedCollection<E> extends AbstractCollectionDecorator<E> { * <p> * The builder is not modified by this method, so it is possible to create more collections * or add more elements afterwards. Further changes will not propagate to the returned queue. + * </p> * * @return a new predicated queue. */ @@ -256,11 +265,12 @@ public class PredicatedCollection<E> extends AbstractCollectionDecorator<E> { * <p> * The builder is not modified by this method, so it is possible to create more collections * or add more elements afterwards. Further changes will not propagate to the returned queue. + * </p> * - * @param queue the queue to decorate, must not be null + * @param queue the queue to decorate, must not be null. * @return the decorated queue. - * @throws NullPointerException if queue is null - * @throws IllegalArgumentException if queue contains invalid elements + * @throws NullPointerException if queue is null. + * @throws IllegalArgumentException if queue contains invalid elements. */ public Queue<E> createPredicatedQueue(final Queue<E> queue) { Objects.requireNonNull(queue, "queue"); @@ -274,6 +284,7 @@ public class PredicatedCollection<E> extends AbstractCollectionDecorator<E> { * <p> * The builder is not modified by this method, so it is possible to create more collections * or add more elements afterwards. Further changes will not propagate to the returned set. + * </p> * * @return a new predicated set. */ @@ -287,11 +298,12 @@ public class PredicatedCollection<E> extends AbstractCollectionDecorator<E> { * <p> * The builder is not modified by this method, so it is possible to create more collections * or add more elements afterwards. Further changes will not propagate to the returned set. + * </p> * - * @param set the set to decorate, must not be null + * @param set the set to decorate, must not be null. * @return the decorated set. - * @throws NullPointerException if set is null - * @throws IllegalArgumentException if set contains invalid elements + * @throws NullPointerException if set is null. + * @throws IllegalArgumentException if set contains invalid elements. */ public Set<E> createPredicatedSet(final Set<E> set) { Objects.requireNonNull(set, "set"); @@ -303,7 +315,7 @@ public class PredicatedCollection<E> extends AbstractCollectionDecorator<E> { /** * Returns an unmodifiable collection containing all rejected elements. * - * @return an unmodifiable collection + * @return an unmodifiable collection. */ public Collection<E> rejectedElements() { return Collections.unmodifiableCollection(rejected); @@ -317,9 +329,9 @@ public class PredicatedCollection<E> extends AbstractCollectionDecorator<E> { /** * Returns a Builder with the given predicate. * - * @param <E> the element type - * @param predicate the predicate to use - * @return a new Builder for predicated collections + * @param <E> the element type. + * @param predicate the predicate to use. + * @return a new Builder for predicated collections. * @since 4.1 */ public static <E> Builder<E> builder(final Predicate<? super E> predicate) { @@ -329,7 +341,7 @@ public class PredicatedCollection<E> extends AbstractCollectionDecorator<E> { /** * Returns a Builder with a NotNullPredicate. * - * @param <E> the element type + * @param <E> the element type. * @return a new Builder for predicated collections that ignores null values. * @since 4.1 */ @@ -342,13 +354,14 @@ public class PredicatedCollection<E> extends AbstractCollectionDecorator<E> { * <p> * If there are any elements already in the collection being decorated, they * are validated. + * </p> * - * @param <T> the type of the elements in the collection - * @param coll the collection to decorate, must not be null - * @param predicate the predicate to use for validation, must not be null - * @return a new predicated collection - * @throws NullPointerException if collection or predicate is null - * @throws IllegalArgumentException if the collection contains invalid elements + * @param <T> the type of the elements in the collection. + * @param coll the collection to decorate, must not be null. + * @param predicate the predicate to use for validation, must not be null. + * @return a new predicated collection. + * @throws NullPointerException if collection or predicate is null. + * @throws IllegalArgumentException if the collection contains invalid elements. * @since 4.0 */ public static <T> PredicatedCollection<T> predicatedCollection(final Collection<T> coll, @@ -364,11 +377,12 @@ public class PredicatedCollection<E> extends AbstractCollectionDecorator<E> { * <p> * If there are any elements already in the collection being decorated, they * are validated. + * </p> * - * @param collection the collection to decorate, must not be null - * @param predicate the predicate to use for validation, must not be null - * @throws NullPointerException if collection or predicate is null - * @throws IllegalArgumentException if the collection contains invalid elements + * @param collection the collection to decorate, must not be null. + * @param predicate the predicate to use for validation, must not be null. + * @throws NullPointerException if collection or predicate is null. + * @throws IllegalArgumentException if the collection contains invalid elements. */ protected PredicatedCollection(final Collection<E> collection, final Predicate<? super E> predicate) { super(collection); @@ -380,9 +394,9 @@ public class PredicatedCollection<E> extends AbstractCollectionDecorator<E> { * Override to validate the object being added to ensure it matches * the predicate. * - * @param object the object being added - * @return the result of adding to the underlying collection - * @throws IllegalArgumentException if the add is invalid + * @param object the object being added. + * @return the result of adding to the underlying collection. + * @throws IllegalArgumentException if the add is invalid. */ @Override public boolean add(final E object) { @@ -395,9 +409,9 @@ public class PredicatedCollection<E> extends AbstractCollectionDecorator<E> { * the predicate. If anyone fails, no update is made to the underlying * collection. * - * @param coll the collection being added - * @return the result of adding to the underlying collection - * @throws IllegalArgumentException if the add is invalid + * @param coll the collection being added. + * @return the result of adding to the underlying collection. + * @throws IllegalArgumentException if the add is invalid. */ @Override public boolean addAll(final Collection<? extends E> coll) { @@ -408,9 +422,9 @@ public class PredicatedCollection<E> extends AbstractCollectionDecorator<E> { /** * Deserializes the collection in using a custom routine. * - * @param in the input stream - * @throws IOException if an error occurs while reading from the stream - * @throws ClassNotFoundException if an object read from the stream cannot be loaded + * @param in the input stream. + * @throws IOException if an error occurs while reading from the stream. + * @throws ClassNotFoundException if an object read from the stream cannot be loaded. */ private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException { in.defaultReadObject(); @@ -432,9 +446,10 @@ public class PredicatedCollection<E> extends AbstractCollectionDecorator<E> { * <p> * The predicate itself should not throw an exception, but return false to * indicate that the object cannot be added. + * </p> * - * @param object the object being added - * @throws IllegalArgumentException if the add is invalid + * @param object the object being added. + * @throws IllegalArgumentException if the add is invalid. */ protected void validate(final E object) { if (!predicate.test(object)) { diff --git a/src/main/java/org/apache/commons/collections4/collection/SynchronizedCollection.java b/src/main/java/org/apache/commons/collections4/collection/SynchronizedCollection.java index dbe9d50d9..88f66920e 100644 --- a/src/main/java/org/apache/commons/collections4/collection/SynchronizedCollection.java +++ b/src/main/java/org/apache/commons/collections4/collection/SynchronizedCollection.java @@ -47,7 +47,7 @@ public class SynchronizedCollection<E> implements Collection<E>, Serializable { private static final long serialVersionUID = 2412805092710877986L; /** - * Factory method to create a synchronized collection. + * Creates a synchronized collection. * * @param <T> the type of the elements in the collection * @param coll the collection to decorate, must not be null @@ -66,7 +66,7 @@ public class SynchronizedCollection<E> implements Collection<E>, Serializable { protected final Object lock; /** - * Constructor that wraps (not copies). + * Constructs and wraps (not copies). * * @param collection the collection to decorate, must not be null * @throws NullPointerException if the collection is null @@ -77,7 +77,7 @@ public class SynchronizedCollection<E> implements Collection<E>, Serializable { } /** - * Constructor that wraps (not copies). + * Constructs and wraps (not copies). * * @param collection the collection to decorate, must not be null * @param lock the lock object to use, must not be null diff --git a/src/main/java/org/apache/commons/collections4/collection/TransformedCollection.java b/src/main/java/org/apache/commons/collections4/collection/TransformedCollection.java index e101b5a71..d87077cb7 100644 --- a/src/main/java/org/apache/commons/collections4/collection/TransformedCollection.java +++ b/src/main/java/org/apache/commons/collections4/collection/TransformedCollection.java @@ -35,7 +35,7 @@ import org.apache.commons.collections4.Transformer; * This class is Serializable from Commons Collections 3.1. * </p> * - * @param <E> the type of the elements in the collection + * @param <E> the type of the elements in the collection. * @since 3.0 */ public class TransformedCollection<E> extends AbstractCollectionDecorator<E> { @@ -44,18 +44,19 @@ public class TransformedCollection<E> extends AbstractCollectionDecorator<E> { private static final long serialVersionUID = 8692300188161871514L; /** - * Factory method to create a transforming collection that will transform + * Creates a transforming collection that will transform * existing contents of the specified collection. * <p> * If there are any elements already in the collection being decorated, they * will be transformed by this method. * Contrast this with {@link #transformingCollection(Collection, Transformer)}. + * </p> * - * @param <E> the type of the elements in the collection - * @param collection the collection to decorate, must not be null - * @param transformer the transformer to use for conversion, must not be null - * @return a new transformed Collection - * @throws NullPointerException if collection or transformer is null + * @param <E> the type of the elements in the collection. + * @param collection the collection to decorate, must not be null. + * @param transformer the transformer to use for conversion, must not be null. + * @return a new transformed Collection. + * @throws NullPointerException if collection or transformer is null. * @since 4.0 */ public static <E> TransformedCollection<E> transformedCollection(final Collection<E> collection, @@ -75,17 +76,18 @@ public class TransformedCollection<E> extends AbstractCollectionDecorator<E> { } /** - * Factory method to create a transforming collection. + * Creates a transforming collection. * <p> * If there are any elements already in the collection being decorated, they * are NOT transformed. * Contrast this with {@link #transformedCollection(Collection, Transformer)}. + * </p> * - * @param <E> the type of the elements in the collection - * @param coll the collection to decorate, must not be null - * @param transformer the transformer to use for conversion, must not be null - * @return a new transformed collection - * @throws NullPointerException if collection or transformer is null + * @param <E> the type of the elements in the collection. + * @param coll the collection to decorate, must not be null. + * @param transformer the transformer to use for conversion, must not be null. + * @return a new transformed collection. + * @throws NullPointerException if collection or transformer is null. * @since 4.0 */ public static <E> TransformedCollection<E> transformingCollection(final Collection<E> coll, @@ -97,14 +99,15 @@ public class TransformedCollection<E> extends AbstractCollectionDecorator<E> { protected final Transformer<? super E, ? extends E> transformer; /** - * Constructor that wraps (not copies). + * Constructs and wraps (not copies). * <p> * If there are any elements already in the collection being decorated, they * are NOT transformed. + * </p> * - * @param collection the collection to decorate, must not be null - * @param transformer the transformer to use for conversion, must not be null - * @throws NullPointerException if collection or transformer is null + * @param collection the collection to decorate, must not be null. + * @param transformer the transformer to use for conversion, must not be null. + * @throws NullPointerException if collection or transformer is null. */ protected TransformedCollection(final Collection<E> collection, final Transformer<? super E, ? extends E> transformer) { super(collection); @@ -125,9 +128,10 @@ public class TransformedCollection<E> extends AbstractCollectionDecorator<E> { * Transforms a collection. * <p> * The transformer itself may throw an exception if necessary. + * </p> * - * @param coll the collection to transform - * @return a transformed object + * @param coll the collection to transform. + * @return a transformed object. */ protected Collection<E> transform(final Collection<? extends E> coll) { final List<E> list = new ArrayList<>(coll.size()); @@ -141,9 +145,10 @@ public class TransformedCollection<E> extends AbstractCollectionDecorator<E> { * Transforms an object. * <p> * The transformer itself may throw an exception if necessary. + * </p> * - * @param object the object to transform - * @return a transformed object + * @param object the object to transform. + * @return a transformed object. */ protected E transform(final E object) { return transformer.apply(object); diff --git a/src/main/java/org/apache/commons/collections4/collection/UnmodifiableBoundedCollection.java b/src/main/java/org/apache/commons/collections4/collection/UnmodifiableBoundedCollection.java index 54cb90073..61c96675e 100644 --- a/src/main/java/org/apache/commons/collections4/collection/UnmodifiableBoundedCollection.java +++ b/src/main/java/org/apache/commons/collections4/collection/UnmodifiableBoundedCollection.java @@ -52,12 +52,12 @@ public final class UnmodifiableBoundedCollection<E> extends AbstractCollectionDe private static final long serialVersionUID = -7112672385450340330L; /** - * Factory method to create an unmodifiable bounded collection. + * Creates an unmodifiable bounded collection. * - * @param <E> the type of the elements in the collection - * @param coll the {@code BoundedCollection} to decorate, must not be null - * @return a new unmodifiable bounded collection - * @throws NullPointerException if {@code coll} is {@code null} + * @param <E> the type of the elements in the collection. + * @param coll the {@code BoundedCollection} to decorate, must not be null. + * @return a new unmodifiable bounded collection. + * @throws NullPointerException if {@code coll} is {@code null}. * @since 4.0 */ public static <E> BoundedCollection<E> unmodifiableBoundedCollection(final BoundedCollection<? extends E> coll) { @@ -70,16 +70,17 @@ public final class UnmodifiableBoundedCollection<E> extends AbstractCollectionDe } /** - * Factory method to create an unmodifiable bounded collection. + * Creates an unmodifiable bounded collection. * <p> * This method is capable of drilling down through up to 1000 other decorators * to find a suitable BoundedCollection. + * </p> * - * @param <E> the type of the elements in the collection - * @param collection the {@code BoundedCollection} to decorate, must not be null - * @return a new unmodifiable bounded collection - * @throws NullPointerException if coll is null - * @throws IllegalArgumentException if coll is not a {@code BoundedCollection} + * @param <E> the type of the elements in the collection. + * @param collection the {@code BoundedCollection} to decorate, must not be null. + * @return a new unmodifiable bounded collection. + * @throws NullPointerException if coll is null. + * @throws IllegalArgumentException if coll is not a {@code BoundedCollection}. * @since 4.0 */ @SuppressWarnings("unchecked") @@ -105,10 +106,10 @@ public final class UnmodifiableBoundedCollection<E> extends AbstractCollectionDe } /** - * Constructor that wraps (not copies). + * Constructs and wraps (not copies). * - * @param coll the collection to decorate, must not be null - * @throws NullPointerException if coll is null + * @param coll the collection to decorate, must not be null. + * @throws NullPointerException if coll is null. */ @SuppressWarnings("unchecked") // safe to upcast private UnmodifiableBoundedCollection(final BoundedCollection<? extends E> coll) { diff --git a/src/main/java/org/apache/commons/collections4/collection/UnmodifiableCollection.java b/src/main/java/org/apache/commons/collections4/collection/UnmodifiableCollection.java index f2c6bc622..672d753ec 100644 --- a/src/main/java/org/apache/commons/collections4/collection/UnmodifiableCollection.java +++ b/src/main/java/org/apache/commons/collections4/collection/UnmodifiableCollection.java @@ -43,14 +43,15 @@ public final class UnmodifiableCollection<E> private static final long serialVersionUID = -239892006883819945L; /** - * Factory method to create an unmodifiable collection. + * Creates an unmodifiable collection. * <p> * If the collection passed in is already unmodifiable, it is returned. + * </p> * - * @param <T> the type of the elements in the collection - * @param coll the collection to decorate, must not be null - * @return an unmodifiable collection - * @throws NullPointerException if collection is null + * @param <T> the type of the elements in the collection. + * @param coll the collection to decorate, must not be null. + * @return an unmodifiable collection. + * @throws NullPointerException if collection is null. * @since 4.0 */ public static <T> Collection<T> unmodifiableCollection(final Collection<? extends T> coll) { @@ -63,10 +64,10 @@ public final class UnmodifiableCollection<E> } /** - * Constructor that wraps (not copies). + * Constructs and wraps (not copies). * - * @param coll the collection to decorate, must not be null - * @throws NullPointerException if collection is null + * @param coll the collection to decorate, must not be null. + * @throws NullPointerException if collection is null. */ @SuppressWarnings("unchecked") // safe to upcast private UnmodifiableCollection(final Collection<? extends E> coll) {
