This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-collections.git
The following commit(s) were added to refs/heads/master by this push:
new 8831944e5 Javadoc
8831944e5 is described below
commit 8831944e5c176688a89d6cfbded8dbe1951cc8a7
Author: Gary Gregory <[email protected]>
AuthorDate: Tue Dec 30 13:39:38 2025 +0000
Javadoc
---
.../collection/AbstractCollectionTest.java | 208 +++++++++++----------
.../collections4/list/AbstractListTest.java | 106 +++++------
2 files changed, 158 insertions(+), 156 deletions(-)
diff --git
a/src/test/java/org/apache/commons/collections4/collection/AbstractCollectionTest.java
b/src/test/java/org/apache/commons/collections4/collection/AbstractCollectionTest.java
index bec79c3e0..425b83b00 100644
---
a/src/test/java/org/apache/commons/collections4/collection/AbstractCollectionTest.java
+++
b/src/test/java/org/apache/commons/collections4/collection/AbstractCollectionTest.java
@@ -261,45 +261,45 @@ public abstract class AbstractCollectionTest<E> extends
AbstractObjectTest {
}
/**
- * A collection instance that will be used for testing.
+ * A collection instance that will be used for testing.
*/
private Collection<E> collection;
/**
- * Confirmed collection. This is an instance of a collection that is
- * confirmed to conform exactly to the java.util.Collection contract.
- * Modification operations are tested by performing a mod on your
- * collection, performing the exact same mod on an equivalent confirmed
- * collection, and then calling verify() to make sure your collection
- * still matches the confirmed collection.
+ * Confirmed collection. This is an instance of a collection that is
+ * confirmed to conform exactly to the java.util.Collection contract.
+ * Modification operations are tested by performing a mod on your
+ * collection, performing the exact same mod on an equivalent confirmed
+ * collection, and then calling verify() to make sure your collection
+ * still matches the confirmed collection.
*/
private Collection<E> confirmed;
/**
- * Specifies whether equal elements in the collection are, in fact,
- * distinguishable with information not readily available.
- * <p>
- * If a particular value is to be removed from the collection, then there
is
- * one and only one value that can be removed, even if there are other
- * elements which are equal to it.
- * </p>
- * <p>
- * In most collection cases, elements are not distinguishable (equal is
- * equal), thus this method defaults to return false. In some cases,
- * however, they are. For example, the collection returned from the map's
- * values() collection view are backed by the map, so while there may be
- * two values that are equal, their associated keys are not. Since the
- * keys are distinguishable, the values are.
- * </p>
- * <p>
- * This flag is used to skip some verifications for iterator.remove()
- * where it is impossible to perform an equivalent modification on the
- * confirmed collection because it is not possible to determine which
- * value in the confirmed collection to actually remove. Tests that
- * override the default (i.e. where equal elements are distinguishable),
- * should provide additional tests on iterator.remove() to make sure the
- * proper elements are removed when remove() is called on the iterator.
- * </p>
+ * Specifies whether equal elements in the collection are, in fact,
+ * distinguishable with information not readily available.
+ * <p>
+ * If a particular value is to be removed from the collection, then there
is
+ * one and only one value that can be removed, even if there are other
+ * elements which are equal to it.
+ * </p>
+ * <p>
+ * In most collection cases, elements are not distinguishable (equal is
+ * equal), thus this method defaults to return false. In some cases,
+ * however, they are. For example, the collection returned from the map's
+ * values() collection view are backed by the map, so while there may be
+ * two values that are equal, their associated keys are not. Since the
+ * keys are distinguishable, the values are.
+ * </p>
+ * <p>
+ * This flag is used to skip some verifications for iterator.remove()
+ * where it is impossible to perform an equivalent modification on the
+ * confirmed collection because it is not possible to determine which
+ * value in the confirmed collection to actually remove. Tests that
+ * override the default (i.e. where equal elements are distinguishable),
+ * should provide additional tests on iterator.remove() to make sure the
+ * proper elements are removed when remove() is called on the iterator.
+ * </p>
*/
public boolean areEqualElementsDistinguishable() {
return false;
@@ -323,18 +323,18 @@ public abstract class AbstractCollectionTest<E> extends
AbstractObjectTest {
}
/**
- * Returns an array of objects that are contained in a collection
- * produced by {@link #makeFullCollection()}.
- * <p>
- * Every element in the returned array <em>must</em> be an element in a
full collection.
- * </p>
- * <p>
- * The default implementation returns a heterogeneous array of
- * objects with some duplicates. null is added if allowed.
- * Override if you require specific testing elements. Note that if you
- * override {@link #makeFullCollection()}, you <em>must</em> override
- * this method to reflect the contents of a full collection.
- * <p>
+ * Returns an array of objects that are contained in a collection
+ * produced by {@link #makeFullCollection()}.
+ * <p>
+ * Every element in the returned array <em>must</em> be an element in a
full collection.
+ * </p>
+ * <p>
+ * The default implementation returns a heterogeneous array of
+ * objects with some duplicates. null is added if allowed.
+ * Override if you require specific testing elements. Note that if you
+ * override {@link #makeFullCollection()}, you <em>must</em> override
+ * this method to reflect the contents of a full collection.
+ * <p>
*/
@SuppressWarnings("unchecked")
public E[] getFullElements() {
@@ -347,12 +347,12 @@ public abstract class AbstractCollectionTest<E> extends
AbstractObjectTest {
}
/**
- * Returns a list of elements suitable for return by
- * {@link #getFullElements()}. The array returned by this method
- * does not include null, but does include a variety of objects
- * of different types. Override getFullElements to return
- * the results of this method if your collection does not support
- * the null element.
+ * Returns a list of elements suitable for return by
+ * {@link #getFullElements()}. The array returned by this method
+ * does not include null, but does include a variety of objects
+ * of different types. Override getFullElements to return
+ * the results of this method if your collection does not support
+ * the null element.
*/
@SuppressWarnings("unchecked")
public E[] getFullNonNullElements() {
@@ -379,10 +379,10 @@ public abstract class AbstractCollectionTest<E> extends
AbstractObjectTest {
}
/**
- * Returns a list of string elements suitable for return by
- * {@link #getFullElements()}. Override getFullElements to return
- * the results of this method if your collection does not support
- * heterogeneous elements or the null element.
+ * Returns a list of string elements suitable for return by
+ * {@link #getFullElements()}. Override getFullElements to return
+ * the results of this method if your collection does not support
+ * heterogeneous elements or the null element.
*/
public Object[] getFullNonNullStringElements() {
return new Object[] {
@@ -404,22 +404,22 @@ public abstract class AbstractCollectionTest<E> extends
AbstractObjectTest {
}
/**
- * Returns an array of elements that are <em>not</em> contained in a
- * full collection. Every element in the returned array must
- * not exist in a collection returned by {@link #makeFullCollection()}.
- * The default implementation returns a heterogeneous array of elements
- * without null. Note that some of the tests add these elements
- * to an empty or full collection, so if your collection restricts
- * certain kinds of elements, you should override this method.
+ * Returns an array of elements that are <em>not</em> contained in a
+ * full collection. Every element in the returned array must
+ * not exist in a collection returned by {@link #makeFullCollection()}.
+ * The default implementation returns a heterogeneous array of elements
+ * without null. Note that some of the tests add these elements
+ * to an empty or full collection, so if your collection restricts
+ * certain kinds of elements, you should override this method.
*/
public E[] getOtherElements() {
return getOtherNonNullElements();
}
/**
- * Returns the default list of objects returned by
- * {@link #getOtherElements()}. Includes many objects
- * of different types.
+ * Returns the default list of objects returned by
+ * {@link #getOtherElements()}. Includes many objects
+ * of different types.
*/
@SuppressWarnings("unchecked")
public E[] getOtherNonNullElements() {
@@ -437,10 +437,10 @@ public abstract class AbstractCollectionTest<E> extends
AbstractObjectTest {
}
/**
- * Returns a list of string elements suitable for return by
- * {@link #getOtherElements()}. Override getOtherElements to return
- * the results of this method if your collection does not support
- * heterogeneous elements or the null element.
+ * Returns a list of string elements suitable for return by
+ * {@link #getOtherElements()}. Override getOtherElements to return
+ * the results of this method if your collection does not support
+ * heterogeneous elements or the null element.
*/
public Object[] getOtherNonNullStringElements() {
return new Object[] {
@@ -450,14 +450,14 @@ public abstract class AbstractCollectionTest<E> extends
AbstractObjectTest {
}
/**
- * Returns true if the collections produced by
- * {@link #makeObject()} and {@link #makeFullCollection()}
- * support the {@code add} and {@code addAll}
- * operations.
- * <p>
- * Default implementation returns true. Override if your collection
- * class does not support add or addAll.
- * </p>
+ * Returns true if the collections produced by
+ * {@link #makeObject()} and {@link #makeFullCollection()}
+ * support the {@code add} and {@code addAll}
+ * operations.
+ * <p>
+ * Default implementation returns true. Override if your collection
+ * class does not support add or addAll.
+ * </p>
*/
public boolean isAddSupported() {
return true;
@@ -489,44 +489,44 @@ public abstract class AbstractCollectionTest<E> extends
AbstractObjectTest {
}
/**
- * Returns true if the collections produced by
- * {@link #makeObject()} and {@link #makeFullCollection()}
- * support the {@code remove}, {@code removeAll},
- * {@code retainAll}, {@code clear} and
- * {@code iterator().remove()} methods.
- * Default implementation returns true. Override if your collection
- * class does not support removal operations.
+ * Returns true if the collections produced by
+ * {@link #makeObject()} and {@link #makeFullCollection()}
+ * support the {@code remove}, {@code removeAll},
+ * {@code retainAll}, {@code clear} and
+ * {@code iterator().remove()} methods.
+ * Default implementation returns true. Override if your collection
+ * class does not support removal operations.
*/
public boolean isRemoveSupported() {
return true;
}
/**
- * Returns a confirmed empty collection.
- * For instance, an {@link java.util.ArrayList} for lists or a
- * {@link java.util.HashSet} for sets.
+ * Returns a confirmed empty collection.
+ * For instance, an {@link java.util.ArrayList} for lists or a
+ * {@link java.util.HashSet} for sets.
*
- * @return a confirmed empty collection
+ * @return a confirmed empty collection
*/
public abstract Collection<E> makeConfirmedCollection();
/**
- * Returns a confirmed full collection.
- * For instance, an {@link java.util.ArrayList} for lists or a
- * {@link java.util.HashSet} for sets. The returned collection
- * should contain the elements returned by {@link #getFullElements()}.
+ * Returns a confirmed full collection.
+ * For instance, an {@link java.util.ArrayList} for lists or a
+ * {@link java.util.HashSet} for sets. The returned collection
+ * should contain the elements returned by {@link #getFullElements()}.
*
- * @return a confirmed full collection
+ * @return a confirmed full collection
*/
public abstract Collection<E> makeConfirmedFullCollection();
/**
- * Returns a full collection to be used for testing. The collection
- * returned by this method should contain every element returned by
- * {@link #getFullElements()}. The default implementation, in fact,
- * simply invokes {@code addAll} on an empty collection with
- * the results of {@link #getFullElements()}. Override this default
- * if your collection doesn't support addAll.
+ * Returns a full collection to be used for testing. The collection
+ * returned by this method should contain every element returned by
+ * {@link #getFullElements()}. The default implementation, in fact,
+ * simply invokes {@code addAll} on an empty collection with
+ * the results of {@link #getFullElements()}. Override this default
+ * if your collection doesn't support addAll.
*/
public Collection<E> makeFullCollection() {
final Collection<E> c = makeObject();
@@ -541,9 +541,9 @@ public abstract class AbstractCollectionTest<E> extends
AbstractObjectTest {
public abstract Collection<E> makeObject();
/**
- * Resets the {@link #collection} and {@link #confirmed} fields to empty
- * collections. Invoke this method before performing a modification
- * test.
+ * Resets the {@link #collection} and {@link #confirmed} fields to empty
+ * collections. Invoke this method before performing a modification
+ * test.
*/
public void resetEmpty() {
this.setCollection(makeObject());
@@ -551,9 +551,9 @@ public abstract class AbstractCollectionTest<E> extends
AbstractObjectTest {
}
/**
- * Resets the {@link #collection} and {@link #confirmed} fields to full
- * collections. Invoke this method before performing a modification
- * test.
+ * Resets the {@link #collection} and {@link #confirmed} fields to full
+ * collections. Invoke this method before performing a modification
+ * test.
*/
public void resetFull() {
this.setCollection(makeFullCollection());
@@ -562,6 +562,7 @@ public abstract class AbstractCollectionTest<E> extends
AbstractObjectTest {
/**
* Sets the collection.
+ *
* @param collection the Collection<E> to set
*/
public void setCollection(final Collection<E> collection) {
@@ -570,6 +571,7 @@ public abstract class AbstractCollectionTest<E> extends
AbstractObjectTest {
/**
* Sets the confirmed.
+ *
* @param confirmed the Collection<E> to set
*/
public void setConfirmed(final Collection<E> confirmed) {
diff --git
a/src/test/java/org/apache/commons/collections4/list/AbstractListTest.java
b/src/test/java/org/apache/commons/collections4/list/AbstractListTest.java
index 839b82d42..f1dad5c1b 100644
--- a/src/test/java/org/apache/commons/collections4/list/AbstractListTest.java
+++ b/src/test/java/org/apache/commons/collections4/list/AbstractListTest.java
@@ -167,10 +167,10 @@ public abstract class AbstractListTest<E> extends
AbstractCollectionTest<E> {
}
/**
- * Traverses to the beginning of the given iterator.
+ * Traverses to the beginning of the given iterator.
*
- * @param iter the iterator to traverse
- * @param i the starting index
+ * @param iter the iterator to traverse
+ * @param i the starting index
*/
private void backwardTest(final ListIterator<E> iter, int i) {
final List<E> list = getCollection();
@@ -203,14 +203,14 @@ public abstract class AbstractListTest<E> extends
AbstractCollectionTest<E> {
}
/**
- * Returns a {@link BulkTest} for testing {@link List#subList(int,int)}.
- * The returned bulk test will run through every {@code TestList}
- * method, <em>including</em> another {@code bulkTestSubList}.
- * Sublists are tested until the size of the sublist is less than 10.
- * Each sublist is 6 elements smaller than its parent list.
- * (By default this means that two rounds of sublists will be tested).
- * The verify() method is overloaded to test that the original list is
- * modified when the sublist is.
+ * Returns a {@link BulkTest} for testing {@link List#subList(int,int)}.
+ * The returned bulk test will run through every {@code TestList}
+ * method, <em>including</em> another {@code bulkTestSubList}.
+ * Sublists are tested until the size of the sublist is less than 10.
+ * Each sublist is 6 elements smaller than its parent list.
+ * (By default this means that two rounds of sublists will be tested).
+ * The verify() method is overloaded to test that the original list is
+ * modified when the sublist is.
*/
public BulkTest bulkTestSubList() {
if (getFullElements().length - 6 < 10) {
@@ -271,10 +271,10 @@ public abstract class AbstractListTest<E> extends
AbstractCollectionTest<E> {
}
/**
- * Traverses to the end of the given iterator.
+ * Traverses to the end of the given iterator.
*
- * @param iter the iterator to traverse
- * @param i the starting index
+ * @param iter the iterator to traverse
+ * @param i the starting index
*/
private void forwardTest(final ListIterator<E> iter, int i) {
final List<E> list = getCollection();
@@ -328,11 +328,11 @@ public abstract class AbstractListTest<E> extends
AbstractCollectionTest<E> {
}
/**
- * Returns true if the collections produced by
- * {@link #makeObject()} and {@link #makeFullCollection()}
- * support the <code>set operation.<p>
- * Default implementation returns true. Override if your collection
- * class does not support set.
+ * Returns true if the collections produced by
+ * {@link #makeObject()} and {@link #makeFullCollection()}
+ * support the <code>set operation.<p>
+ * Default implementation returns true. Override if your collection
+ * class does not support set.
*/
public boolean isSetSupported() {
return true;
@@ -458,7 +458,7 @@ public abstract class AbstractListTest<E> extends
AbstractCollectionTest<E> {
}
/**
- * Tests {@link List#add(int,Object)}.
+ * Tests {@link List#add(int,Object)}.
*/
@Test
void testListAddByIndex() {
@@ -478,8 +478,8 @@ public abstract class AbstractListTest<E> extends
AbstractCollectionTest<E> {
}
/**
- * Tests bounds checking for {@link List#add(int, Object)} on an
- * empty list.
+ * Tests bounds checking for {@link List#add(int, Object)} on an
+ * empty list.
*/
@Test
void testListAddByIndexBoundsChecking() {
@@ -507,8 +507,8 @@ public abstract class AbstractListTest<E> extends
AbstractCollectionTest<E> {
}
/**
- * Tests bounds checking for {@link List#add(int, Object)} on a
- * full list.
+ * Tests bounds checking for {@link List#add(int, Object)} on a
+ * full list.
*/
@Test
void testListAddByIndexBoundsChecking2() {
@@ -536,7 +536,7 @@ public abstract class AbstractListTest<E> extends
AbstractCollectionTest<E> {
}
/**
- * Tests {@link List#equals(Object)}.
+ * Tests {@link List#equals(Object)}.
*/
@Test
void testListEquals() {
@@ -607,7 +607,7 @@ public abstract class AbstractListTest<E> extends
AbstractCollectionTest<E> {
}
/**
- * Tests {@link List#get(int)}.
+ * Tests {@link List#get(int)}.
*/
@Test
void testListGetByIndex() {
@@ -621,8 +621,8 @@ public abstract class AbstractListTest<E> extends
AbstractCollectionTest<E> {
}
/**
- * Tests bounds checking for {@link List#get(int)} on an
- * empty list.
+ * Tests bounds checking for {@link List#get(int)} on an
+ * empty list.
*/
@Test
void testListGetByIndexBoundsChecking() {
@@ -645,8 +645,8 @@ public abstract class AbstractListTest<E> extends
AbstractCollectionTest<E> {
}
/**
- * Tests bounds checking for {@link List#get(int)} on a
- * full list.
+ * Tests bounds checking for {@link List#get(int)} on a
+ * full list.
*/
@Test
void testListGetByIndexBoundsChecking2() {
@@ -666,7 +666,7 @@ public abstract class AbstractListTest<E> extends
AbstractCollectionTest<E> {
}
/**
- * Tests {@link List#hashCode()}.
+ * Tests {@link List#hashCode()}.
*/
@Test
void testListHashCode() {
@@ -684,7 +684,7 @@ public abstract class AbstractListTest<E> extends
AbstractCollectionTest<E> {
}
/**
- * Tests {@link List#indexOf}.
+ * Tests {@link List#indexOf}.
*/
@Test
void testListIndexOf() {
@@ -707,8 +707,8 @@ public abstract class AbstractListTest<E> extends
AbstractCollectionTest<E> {
}
/**
- * Tests the {@link ListIterator#add(Object)} method of the list
- * iterator.
+ * Tests the {@link ListIterator#add(Object)} method of the list
+ * iterator.
*/
@Test
void testListIteratorAdd() {
@@ -743,8 +743,8 @@ public abstract class AbstractListTest<E> extends
AbstractCollectionTest<E> {
}
/**
- * Tests the {@link ListIterator#set(Object)} method of the list
- * iterator.
+ * Tests the {@link ListIterator#set(Object)} method of the list
+ * iterator.
*/
@Test
void testListIteratorSet() {
@@ -767,7 +767,7 @@ public abstract class AbstractListTest<E> extends
AbstractCollectionTest<E> {
}
/**
- * Tests {@link List#lastIndexOf}.
+ * Tests {@link List#lastIndexOf}.
*/
@Test
void testListLastIndexOf() {
@@ -790,7 +790,7 @@ public abstract class AbstractListTest<E> extends
AbstractCollectionTest<E> {
}
/**
- * Tests the read-only bits of {@link List#listIterator()}.
+ * Tests the read-only bits of {@link List#listIterator()}.
*/
@Test
void testListListIterator() {
@@ -800,7 +800,7 @@ public abstract class AbstractListTest<E> extends
AbstractCollectionTest<E> {
}
/**
- * Tests the read-only bits of {@link List#listIterator(int)}.
+ * Tests the read-only bits of {@link List#listIterator(int)}.
*/
@Test
void testListListIteratorByIndex() {
@@ -945,7 +945,7 @@ public abstract class AbstractListTest<E> extends
AbstractCollectionTest<E> {
}
/**
- * Tests {@link List#remove(int)}.
+ * Tests {@link List#remove(int)}.
*/
@Test
void testListRemoveByIndex() {
@@ -964,8 +964,8 @@ public abstract class AbstractListTest<E> extends
AbstractCollectionTest<E> {
}
/**
- * Tests bounds checking for {@link List#remove(int)} on an
- * empty list.
+ * Tests bounds checking for {@link List#remove(int)} on an
+ * empty list.
*/
@Test
void testListRemoveByIndexBoundsChecking() {
@@ -992,8 +992,8 @@ public abstract class AbstractListTest<E> extends
AbstractCollectionTest<E> {
}
/**
- * Tests bounds checking for {@link List#remove(int)} on a
- * full list.
+ * Tests bounds checking for {@link List#remove(int)} on a
+ * full list.
*/
@Test
void testListRemoveByIndexBoundsChecking2() {
@@ -1017,7 +1017,7 @@ public abstract class AbstractListTest<E> extends
AbstractCollectionTest<E> {
}
/**
- * Test {@link List#set(int,Object)}.
+ * Test {@link List#set(int,Object)}.
*/
@Test
void testListSetByIndex() {
@@ -1039,8 +1039,8 @@ public abstract class AbstractListTest<E> extends
AbstractCollectionTest<E> {
}
/**
- * Tests bounds checking for {@link List#set(int,Object)} on an
- * empty list.
+ * Tests bounds checking for {@link List#set(int,Object)} on an
+ * empty list.
*/
@Test
void testListSetByIndexBoundsChecking() {
@@ -1068,8 +1068,8 @@ public abstract class AbstractListTest<E> extends
AbstractCollectionTest<E> {
}
/**
- * Tests bounds checking for {@link List#set(int,Object)} on a
- * full list.
+ * Tests bounds checking for {@link List#set(int,Object)} on a
+ * full list.
*/
@Test
void testListSetByIndexBoundsChecking2() {
@@ -1169,8 +1169,8 @@ public abstract class AbstractListTest<E> extends
AbstractCollectionTest<E> {
}
/**
- * If {@link #isSetSupported()} returns false, tests that set operation
- * raises <Code>UnsupportedOperationException.
+ * If {@link #isSetSupported()} returns false, tests that set operation
+ * raises <Code>UnsupportedOperationException.
*/
@Test
void testUnsupportedSet() {
@@ -1187,8 +1187,8 @@ public abstract class AbstractListTest<E> extends
AbstractCollectionTest<E> {
}
/**
- * Verifies that the test list implementation matches the confirmed list
- * implementation.
+ * Verifies that the test list implementation matches the confirmed list
+ * implementation.
*/
@Override
@SuppressWarnings("unchecked")
