Add package private unwrap() method

- Add generics for the wrapped type
- Add TODO for remove(): This method can be removed in 5.0 since it's
implemented as a default method in Iterator.
- Improve Javadoc

Author: garydgregory

src/changes/changes.xml

@@ -33,6 +33,7 @@
     <action type="fix" dev="ggregory" due-to="Gary Gregory">Fix exception message in org.apache.commons.collections4.functors.FunctorUtils.validate(Consumer...)</action>
     <action type="fix" dev="ggregory" due-to="Gary Gregory">Fix exception message in org.apache.commons.collections4.iterators.UnmodifiableIterator.remove() to match java.util.Iterator.remove().</action>
     <!-- ADD -->
+    <action type="add" dev="ggregory" due-to="Gary Gregory">Add generics to UnmodifiableIterator for the wrapped type.</action>
     <!-- UPDATE -->
     <action type="update" dev="ggregory" due-to="Gary Gregory, Dependabot">Bump org.apache.commons:commons-parent from 81 to 84 #612.</action>
     <action type="update" dev="ggregory" due-to="Gary Gregory">Bump com.google.guava:guava-testlib from 33.3.1-jre to 33.4.8-jre.</action>

src/main/java/org/apache/commons/collections4/iterators/UnmodifiableIterator.java

@@ -24,13 +24,14 @@
 /**
  * Decorates an iterator such that it cannot be modified.
  * <p>
- * Attempts to modify it will result in an UnsupportedOperationException.
+ * Calling {@link #remove()} throws {@link UnsupportedOperationException}.
  * </p>
  *
  * @param <E> the type of elements returned by this iterator.
+ * @param <T> The wrapped Iterator type.
  * @since 3.0
  */
-public final class UnmodifiableIterator<E> implements Iterator<E>, Unmodifiable {
+public final class UnmodifiableIterator<E, T extends Iterator<? extends E>> implements Iterator<E>, Unmodifiable {
 
     /**
      * Decorates the specified iterator such that it cannot be modified.
@@ -50,18 +51,24 @@ public static <E> Iterator<E> unmodifiableIterator(final Iterator<? extends E> i
             final Iterator<E> tmpIterator = (Iterator<E>) iterator;
             return tmpIterator;
         }
+        return wrap(iterator);
+    }
+
+    static <E, T extends Iterator<? extends E>> UnmodifiableIterator<E, T> wrap(final T iterator) {
         return new UnmodifiableIterator<>(iterator);
     }
 
-    /** The iterator being decorated */
-    private final Iterator<? extends E> iterator;
+    /**
+     * The decorated iterator.
+     */
+    private final T iterator;
 
     /**
      * Constructs a new instance.
      *
-     * @param iterator  the iterator to decorate
+     * @param iterator  the iterator to decorate.
      */
-    private UnmodifiableIterator(final Iterator<? extends E> iterator) {
+    private UnmodifiableIterator(final T iterator) {
         this.iterator = iterator;
     }
 
@@ -75,9 +82,14 @@ public E next() {
         return iterator.next();
     }
 
+    // TODO This method can be removed in 5.0 since it's implemented as a default method in Iterator.
     @Override
     public void remove() {
         throw new UnsupportedOperationException("remove");
     }
 
+    T unwrap() {
+        return iterator;
+    }
+
 }

src/test/java/org/apache/commons/collections4/iterators/UnmodifiableIteratorTest.java

@@ -14,6 +14,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
 package org.apache.commons.collections4.iterators;
 
 import static org.junit.jupiter.api.Assertions.assertNotSame;
@@ -38,8 +39,8 @@
  */
 public class UnmodifiableIteratorTest<E> extends AbstractIteratorTest<E> {
 
-    protected String[] testArray = { "One", "Two", "Three" };
-    protected List<E> testList;
+    private final String[] testArray = { "One", "Two", "Three" };
+    private List<E> testList;
 
     @Override
     public Iterator<E> makeEmptyIterator() {
@@ -66,10 +67,8 @@ public boolean supportsRemove() {
     void testDecorateFactory() {
         Iterator<E> it = makeObject();
         assertSame(it, UnmodifiableIterator.unmodifiableIterator(it));
-
         it = testList.iterator();
         assertNotSame(it, UnmodifiableIterator.unmodifiableIterator(it));
-
         assertThrows(NullPointerException.class, () -> UnmodifiableIterator.unmodifiableIterator(null));
     }
 
@@ -78,4 +77,19 @@ void testIterator() {
         assertTrue(makeEmptyIterator() instanceof Unmodifiable);
     }
 
+    @Test
+    void testUnwrap() {
+        final Iterator<E> iterator = testList.iterator();
+        @SuppressWarnings("unchecked")
+        final UnmodifiableIterator<E, Iterator<E>> unmodifiableIterator = (UnmodifiableIterator<E, Iterator<E>>) UnmodifiableIterator
+                .unmodifiableIterator(iterator);
+        assertSame(iterator, unmodifiableIterator.unwrap());
+    }
+
+    @Test
+    void testWrapUnwrap() {
+        final Iterator<E> iterator = testList.iterator();
+        final UnmodifiableIterator<E, Iterator<E>> unmodifiableIterator = UnmodifiableIterator.wrap(iterator);
+        assertSame(iterator, unmodifiableIterator.unwrap());
+    }
 }