diff --git a/src/main/java/org/apache/commons/collections4/ClosureUtils.java b/src/main/java/org/apache/commons/collections4/ClosureUtils.java index def04ea9c9..fe190eb86d 100644 --- a/src/main/java/org/apache/commons/collections4/ClosureUtils.java +++ b/src/main/java/org/apache/commons/collections4/ClosureUtils.java @@ -253,6 +253,7 @@ public static Closure nopClosure() { * closure is called. The default closure is set in the map with a * null key. The ordering is that of the iterator() method on the entryset * collection of the map. + *

* * @see org.apache.commons.collections4.functors.SwitchClosure * @@ -275,6 +276,7 @@ public static Closure switchClosure(final Map, Closure> p * The closure at array location 0 is called if the predicate at array * location 0 returned true. Each predicate is evaluated * until one returns true. + *

* * @see org.apache.commons.collections4.functors.SwitchClosure * @@ -299,6 +301,7 @@ public static Closure switchClosure(final Predicate[] predicat * location 0 returned true. Each predicate is evaluated * until one returns true. If no predicates evaluate to true, the default * closure is called. + *

* * @see org.apache.commons.collections4.functors.SwitchClosure * @@ -325,6 +328,7 @@ public static Closure switchClosure(final Predicate[] predicat * is called if the input object equals the key. If there is no match, the * default closure is called. The default closure is set in the map * using a null key. + *

* * @see org.apache.commons.collections4.functors.SwitchClosure * diff --git a/src/main/java/org/apache/commons/collections4/CollectionUtils.java b/src/main/java/org/apache/commons/collections4/CollectionUtils.java index 3aed6feae5..49d7cf38a0 100644 --- a/src/main/java/org/apache/commons/collections4/CollectionUtils.java +++ b/src/main/java/org/apache/commons/collections4/CollectionUtils.java @@ -225,6 +225,7 @@ public void setCardinality(final O obj, final int count) { * @since 4.5.0 */ public static final int INDEX_NOT_FOUND = -1; + /** * Default prefix used while converting an Iterator to its String representation. * @@ -461,11 +462,9 @@ public static List collate(final Iterable a, final Iterable< */ public static List collate(final Iterable iterableA, final Iterable iterableB, final Comparator comparator, final boolean includeDuplicates) { - Objects.requireNonNull(iterableA, "iterableA"); Objects.requireNonNull(iterableB, "iterableB"); Objects.requireNonNull(comparator, "comparator"); - // if both Iterables are a Collection, we can estimate the size final int totalSize = iterableA instanceof Collection && iterableB instanceof Collection ? Math.max(1, ((Collection) iterableA).size() + ((Collection) iterableB).size()) : 10; @@ -475,7 +474,6 @@ public static List collate(final Iterable iterableA, final I return IteratorUtils.toList(iterator, totalSize); } final ArrayList mergedList = new ArrayList<>(totalSize); - O lastItem = null; while (iterator.hasNext()) { final O item = iterator.next(); @@ -484,7 +482,6 @@ public static List collate(final Iterable iterableA, final I } lastItem = item; } - mergedList.trimToSize(); return mergedList; } diff --git a/src/main/java/org/apache/commons/collections4/EnumerationUtils.java b/src/main/java/org/apache/commons/collections4/EnumerationUtils.java index 7df8c409e0..b6d27a36dd 100644 --- a/src/main/java/org/apache/commons/collections4/EnumerationUtils.java +++ b/src/main/java/org/apache/commons/collections4/EnumerationUtils.java @@ -50,6 +50,7 @@ public static Iterable asIterable(final Enumeration enumeration) { *

* The Enumeration is advanced to {@code index} (or to the end, if * {@code index} exceeds the number of entries) as a side effect of this method. + *

* * @param e the enumeration to get a value from * @param index the index to get diff --git a/src/main/java/org/apache/commons/collections4/FactoryUtils.java b/src/main/java/org/apache/commons/collections4/FactoryUtils.java index 36d5679448..06f3187f27 100644 --- a/src/main/java/org/apache/commons/collections4/FactoryUtils.java +++ b/src/main/java/org/apache/commons/collections4/FactoryUtils.java @@ -34,6 +34,7 @@ *

* Since v4.1 only factories which are considered to be safe are * Serializable. Factories considered to be unsafe for serialization are: + *

*
    *
  • Prototype *
  • Instantiate diff --git a/src/main/java/org/apache/commons/collections4/FluentIterable.java b/src/main/java/org/apache/commons/collections4/FluentIterable.java index c985d7e575..c58182afb6 100644 --- a/src/main/java/org/apache/commons/collections4/FluentIterable.java +++ b/src/main/java/org/apache/commons/collections4/FluentIterable.java @@ -84,6 +84,7 @@ public static FluentIterable empty() { *

    * The returned iterable's iterator supports {@code remove()} when the * corresponding input iterator supports it. + *

    * * @param the element type * @param iterable the iterable to wrap into a FluentIterable, may not be null @@ -102,6 +103,7 @@ public static FluentIterable of(final Iterable iterable) { * Creates a new FluentIterable of the single provided element. *

    * The returned iterable's iterator does not support {@code remove()}. + *

    * * @param the element type * @param singleton the singleton element @@ -115,6 +117,7 @@ public static FluentIterable of(final T singleton) { * Creates a new FluentIterable from the provided elements. *

    * The returned iterable's iterator does not support {@code remove()}. + *

    * * @param the element type * @param elements the elements to be contained in the FluentIterable @@ -147,6 +150,7 @@ private FluentIterable(final Iterable iterable) { * provided predicate. *

    * A {@code null} or empty iterable returns true. + *

    * * @param predicate the predicate to use, may not be null * @return true if all elements contained in this iterable match the predicate, @@ -161,6 +165,7 @@ public boolean allMatch(final Predicate predicate) { * Checks if this iterable contains any element matching the provided predicate. *

    * A {@code null} or empty iterable returns false. + *

    * * @param predicate the predicate to use, may not be null * @return true if at least one element contained in this iterable matches the predicate, @@ -211,6 +216,7 @@ public Enumeration asEnumeration() { * elements of the current and provided iterable in natural order. *

    * Example: natural ordering + *

    *
      *
    • this contains elements [1, 3, 5, 7] *
    • other contains elements [2, 4, 6, 8] @@ -218,6 +224,7 @@ public Enumeration asEnumeration() { *

      * The returned iterable will traverse the elements in the following * order: [1, 2, 3, 4, 5, 6, 7, 8] + *

      * * @param other the other iterable to collate, may not be null * @return a new iterable, collating this iterable with the other in natural order @@ -234,6 +241,7 @@ public FluentIterable collate(final Iterable other) { * ordering defined by a comparator. *

      * Example: descending order + *

      *
        *
      • this contains elements [7, 5, 3, 1] *
      • other contains elements [8, 6, 4, 2] @@ -241,6 +249,7 @@ public FluentIterable collate(final Iterable other) { *

        * The returned iterable will traverse the elements in the following * order: [8, 7, 6, 5, 4, 3, 2, 1] + *

        * * @param comparator the comparator to define an ordering, may be null, * in which case natural ordering will be used @@ -282,10 +291,12 @@ public void copyInto(final Collection collection) { * to the originating iterables and/or iterators. *

        * Calling this method is equivalent to: + *

        *
              *   FluentIterable<E> someIterable = ...;
              *   FluentIterable.of(someIterable.toList());
              * 
        + *

        * * @return a new iterable with the same contents as this iterable */ @@ -416,6 +427,7 @@ public E[] toArray(final Class arrayClass) { * by traversing its iterator. *

        * The returned list is guaranteed to be mutable. + *

        * * @return a list of the iterable contents */ diff --git a/src/main/java/org/apache/commons/collections4/IterableGet.java b/src/main/java/org/apache/commons/collections4/IterableGet.java index 39b7bcab79..4189821bfd 100644 --- a/src/main/java/org/apache/commons/collections4/IterableGet.java +++ b/src/main/java/org/apache/commons/collections4/IterableGet.java @@ -31,6 +31,7 @@ public interface IterableGet extends Get { *

        * A map iterator is an efficient way of iterating over maps. * There is no need to access the entry set or use Map Entry objects. + *

        *
              * IterableMap<String,Integer> map = new HashedMap<String,Integer>();
              * MapIterator<String,Integer> it = map.mapIterator();
        diff --git a/src/main/java/org/apache/commons/collections4/IteratorUtils.java b/src/main/java/org/apache/commons/collections4/IteratorUtils.java
        index 4bf0829294..1b62492046 100644
        --- a/src/main/java/org/apache/commons/collections4/IteratorUtils.java
        +++ b/src/main/java/org/apache/commons/collections4/IteratorUtils.java
        @@ -536,7 +536,6 @@ public static  Iterator collatedIterator(final Comparator compa
                 return new CollatingIterator<>(comp, iterators);
             }
         
        -    // Collated
             /**
              * Gets an iterator that provides an ordered iteration over the elements
              * contained in a collection of ordered {@link Iterator}s.
        @@ -1070,7 +1069,6 @@ public static NodeListIterator nodeListIterator(final NodeList nodeList) {
                 return new NodeListIterator(Objects.requireNonNull(nodeList, "nodeList"));
             }
         
        -    // Object Graph
             /**
              * Gets an iterator that operates over an object graph.
              * 

        diff --git a/src/main/java/org/apache/commons/collections4/ListUtils.java b/src/main/java/org/apache/commons/collections4/ListUtils.java index 6a02430114..0aeb413053 100644 --- a/src/main/java/org/apache/commons/collections4/ListUtils.java +++ b/src/main/java/org/apache/commons/collections4/ListUtils.java @@ -42,6 +42,7 @@ * @since 1.0 */ public class ListUtils { + /** * A simple wrapper to use a CharSequence as List. */ @@ -178,6 +179,7 @@ public static List fixedSizeList(final List list) { *

        * Shorthand for {@code list.get(0)} *

        + * * @param The list type. * @param list The list. * @return the first element of a list. @@ -193,6 +195,7 @@ public static T getFirst(final List list) { *

        * Shorthand for {@code list.get(list.size() - 1)} *

        + * * @param The list type. * @param list The list. * @return the last element of a list. @@ -210,6 +213,7 @@ public static T getLast(final List list) { * This method is useful for implementing {@code List} when you cannot * extend AbstractList. The method takes Collection instances to enable other * collection types to use the List implementation algorithm. + *

        * * @see java.util.List#hashCode() * @param list the list to generate the hashCode for, may be null @@ -232,6 +236,7 @@ public static int hashCodeForList(final Collection list) { *

        * If the input List or predicate is null, or no element of the List * matches the predicate, -1 is returned. + *

        * * @param the element type * @param list the List to search, may be null @@ -288,8 +293,10 @@ public static List intersection(final List list1, final List * This method is useful for implementing {@code List} when you cannot * extend AbstractList. The method takes Collection instances to enable other * collection types to use the List implementation algorithm. + *

        *

        * The relevant text (slightly paraphrased as this is a static method) is: + *

        *
        * Compares the two list objects for equality. Returns * {@code true} if and only if both @@ -301,9 +308,10 @@ public static List intersection(final List list1, final List * definition ensures that the equals method works properly across * different implementations of the {@code List} interface. *
        - * + *

        * Note: The behavior of this method is undefined if the lists are * modified during the equals comparison. + *

        * * @see java.util.List * @param list1 the first list, may be null @@ -339,9 +347,10 @@ public static boolean isEqualList(final Collection list1, final Collection * When the index passed to the returned list's {@link List#get(int) get} * method is greater than the list's size, then the factory will be used * to create a new object and that object will be inserted at that index. + *

        *

        * For instance: - * + *

        *
              * Factory<Date> factory = new Factory<Date>() {
              *     public Date create() {
        @@ -351,11 +360,12 @@ public static boolean isEqualList(final Collection list1, final Collection
              * List<Date> lazy = ListUtils.lazyList(new ArrayList<Date>(), factory);
              * Date date = lazy.get(3);
              * 
        - * + *

        * After the above code is executed, {@code date} will refer to * a new {@code Date} instance. Furthermore, that {@code Date} * instance is the fourth element in the list. The first, second, * and third element are all set to {@code null}. + *

        * * @param the element type * @param list the list to make lazy, must not be null @@ -373,20 +383,22 @@ public static List lazyList(final List list, final Factory *

        * For instance: - * + *

        *
              * List<Integer> hours = Arrays.asList(7, 5, 8, 2);
              * Transformer<Integer,Date> transformer = input -> LocalDateTime.now().withHour(hours.get(input));
              * List<LocalDateTime> lazy = ListUtils.lazyList(new ArrayList<LocalDateTime>(), transformer);
              * Date date = lazy.get(3);
              * 
        - * + *

        * After the above code is executed, {@code date} will refer to * a new {@code Date} instance. Furthermore, that {@code Date} * instance is the fourth element in the list. The first, second, * and third element are all set to {@code null}. + *

        * * @param the element type * @param list the list to make lazy, must not be null @@ -403,6 +415,7 @@ public static List lazyList(final List list, final Transformer * This is a convenience method for using {@link #longestCommonSubsequence(List, List)} * with {@link CharSequence} instances. + *

        * * @param charSequenceA the first sequence * @param charSequenceB the second sequence @@ -471,8 +484,10 @@ public static List longestCommonSubsequence(final List listA, final Li * source list. The inner lists are sublist views of the original list, * produced on demand using {@link List#subList(int, int)}, and are subject * to all the usual caveats about modification as explained in that API. + *

        *

        * Adapted from https://github.com/google/guava + *

        * * @param the element type * @param list the list to return consecutive sublists of @@ -497,6 +512,7 @@ public static List> partition(final List list, final int size) { * Trying to add an invalid object results in an IllegalArgumentException. * It is important not to use the original list after invoking this method, * as it is a backdoor for adding invalid objects. + *

        * * @param the element type * @param list the list to predicate, must not be null @@ -522,6 +538,7 @@ public static List predicatedList(final List list, final Predicate * to the returned list. As a consequence, it is advised to use a collection type for * {@code remove} that provides a fast (e.g. O(1)) implementation of * {@link Collection#contains(Object)}. + *

        * * @param the element type * @param collection the collection from which items are removed (in the returned collection) @@ -556,6 +573,7 @@ public static List removeAll(final Collection collection, final Collec * to the returned list. As a consequence, it is advised to use a collection type for * {@code retain} that provides a fast (e.g. O(1)) implementation of * {@link Collection#contains(Object)}. + *

        * * @param the element type * @param collection the collection whose contents are the target of the #retailAll operation @@ -581,6 +599,7 @@ public static List retainAll(final Collection collection, final Collec * predicate into an output list. *

        * A {@code null} predicate matches no elements. + *

        * * @param the element type * @param inputCollection the collection to get the input from, may not be null @@ -601,6 +620,7 @@ public static List select(final Collection inputCollection, * predicate into an output collection. *

        * If the input predicate is {@code null}, the result is an empty list. + *

        * * @param the element type * @param inputCollection the collection to get the input from, may not be null @@ -625,6 +645,7 @@ public static List selectRejected(final Collection inputColl * occurrences of null and list2 only * contains one occurrence, then the returned list will still contain * one occurrence. + *

        * * @param the element type * @param list1 the list to subtract from @@ -662,7 +683,7 @@ public static List sum(final List list1, final List * You must manually synchronize on the returned list's iterator to * avoid non-deterministic behavior: - * + *

        *
              * List list = ListUtils.synchronizedList(myList);
              * synchronized (list) {
        @@ -672,8 +693,9 @@ public static  List sum(final List list1, final List
        -     *
        +     * 

        * This method is just a wrapper for {@link Collections#synchronizedList(List)}. + *

        * * @param the element type * @param list the list to synchronize, must not be null @@ -690,13 +712,16 @@ public static List synchronizedList(final List list) { * This method returns a new list (decorating the specified list) that * will transform any new entries added to it. * Existing entries in the specified list will not be transformed. + *

        *

        * Each object is passed through the transformer as it is added to the * List. It is important not to use the original list after invoking this * method, as it is a backdoor for adding untransformed objects. + *

        *

        * Existing entries in the specified list will not be transformed. * If you want that behavior, see {@link TransformedList#transformedList}. + *

        * * @param the element type * @param list the list to predicate, must not be null @@ -731,6 +756,7 @@ public static List union(final List list1, final List * This method uses the implementation in the decorators subpackage. + *

        * * @param the element type * @param list the list to make unmodifiable, must not be null diff --git a/src/main/java/org/apache/commons/collections4/ListValuedMap.java b/src/main/java/org/apache/commons/collections4/ListValuedMap.java index 75079bd328..37174ae5a9 100644 --- a/src/main/java/org/apache/commons/collections4/ListValuedMap.java +++ b/src/main/java/org/apache/commons/collections4/ListValuedMap.java @@ -41,6 +41,7 @@ public interface ListValuedMap extends MultiValuedMap { * {@link #containsKey(Object)} returns {@code false}. Changes to the * returned list will update the underlying {@code ListValuedMap} and * vice-versa. + *

        * * @param key the key to retrieve * @return the {@code List} of values, implementations should return an @@ -56,6 +57,7 @@ public interface ListValuedMap extends MultiValuedMap { * The returned list may 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. + *

        * * @param key the key to remove values from * @return the {@code List} of values removed, implementations diff --git a/src/main/java/org/apache/commons/collections4/MapIterator.java b/src/main/java/org/apache/commons/collections4/MapIterator.java index 54cd88e76a..c9c76fc9c6 100644 --- a/src/main/java/org/apache/commons/collections4/MapIterator.java +++ b/src/main/java/org/apache/commons/collections4/MapIterator.java @@ -88,6 +88,7 @@ public interface MapIterator extends Iterator { * Removes the last returned key from the underlying {@code Map} (optional operation). *

        * This method can be called once per call to {@code next()}. + *

        * * @throws UnsupportedOperationException if remove is not supported by the map * @throws IllegalStateException if {@code next()} has not yet been called diff --git a/src/main/java/org/apache/commons/collections4/MultiMap.java b/src/main/java/org/apache/commons/collections4/MultiMap.java index 1e10fda861..ad6d4fa106 100644 --- a/src/main/java/org/apache/commons/collections4/MultiMap.java +++ b/src/main/java/org/apache/commons/collections4/MultiMap.java @@ -57,6 +57,7 @@ public interface MultiMap extends IterableMap { *

        * Implementations typically check all collections against all keys for the value. * This cannot be mandated due to backwards compatibility of this interface. + *

        * * @param value the value to search for * @return true if the map contains the value @@ -72,12 +73,15 @@ public interface MultiMap extends IterableMap { * 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}. + *

        *

        * 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 may choose to return a clone of the internal collection. + *

        * * @param key the key to retrieve * @return the {@code Collection} of values, implementations should @@ -95,6 +99,7 @@ public interface MultiMap extends IterableMap { * 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. + *

        * * @param key the key to store against * @param value the value to add to the collection at the key @@ -112,6 +117,7 @@ public interface MultiMap extends IterableMap { *

        * Implementations typically return {@code null} from a subsequent * {@code get(Object)}, however they may choose to return an empty collection. + *

        * * @param key the key to remove values from * @return the {@code Collection} of values removed, implementations should @@ -128,10 +134,12 @@ public interface MultiMap extends IterableMap { *

        * The item is removed from the collection mapped to the specified key. * Other values attached to that key are unaffected. + *

        *

        * 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. + *

        * * @param key the key to remove from * @param item the item to remove @@ -148,6 +156,7 @@ public interface MultiMap extends IterableMap { *

        * Implementations typically return only the count of keys in the map * This cannot be mandated due to backwards compatibility of this interface. + *

        * * @return the number of key-collection mappings in this map */ @@ -160,6 +169,7 @@ public interface MultiMap extends IterableMap { * Implementations typically return a collection containing the combination * of values from all keys. * This cannot be mandated due to backwards compatibility of this interface. + *

        * * @return a collection view of the values contained in this map */ diff --git a/src/main/java/org/apache/commons/collections4/MultiMapUtils.java b/src/main/java/org/apache/commons/collections4/MultiMapUtils.java index a91372722c..77dee5afe5 100644 --- a/src/main/java/org/apache/commons/collections4/MultiMapUtils.java +++ b/src/main/java/org/apache/commons/collections4/MultiMapUtils.java @@ -161,6 +161,7 @@ public static Set getValuesAsSet(final MultiValuedMap map, final * Null-safe check if the specified {@code MultiValuedMap} is empty. *

        * If the provided map is null, returns true. + *

        * * @param map the map to check, may be null * @return true if the map is empty or null @@ -200,13 +201,16 @@ public static SetValuedMap newSetValuedHashMap() { * specified map) that will transform any new entries added to it. Existing * entries in the specified map will not be transformed. If you want that * behavior, see {@link TransformedMultiValuedMap#transformedMap}. + *

        *

        * Each object is passed through the transformers as it is added to the Map. * It is important not to use the original map after invoking this method, * as it is a back door for adding untransformed objects. + *

        *

        * If there are any elements already in the map being decorated, they are * NOT transformed. + *

        * * @param the key type * @param the value type diff --git a/src/main/java/org/apache/commons/collections4/MultiSet.java b/src/main/java/org/apache/commons/collections4/MultiSet.java index 5096ad5867..122a824ea2 100644 --- a/src/main/java/org/apache/commons/collections4/MultiSet.java +++ b/src/main/java/org/apache/commons/collections4/MultiSet.java @@ -39,6 +39,7 @@ public interface MultiSet extends Collection { *

        * The {@link MultiSet#entrySet()} method returns a view of the multiset whose elements * implement this interface. + *

        * * @param the element type */ @@ -52,6 +53,7 @@ interface Entry { *

        * More formally, two entries {@code e1} and {@code e2} represent * the same mapping if + *

        *
                  *     (e1.getElement()==null ? e2.getElement()==null
                  *                            : e1.getElement().equals(e2.getElement())) &&
        @@ -98,6 +100,7 @@ interface Entry {
              * If the object is already in the {@link #uniqueSet()} then increment its
              * count as reported by {@link #getCount(Object)}. Otherwise, add it to the
              * {@link #uniqueSet()} and report its count as 1.
        +     * 

        * * @param object the object to add * @return {@code true} always, as the size of the MultiSet is increased @@ -112,6 +115,7 @@ interface Entry { * If the object is already in the {@link #uniqueSet()} then increment its * count as reported by {@link #getCount(Object)}. Otherwise, add it to the * {@link #uniqueSet()} and report its count as {@code occurrences}. + *

        * * @param object the object to add * @param occurrences the number of occurrences to add, may be zero, @@ -137,6 +141,7 @@ interface Entry { *

        * The returned set is backed by this multiset, so any change to either * is immediately reflected in the other. + *

        * * @return the Set of MultiSet entries */ @@ -147,6 +152,7 @@ interface Entry { *

        * This MultiSet equals another object if it is also a MultiSet * that contains the same number of occurrences of the same elements. + *

        * * @param obj the object to compare to * @return true if equal @@ -202,6 +208,7 @@ interface Entry { *

        * If the number of occurrences to remove is greater than the actual number of * occurrences in the multiset, the object will be removed from the multiset. + *

        * * @param object the object to remove * @param occurrences the number of occurrences to remove, may be zero, @@ -238,6 +245,7 @@ interface Entry { *

        * If the provided count is zero, the object will be removed from the * {@link #uniqueSet()}. + *

        * * @param object the object to update * @param count the number of occurrences of the object @@ -259,11 +267,13 @@ interface Entry { * Returns a {@link Set} of unique elements in the MultiSet. *

        * Uniqueness constraints are the same as those in {@link java.util.Set}. + *

        *

        * The returned set is backed by this multiset, so any change to either * is immediately reflected in the other. Only removal operations are * supported, in which case all occurrences of the element are removed * from the backing multiset. + *

        * * @return the Set of unique MultiSet elements */ diff --git a/src/main/java/org/apache/commons/collections4/MultiSetUtils.java b/src/main/java/org/apache/commons/collections4/MultiSetUtils.java index f424236e22..419574bca5 100644 --- a/src/main/java/org/apache/commons/collections4/MultiSetUtils.java +++ b/src/main/java/org/apache/commons/collections4/MultiSetUtils.java @@ -54,6 +54,7 @@ public static MultiSet emptyMultiSet() { * IllegalArgumentException. It is important not to use the original multiset * after invoking this method, as it is a backdoor for adding invalid * objects. + *

        * * @param the element type * @param multiset the multiset to predicate, must not be null @@ -73,7 +74,7 @@ public static MultiSet predicatedMultiSet(final MultiSet multiset, *

        * It is imperative that the user manually synchronize on the returned multiset * when iterating over it: - * + *

        *
              * MultiSet multiset = MultiSetUtils.synchronizedMultiSet(new HashMultiSet());
              * ...
        diff --git a/src/main/java/org/apache/commons/collections4/MultiValuedMap.java b/src/main/java/org/apache/commons/collections4/MultiValuedMap.java
        index 5b1d6268e4..b5620e2c12 100644
        --- a/src/main/java/org/apache/commons/collections4/MultiValuedMap.java
        +++ b/src/main/java/org/apache/commons/collections4/MultiValuedMap.java
        @@ -231,8 +231,6 @@ public interface MultiValuedMap {
              */
             boolean putAll(K key, Iterable values);
         
        -    // Views
        -
             /**
              * Copies all mappings from the specified map to this multivalued map
              * (optional operation).
        diff --git a/src/main/java/org/apache/commons/collections4/OrderedBidiMap.java b/src/main/java/org/apache/commons/collections4/OrderedBidiMap.java
        index 36f3cc48e5..14f4a9ee86 100644
        --- a/src/main/java/org/apache/commons/collections4/OrderedBidiMap.java
        +++ b/src/main/java/org/apache/commons/collections4/OrderedBidiMap.java
        @@ -36,13 +36,16 @@ public interface OrderedBidiMap extends BidiMap, OrderedMap {
              * 

        * Changes to one map will be visible in the other and vice versa. * This enables both directions of the map to be accessed equally. + *

        *

        * 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 must return an {@code OrderedBidiMap} instance, * usually by forwarding to {@code inverseOrderedBidiMap()}. + *

        * * @return an inverted bidirectional map */ diff --git a/src/main/java/org/apache/commons/collections4/OrderedMap.java b/src/main/java/org/apache/commons/collections4/OrderedMap.java index b6f292eb7c..7707894403 100644 --- a/src/main/java/org/apache/commons/collections4/OrderedMap.java +++ b/src/main/java/org/apache/commons/collections4/OrderedMap.java @@ -48,6 +48,7 @@ public interface OrderedMap extends IterableMap { *

        * An ordered map iterator is an efficient way of iterating over maps * in both directions. + *

        * * @return a map iterator */ diff --git a/src/main/java/org/apache/commons/collections4/PredicateUtils.java b/src/main/java/org/apache/commons/collections4/PredicateUtils.java index 8869fa1cb2..bced37f9ae 100644 --- a/src/main/java/org/apache/commons/collections4/PredicateUtils.java +++ b/src/main/java/org/apache/commons/collections4/PredicateUtils.java @@ -64,7 +64,9 @@ *
      • NullIsException/NullIsFalse/NullIsTrue - check for null input *
      • Transformed - transforms the input before calling the predicate *
      + *

      * All the supplied predicates are Serializable. + *

      * * @since 3.0 */ @@ -277,6 +279,7 @@ public static Predicate invokerPredicate(final String methodName) { * For example, {@code PredicateUtils.invokerPredicate("isEmpty");} * will call the {@code isEmpty} method on the input object to * determine the predicate result. + *

      * * @param the type that the predicate queries * @param methodName the method name to call on the input object, may not be null @@ -473,7 +476,6 @@ public static Predicate orPredicate(final Predicate predicate1 return OrPredicate.orPredicate(predicate1, predicate2); } - // Transformed /** * Creates a predicate that transforms the input object before passing it * to the predicate. diff --git a/src/main/java/org/apache/commons/collections4/QueueUtils.java b/src/main/java/org/apache/commons/collections4/QueueUtils.java index aff6a24194..d5f82b55d2 100644 --- a/src/main/java/org/apache/commons/collections4/QueueUtils.java +++ b/src/main/java/org/apache/commons/collections4/QueueUtils.java @@ -55,6 +55,7 @@ public static Queue emptyQueue() { * Trying to add an invalid object results in an IllegalArgumentException. * It is important not to use the original queue after invoking this method, * as it is a backdoor for adding invalid objects. + *

      * * @param the type of the elements in the queue * @param queue the queue to predicate, must not be null @@ -73,7 +74,7 @@ public static Queue predicatedQueue(final Queue queue, final Predicate *

      * It is imperative that the user manually synchronize on the returned queue * when iterating over it: - * + *

      *
            * Queue queue = QueueUtils.synchronizedQueue(new CircularFifoQueue());
            * ...
      @@ -84,8 +85,9 @@ public static  Queue predicatedQueue(final Queue queue, final Predicate
            *     }
            * }
            * 
      - * + *

      * Failure to follow this advice may result in non-deterministic behavior. + *

      * * @param the element type * @param queue the queue to synchronize, must not be null @@ -103,9 +105,11 @@ public static Queue synchronizedQueue(final Queue queue) { * Each object is passed through the transformer as it is added to the * Queue. It is important not to use the original queue after invoking this * method, as it is a backdoor for adding untransformed objects. + *

      *

      * Existing entries in the specified queue will not be transformed. * If you want that behavior, see {@link TransformedQueue#transformedQueue}. + *

      * * @param the type of the elements in the queue * @param queue the queue to predicate, must not be null diff --git a/src/main/java/org/apache/commons/collections4/SetUtils.java b/src/main/java/org/apache/commons/collections4/SetUtils.java index befd03ccd4..bdef4b5a88 100644 --- a/src/main/java/org/apache/commons/collections4/SetUtils.java +++ b/src/main/java/org/apache/commons/collections4/SetUtils.java @@ -54,6 +54,7 @@ public class SetUtils { * If the decorated sets change, this view will change as well. The contents * of this view can be transferred to another instance via the {@link #copyInto(Set)} * and {@link #toSet()} methods. + *

      * * @param the element type * @since 4.1 diff --git a/src/main/java/org/apache/commons/collections4/SortedBidiMap.java b/src/main/java/org/apache/commons/collections4/SortedBidiMap.java index f338b96af9..79e60a8719 100644 --- a/src/main/java/org/apache/commons/collections4/SortedBidiMap.java +++ b/src/main/java/org/apache/commons/collections4/SortedBidiMap.java @@ -38,13 +38,16 @@ public interface SortedBidiMap extends OrderedBidiMap, SortedMap * Changes to one map will be visible in the other and vice versa. * This enables both directions of the map to be accessed equally. + *

      *

      * 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 must return a {@code SortedBidiMap} instance, * usually by forwarding to {@code inverseSortedBidiMap()}. + *

      * * @return an inverted bidirectional map */ diff --git a/src/main/java/org/apache/commons/collections4/SplitMapUtils.java b/src/main/java/org/apache/commons/collections4/SplitMapUtils.java index bcaca1a53b..d01bea5338 100644 --- a/src/main/java/org/apache/commons/collections4/SplitMapUtils.java +++ b/src/main/java/org/apache/commons/collections4/SplitMapUtils.java @@ -217,6 +217,7 @@ public Collection values() { * If {@code get} implements {@link IterableMap} directly, no conversion will take place. * If {@code get} implements {@link Map} but not {@link IterableMap} it will be decorated. * Otherwise, an {@link Unmodifiable} {@link IterableMap} will be returned. + * * @param the key type * @param the value type * @param get to wrap, must not be null diff --git a/src/main/java/org/apache/commons/collections4/TransformerUtils.java b/src/main/java/org/apache/commons/collections4/TransformerUtils.java index 05c72c1134..7d4dfdf63c 100644 --- a/src/main/java/org/apache/commons/collections4/TransformerUtils.java +++ b/src/main/java/org/apache/commons/collections4/TransformerUtils.java @@ -357,6 +357,7 @@ public static Transformer stringValueTransformer() { * is called if the input object equals the key. If there is no match, the * default transformer is called. The default transformer is set in the map * using a null key. If no default is set, null will be returned in a default case. + *

      * * @param the input type * @param the output type @@ -394,6 +395,7 @@ public static Transformer switchMapTransformer( * null key. If no default transformer is set, null will be returned in a default * case. The ordering is that of the iterator() method on the entryset collection * of the map. + *

      * * @param the input type * @param the output type diff --git a/src/main/java/org/apache/commons/collections4/Trie.java b/src/main/java/org/apache/commons/collections4/Trie.java index 253dc53753..8791b3b44d 100644 --- a/src/main/java/org/apache/commons/collections4/Trie.java +++ b/src/main/java/org/apache/commons/collections4/Trie.java @@ -19,8 +19,7 @@ import java.util.SortedMap; /** - * Defines the interface for a prefix tree, an ordered tree data structure. For - * more information, see Tries. + * Defines the interface for a prefix tree, an ordered tree data structure. For more information, see Tries. * * @param the type of the keys in this map * @param the type of the values in this map @@ -29,19 +28,17 @@ public interface Trie extends IterableSortedMap { /** - * Returns a view of this {@link Trie} of all elements that are prefixed - * by the given key. + * Returns a view of this {@link Trie} of all elements that are prefixed by the given key. *

      - * In a {@link Trie} with fixed size keys, this is essentially a - * {@link #get(Object)} operation. + * In a {@link Trie} with fixed size keys, this is essentially a {@link #get(Object)} operation. + *

      *

      - * For example, if the {@link Trie} contains 'Anna', 'Anael', - * 'Analu', 'Andreas', 'Andrea', 'Andres', and 'Anatole', then - * a lookup of 'And' would return 'Andreas', 'Andrea', and 'Andres'. + * For example, if the {@link Trie} contains 'Anna', 'Anael', 'Analu', 'Andreas', 'Andrea', 'Andres', and 'Anatole', then a lookup of 'And' would return + * 'Andreas', 'Andrea', and 'Andres'. + *

      * - * @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 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 ca1acf5353..3541908d5b 100644 --- a/src/main/java/org/apache/commons/collections4/Unmodifiable.java +++ b/src/main/java/org/apache/commons/collections4/Unmodifiable.java @@ -27,9 +27,11 @@ * } * // now we know coll is modifiable * + *

      * 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. + *

      * * @since 3.0 */