Apache
/
commons-collections
mirror of https://github.com/apache/commons-collections.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Javadoc 

- Close HTML tags
- Use longer lines
- Whitespace before tags
- Remove dead inline comments
= Add missing paragraph tags
This commit is contained in:
Gary Gregory 2024-10-20 08:31:59 -04:00
parent a7e92888fe
commit 01655058b0
25 changed files with 113 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
src/main/java/org/apache/commons/collections4/ClosureUtils.java
View File

@ -253,6 +253,7 @@ public class ClosureUtils {
* 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.
* </p>
*
* @see org.apache.commons.collections4.functors.SwitchClosure
*
@ -275,6 +276,7 @@ public class ClosureUtils {
* 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.
* </p>
*
* @see org.apache.commons.collections4.functors.SwitchClosure
*
@ -299,6 +301,7 @@ public class ClosureUtils {
* location 0 returned true. Each predicate is evaluated
* until one returns true. If no predicates evaluate to true, the default
* closure is called.
* </p>
*
* @see org.apache.commons.collections4.functors.SwitchClosure
*
@ -325,6 +328,7 @@ public class ClosureUtils {
* 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.
* </p>
*
* @see org.apache.commons.collections4.functors.SwitchClosure
*

5
src/main/java/org/apache/commons/collections4/CollectionUtils.java
View File

@ -225,6 +225,7 @@ public class CollectionUtils {
* @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 class CollectionUtils {
*/
public static <O> List<O> collate(final Iterable<? extends O> iterableA, final Iterable<? extends O> iterableB,
final Comparator<? super O> 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 class CollectionUtils {
return IteratorUtils.toList(iterator, totalSize);
}
final ArrayList<O> mergedList = new ArrayList<>(totalSize);
O lastItem = null;
while (iterator.hasNext()) {
final O item = iterator.next();
@ -484,7 +482,6 @@ public class CollectionUtils {
}
lastItem = item;
}
mergedList.trimToSize();
return mergedList;
}

1
src/main/java/org/apache/commons/collections4/EnumerationUtils.java
View File

@ -50,6 +50,7 @@ public class EnumerationUtils {
* <p>
* 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.
* </p>
*
* @param e the enumeration to get a value from
* @param index the index to get

1
src/main/java/org/apache/commons/collections4/FactoryUtils.java
View File

@ -34,6 +34,7 @@ import org.apache.commons.collections4.functors.PrototypeFactory;
* <p>
* Since v4.1 only factories which are considered to be safe are
* Serializable. Factories considered to be unsafe for serialization are:
* </p>
* <ul>
* <li>Prototype
* <li>Instantiate

12
src/main/java/org/apache/commons/collections4/FluentIterable.java
View File

@ -84,6 +84,7 @@ public class FluentIterable<E> implements Iterable<E> {
* <p>
* The returned iterable's iterator supports {@code remove()} when the
* corresponding input iterator supports it.
* </p>
*
* @param <T> the element type
* @param iterable the iterable to wrap into a FluentIterable, may not be null
@ -102,6 +103,7 @@ public class FluentIterable<E> implements Iterable<E> {
* Creates a new FluentIterable of the single provided element.
* <p>
* The returned iterable's iterator does not support {@code remove()}.
* </p>
*
* @param <T> the element type
* @param singleton the singleton element
@ -115,6 +117,7 @@ public class FluentIterable<E> implements Iterable<E> {
* Creates a new FluentIterable from the provided elements.
* <p>
* The returned iterable's iterator does not support {@code remove()}.
* </p>
*
* @param <T> the element type
* @param elements the elements to be contained in the FluentIterable
@ -147,6 +150,7 @@ public class FluentIterable<E> implements Iterable<E> {
* provided predicate.
* <p>
* A {@code null} or empty iterable returns true.
* </p>
*
* @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 class FluentIterable<E> implements Iterable<E> {
* Checks if this iterable contains any element matching the provided predicate.
* <p>
* A {@code null} or empty iterable returns false.
* </p>
*
* @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 class FluentIterable<E> implements Iterable<E> {
* elements of the current and provided iterable in natural order.
* <p>
* Example: natural ordering
* </p>
* <ul>
* <li>this contains elements [1, 3, 5, 7]
* <li>other contains elements [2, 4, 6, 8]
@ -218,6 +224,7 @@ public class FluentIterable<E> implements Iterable<E> {
* <p>
* The returned iterable will traverse the elements in the following
* order: [1, 2, 3, 4, 5, 6, 7, 8]
* </p>
*
* @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 class FluentIterable<E> implements Iterable<E> {
* ordering defined by a comparator.
* <p>
* Example: descending order
* </p>
* <ul>
* <li>this contains elements [7, 5, 3, 1]
* <li>other contains elements [8, 6, 4, 2]
@ -241,6 +249,7 @@ public class FluentIterable<E> implements Iterable<E> {
* <p>
* The returned iterable will traverse the elements in the following
* order: [8, 7, 6, 5, 4, 3, 2, 1]
* </p>
*
* @param comparator the comparator to define an ordering, may be null,
* in which case natural ordering will be used
@ -282,10 +291,12 @@ public class FluentIterable<E> implements Iterable<E> {
* to the originating iterables and/or iterators.
* <p>
* Calling this method is equivalent to:
* </p>
* <pre>
* FluentIterable&lt;E&gt; someIterable = ...;
* FluentIterable.of(someIterable.toList());
* </pre>
* </p>
*
* @return a new iterable with the same contents as this iterable
*/
@ -416,6 +427,7 @@ public class FluentIterable<E> implements Iterable<E> {
* by traversing its iterator.
* <p>
* The returned list is guaranteed to be mutable.
* </p>
*
* @return a list of the iterable contents
*/

1
src/main/java/org/apache/commons/collections4/IterableGet.java
View File

@ -31,6 +31,7 @@ public interface IterableGet<K, V> extends Get<K, V> {
* <p>
* 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.
* </p>
* <pre>
* IterableMap&lt;String,Integer&gt; map = new HashedMap&lt;String,Integer&gt;();
* MapIterator&lt;String,Integer&gt; it = map.mapIterator();

2
src/main/java/org/apache/commons/collections4/IteratorUtils.java
View File

@ -536,7 +536,6 @@ public class IteratorUtils {
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 class IteratorUtils {
return new NodeListIterator(Objects.requireNonNull(nodeList, "nodeList"));
}
// Object Graph
/**
* Gets an iterator that operates over an object graph.
* <p>

40
src/main/java/org/apache/commons/collections4/ListUtils.java
View File

@ -42,6 +42,7 @@ import org.apache.commons.collections4.sequence.SequencesComparator;
* @since 1.0
*/
public class ListUtils {
/**
* A simple wrapper to use a CharSequence as List.
*/
@ -178,6 +179,7 @@ public class ListUtils {
* <p>
* Shorthand for {@code list.get(0)}
* </p>
*
* @param <T> The list type.
* @param list The list.
* @return the first element of a list.
@ -193,6 +195,7 @@ public class ListUtils {
* <p>
* Shorthand for {@code list.get(list.size() - 1)}
* </p>
*
* @param <T> The list type.
* @param list The list.
* @return the last element of a list.
@ -210,6 +213,7 @@ public class ListUtils {
* 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.
* </p>
*
* @see java.util.List#hashCode()
* @param list the list to generate the hashCode for, may be null
@ -232,6 +236,7 @@ public class ListUtils {
* <p>
* If the input List or predicate is null, or no element of the List
* matches the predicate, -1 is returned.
* </p>
*
* @param <E> the element type
* @param list the List to search, may be null
@ -288,8 +293,10 @@ public class ListUtils {
* 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.
* </p>
* <p>
* The relevant text (slightly paraphrased as this is a static method) is:
* </p>
* <blockquote>
* Compares the two list objects for equality. Returns
* {@code true} if and only if both
@ -301,9 +308,10 @@ public class ListUtils {
* definition ensures that the equals method works properly across
* different implementations of the {@code List} interface.
* </blockquote>
*
* <p>
* <b>Note:</b> The behavior of this method is undefined if the lists are
* modified during the equals comparison.
* </p>
*
* @see java.util.List
* @param list1 the first list, may be null
@ -339,9 +347,10 @@ public class ListUtils {
* 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.
* </p>
* <p>
* For instance:
*
* </p>
* <pre>
* Factory&lt;Date&gt; factory = new Factory&lt;Date&gt;() {
* public Date create() {
@ -351,11 +360,12 @@ public class ListUtils {
* List&lt;Date&gt; lazy = ListUtils.lazyList(new ArrayList&lt;Date&gt;(), factory);
* Date date = lazy.get(3);
* </pre>
*
* <p>
* 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}.
* </p>
*
* @param <E> the element type
* @param list the list to make lazy, must not be null
@ -373,20 +383,22 @@ public class ListUtils {
* When the index passed to the returned list's {@link List#get(int) get}
* method is greater than the list's size, then the transformer will be used
* to create a new object and that object will be inserted at that index.
* </p>
* <p>
* For instance:
*
* </p>
* <pre>
* List&lt;Integer&gt; hours = Arrays.asList(7, 5, 8, 2);
* Transformer&lt;Integer,Date&gt; transformer = input -&gt; LocalDateTime.now().withHour(hours.get(input));
* List&lt;LocalDateTime&gt; lazy = ListUtils.lazyList(new ArrayList&lt;LocalDateTime&gt;(), transformer);
* Date date = lazy.get(3);
* </pre>
*
* <p>
* 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}.
* </p>
*
* @param <E> the element type
* @param list the list to make lazy, must not be null
@ -403,6 +415,7 @@ public class ListUtils {
* <p>
* This is a convenience method for using {@link #longestCommonSubsequence(List, List)}
* with {@link CharSequence} instances.
* </p>
*
* @param charSequenceA the first sequence
* @param charSequenceB the second sequence
@ -471,8 +484,10 @@ public class ListUtils {
* 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.
* </p>
* <p>
* Adapted from https://github.com/google/guava
* </p>
*
* @param <T> the element type
* @param list the list to return consecutive sublists of
@ -497,6 +512,7 @@ public class ListUtils {
* 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.
* </p>
*
* @param <E> the element type
* @param list the list to predicate, must not be null
@ -522,6 +538,7 @@ public class ListUtils {
* 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)}.
* </p>
*
* @param <E> the element type
* @param collection the collection from which items are removed (in the returned collection)
@ -556,6 +573,7 @@ public class ListUtils {
* 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)}.
* </p>
*
* @param <E> the element type
* @param collection the collection whose contents are the target of the #retailAll operation
@ -581,6 +599,7 @@ public class ListUtils {
* predicate into an output list.
* <p>
* A {@code null} predicate matches no elements.
* </p>
*
* @param <E> the element type
* @param inputCollection the collection to get the input from, may not be null
@ -601,6 +620,7 @@ public class ListUtils {
* predicate into an output collection.
* <p>
* If the input predicate is {@code null}, the result is an empty list.
* </p>
*
* @param <E> the element type
* @param inputCollection the collection to get the input from, may not be null
@ -625,6 +645,7 @@ public class ListUtils {
* occurrences of <Code>null</Code> and <Code>list2</Code> only
* contains one occurrence, then the returned list will still contain
* one occurrence.
* </p>
*
* @param <E> the element type
* @param list1 the list to subtract from
@ -662,7 +683,7 @@ public class ListUtils {
* <p>
* You must manually synchronize on the returned list's iterator to
* avoid non-deterministic behavior:
*
* </p>
* <pre>
* List list = ListUtils.synchronizedList(myList);
* synchronized (list) {
@ -672,8 +693,9 @@ public class ListUtils {
* }
* }
* </pre>
*
* <p>
* This method is just a wrapper for {@link Collections#synchronizedList(List)}.
* </p>
*
* @param <E> the element type
* @param list the list to synchronize, must not be null
@ -690,13 +712,16 @@ public class ListUtils {
* 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.
* </p>
* <p>
* 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.
* </p>
* <p>
* Existing entries in the specified list will not be transformed.
* If you want that behavior, see {@link TransformedList#transformedList}.
* </p>
*
* @param <E> the element type
* @param list the list to predicate, must not be null
@ -731,6 +756,7 @@ public class ListUtils {
* Returns an unmodifiable list backed by the given list.
* <p>
* This method uses the implementation in the decorators subpackage.
* </p>
*
* @param <E> the element type
* @param list the list to make unmodifiable, must not be null

2
src/main/java/org/apache/commons/collections4/ListValuedMap.java
View File

@ -41,6 +41,7 @@ public interface ListValuedMap<K, V> extends MultiValuedMap<K, V> {
* {@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
@ -56,6 +57,7 @@ public interface ListValuedMap<K, V> extends MultiValuedMap<K, V> {
* 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

1
src/main/java/org/apache/commons/collections4/MapIterator.java
View File

@ -88,6 +88,7 @@ public interface MapIterator<K, V> extends Iterator<K> {
* Removes the last returned key from the underlying {@code Map} (optional operation).
* <p>
* 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

10
src/main/java/org/apache/commons/collections4/MultiMap.java
View File

@ -57,6 +57,7 @@ public interface MultiMap<K, V> extends IterableMap<K, Object> {
* <p>
* 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
@ -72,12 +73,15 @@ public interface MultiMap<K, V> extends IterableMap<K, Object> {
* 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.
* </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
@ -95,6 +99,7 @@ public interface MultiMap<K, V> extends IterableMap<K, Object> {
* 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
@ -112,6 +117,7 @@ public interface MultiMap<K, V> extends IterableMap<K, Object> {
* <p>
* 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
@ -128,10 +134,12 @@ public interface MultiMap<K, V> extends IterableMap<K, Object> {
* <p>
* The item is removed from the collection mapped to the specified key.
* Other values attached to that key are unaffected.
* </p>
* <p>
* If the last value for a key is removed, 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
@ -148,6 +156,7 @@ public interface MultiMap<K, V> extends IterableMap<K, Object> {
* <p>
* 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
*/
@ -160,6 +169,7 @@ public interface MultiMap<K, V> extends IterableMap<K, Object> {
* 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
*/

4
src/main/java/org/apache/commons/collections4/MultiMapUtils.java
View File

@ -161,6 +161,7 @@ public class MultiMapUtils {
* Null-safe check if the specified {@code MultiValuedMap} is empty.
* <p>
* If the provided map is null, returns true.
* </p>
*
* @param map the map to check, may be null
* @return true if the map is empty or null
@ -200,13 +201,16 @@ public class MultiMapUtils {
* 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}.
* </p>
* <p>
* 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.
* </p>
* <p>
* If there are any elements already in the map being decorated, they are
* NOT transformed.
* </p>
*
* @param <K> the key type
* @param <V> the value type

10
src/main/java/org/apache/commons/collections4/MultiSet.java
View File

@ -39,6 +39,7 @@ public interface MultiSet<E> extends Collection<E> {
* <p>
* The {@link MultiSet#entrySet()} method returns a view of the multiset whose elements
* implement this interface.
* </p>
*
* @param <E> the element type
*/
@ -52,6 +53,7 @@ public interface MultiSet<E> extends Collection<E> {
* <p>
* More formally, two entries {@code e1} and {@code e2} represent
* the same mapping if
* </p>
* <pre>
* (e1.getElement()==null ? e2.getElement()==null
* : e1.getElement().equals(e2.getElement())) &amp;&amp;
@ -98,6 +100,7 @@ public interface MultiSet<E> extends Collection<E> {
* 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.
* </p>
*
* @param object the object to add
* @return {@code true} always, as the size of the MultiSet is increased
@ -112,6 +115,7 @@ public interface MultiSet<E> extends Collection<E> {
* 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}.
* </p>
*
* @param object the object to add
* @param occurrences the number of occurrences to add, may be zero,
@ -137,6 +141,7 @@ public interface MultiSet<E> extends Collection<E> {
* <p>
* The returned set is backed by this multiset, so any change to either
* is immediately reflected in the other.
* </p>
*
* @return the Set of MultiSet entries
*/
@ -147,6 +152,7 @@ public interface MultiSet<E> extends Collection<E> {
* <p>
* This MultiSet equals another object if it is also a MultiSet
* that contains the same number of occurrences of the same elements.
* </p>
*
* @param obj the object to compare to
* @return true if equal
@ -202,6 +208,7 @@ public interface MultiSet<E> extends Collection<E> {
* <p>
* 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.
* </p>
*
* @param object the object to remove
* @param occurrences the number of occurrences to remove, may be zero,
@ -238,6 +245,7 @@ public interface MultiSet<E> extends Collection<E> {
* <p>
* If the provided count is zero, the object will be removed from the
* {@link #uniqueSet()}.
* </p>
*
* @param object the object to update
* @param count the number of occurrences of the object
@ -259,11 +267,13 @@ public interface MultiSet<E> extends Collection<E> {
* Returns a {@link Set} of unique elements in the MultiSet.
* <p>
* Uniqueness constraints are the same as those in {@link java.util.Set}.
* </p>
* <p>
* 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.
* </p>
*
* @return the Set of unique MultiSet elements
*/

3
src/main/java/org/apache/commons/collections4/MultiSetUtils.java
View File

@ -54,6 +54,7 @@ public class MultiSetUtils {
* IllegalArgumentException. It is important not to use the original multiset
* after invoking this method, as it is a backdoor for adding invalid
* objects.
* </p>
*
* @param <E> the element type
* @param multiset the multiset to predicate, must not be null
@ -73,7 +74,7 @@ public class MultiSetUtils {
* <p>
* It is imperative that the user manually synchronize on the returned multiset
* when iterating over it:
*
* </p>
* <pre>
* MultiSet multiset = MultiSetUtils.synchronizedMultiSet(new HashMultiSet());
* ...

2
src/main/java/org/apache/commons/collections4/MultiValuedMap.java
View File

@ -231,8 +231,6 @@ public interface MultiValuedMap<K, V> {
*/
boolean putAll(K key, Iterable<? extends V> values);
// Views
/**
* Copies all mappings from the specified map to this multivalued map
* (optional operation).

3
src/main/java/org/apache/commons/collections4/OrderedBidiMap.java
View File

@ -36,13 +36,16 @@ public interface OrderedBidiMap<K, V> extends BidiMap<K, V>, OrderedMap<K, V> {
* <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.
* </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.
* </p>
* <p>
* Implementations must return an {@code OrderedBidiMap} instance,
* usually by forwarding to {@code inverseOrderedBidiMap()}.
* </p>
*
* @return an inverted bidirectional map
*/

1
src/main/java/org/apache/commons/collections4/OrderedMap.java
View File

@ -48,6 +48,7 @@ public interface OrderedMap<K, V> extends IterableMap<K, V> {
* <p>
* An ordered map iterator is an efficient way of iterating over maps
* in both directions.
* </p>
*
* @return a map iterator
*/

4
src/main/java/org/apache/commons/collections4/PredicateUtils.java
View File

@ -64,7 +64,9 @@ import org.apache.commons.collections4.functors.UniquePredicate;
* <li>NullIsException/NullIsFalse/NullIsTrue - check for null input
* <li>Transformed - transforms the input before calling the predicate
* </ul>
* <p>
* All the supplied predicates are Serializable.
* </p>
*
* @since 3.0
*/
@ -277,6 +279,7 @@ public class PredicateUtils {
* For example, {@code PredicateUtils.invokerPredicate("isEmpty");}
* will call the {@code isEmpty} method on the input object to
* determine the predicate result.
* </p>
*
* @param <T> 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 class PredicateUtils {
return OrPredicate.orPredicate(predicate1, predicate2);
}
// Transformed
/**
* Creates a predicate that transforms the input object before passing it
* to the predicate.

8
src/main/java/org/apache/commons/collections4/QueueUtils.java
View File

@ -55,6 +55,7 @@ public class QueueUtils {
* 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.
* </p>
*
* @param <E> the type of the elements in the queue
* @param queue the queue to predicate, must not be null
@ -73,7 +74,7 @@ public class QueueUtils {
* <p>
* It is imperative that the user manually synchronize on the returned queue
* when iterating over it:
*
* </p>
* <pre>
* Queue queue = QueueUtils.synchronizedQueue(new CircularFifoQueue());
* ...
@ -84,8 +85,9 @@ public class QueueUtils {
* }
* }
* </pre>
*
* <p>
* Failure to follow this advice may result in non-deterministic behavior.
* </p>
*
* @param <E> the element type
* @param queue the queue to synchronize, must not be null
@ -103,9 +105,11 @@ public class QueueUtils {
* 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.
* </p>
* <p>
* Existing entries in the specified queue will not be transformed.
* If you want that behavior, see {@link TransformedQueue#transformedQueue}.
* </p>
*
* @param <E> the type of the elements in the queue
* @param queue the queue to predicate, must not be null

1
src/main/java/org/apache/commons/collections4/SetUtils.java
View File

@ -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.
* </p>
*
* @param <E> the element type
* @since 4.1

3
src/main/java/org/apache/commons/collections4/SortedBidiMap.java
View File

@ -38,13 +38,16 @@ public interface SortedBidiMap<K, V> extends OrderedBidiMap<K, V>, SortedMap<K,
* <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.
* </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.
* </p>
* <p>
* Implementations must return a {@code SortedBidiMap} instance,
* usually by forwarding to {@code inverseSortedBidiMap()}.
* </p>
*
* @return an inverted bidirectional map
*/

1
src/main/java/org/apache/commons/collections4/SplitMapUtils.java
View File

@ -217,6 +217,7 @@ public class SplitMapUtils {
* 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 <K> the key type
* @param <V> the value type
* @param get to wrap, must not be null

2
src/main/java/org/apache/commons/collections4/TransformerUtils.java
View File

@ -357,6 +357,7 @@ public class TransformerUtils {
* 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.
* </p>
*
* @param <I> the input type
* @param <O> the output type
@ -394,6 +395,7 @@ public class TransformerUtils {
* 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.
* </p>
*
* @param <I> the input type
* @param <O> the output type

21
src/main/java/org/apache/commons/collections4/Trie.java
View File

@ -19,8 +19,7 @@ package org.apache.commons.collections4;
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>.
* 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
@ -29,19 +28,17 @@ import java.util.SortedMap;
public interface Trie<K, V> extends IterableSortedMap<K, V> {
/**
* 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.
* <p>
* 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.
* </p>
* <p>
* 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'.
* </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);

2
src/main/java/org/apache/commons/collections4/Unmodifiable.java
View File

@ -27,9 +27,11 @@ package org.apache.commons.collections4;
* }
* // 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.
* </p>
*
* @since 3.0
*/