OAK-11566 : added util to replace Iterables.find in oak-commons (#2161)

Co-authored-by: Rishabh Kumar <diam@adobe.com>

Author: rishabhdaim

oak-commons/src/main/java/org/apache/jackrabbit/oak/commons/collections/IterableUtils.java

@@ -18,7 +18,6 @@
  */
 package org.apache.jackrabbit.oak.commons.collections;
 
-import org.apache.commons.collections4.Predicate;
 import org.apache.commons.collections4.iterators.LazyIteratorChain;
 import org.apache.jackrabbit.oak.commons.conditions.Validate;
 import org.jetbrains.annotations.NotNull;
@@ -32,6 +31,7 @@
 import java.util.NoSuchElementException;
 import java.util.Objects;
 import java.util.function.Function;
+import java.util.function.Predicate;
 import java.util.stream.Collectors;
 
 /**
@@ -188,7 +188,7 @@ public static int size(final Iterable<?> itr) {
      * @throws NullPointerException if the iterable or predicate is null
      */
     public static <E> boolean matchesAll(final Iterable<E> itr, final Predicate<? super E> predicate) {
-        return org.apache.commons.collections4.IterableUtils.matchesAll(itr, predicate);
+        return org.apache.commons.collections4.IterableUtils.matchesAll(itr, predicate::test);
     }
 
     /**
@@ -274,7 +274,7 @@ public List<T> next() {
      * @throws NullPointerException if the iterable or predicate is null
      */
     public static <E> Iterable<E> filter(final Iterable<E> itr, final Predicate<? super E> predicate) {
-        return org.apache.commons.collections4.IterableUtils.filteredIterable(itr, predicate);
+        return org.apache.commons.collections4.IterableUtils.filteredIterable(itr, predicate::test);
     }
 
     /**
@@ -428,4 +428,22 @@ public static <T> T get(final Iterable<T> iterable, final int index) {
         Objects.requireNonNull(iterable, "Iterable must not be null.");
         return org.apache.commons.collections4.IterableUtils.get(iterable, index);
     }
+
+    /**
+     * Returns the first element in the specified iterable that matches the given predicate.
+     * <p>
+     * The iterable is traversed until an element is found that satisfies the predicate.
+     * If no element satisfies the predicate, {@code null} is returned.
+     *
+     * @param <T> the type of elements in the iterable
+     * @param iterable the iterable to search, must not be null
+     * @param predicate the predicate to apply, must not be null
+     * @return the first element that satisfies the predicate, or null if no such element exists
+     * @throws NullPointerException if either the iterable or predicate is null
+     */
+    public static <T> T find(final Iterable<T> iterable, final Predicate<? super T> predicate) {
+        Objects.requireNonNull(iterable, "Iterable must not be null.");
+        Objects.requireNonNull(predicate, "Predicate must not be null.");
+        return org.apache.commons.collections4.IterableUtils.find(iterable, predicate::test);
+    }
 }

oak-commons/src/test/java/org/apache/jackrabbit/oak/commons/collections/IterableUtilsTest.java

@@ -18,7 +18,6 @@
  */
 package org.apache.jackrabbit.oak.commons.collections;
 
-import org.apache.commons.collections4.Predicate;
 import org.junit.Assert;
 import org.junit.Test;
 
@@ -31,6 +30,7 @@
 import java.util.List;
 import java.util.NoSuchElementException;
 import java.util.function.Function;
+import java.util.function.Predicate;
 
 /**
  * Unit tests for the {@link IterableUtils} class.
@@ -969,4 +969,65 @@ public void testGetWithSingleElementIterable() {
         String result = IterableUtils.get(list, 0);
         Assert.assertEquals("only", result);
     }
+
+    @Test
+    public void testFindWithMatchingElement() {
+        List<String> list = Arrays.asList("apple", "banana", "cherry");
+        String result = IterableUtils.find(list, s -> s.startsWith("b"));
+        Assert.assertEquals("banana", result);
+    }
+
+    @Test
+    public void testFindWithNoMatchingElement() {
+        List<String> list = Arrays.asList("apple", "banana", "cherry");
+        String result = IterableUtils.find(list, s -> s.startsWith("d"));
+        Assert.assertNull(result);
+    }
+
+    @Test
+    public void testFindWithMultipleMatchingElements() {
+        List<String> list = Arrays.asList("apple", "avocado", "banana", "apricot");
+        String result = IterableUtils.find(list, s -> s.startsWith("a"));
+        // Should return the first matching element
+        Assert.assertEquals("apple", result);
+    }
+
+    @Test
+    public void testFindWithEmptyIterable() {
+        List<String> list = Collections.emptyList();
+        String result = IterableUtils.find(list, s -> true);
+        Assert.assertNull(result);
+    }
+
+    @Test(expected = NullPointerException.class)
+    public void testFindWithNullIterable() {
+        IterableUtils.find(null, s -> true);
+    }
+
+    @Test(expected = NullPointerException.class)
+    public void testFindWithNullPredicate() {
+        List<String> list = Arrays.asList("apple", "banana", "cherry");
+        IterableUtils.find(list, null);
+    }
+
+    @Test
+    public void testFindFirstElement() {
+        List<Integer> list = Arrays.asList(10, 20, 30, 40, 50);
+        Integer result = IterableUtils.find(list, i -> i > 5);
+        Assert.assertEquals(Integer.valueOf(10), result);
+    }
+
+    @Test
+    public void testFindLastElement() {
+        List<Integer> list = Arrays.asList(10, 20, 30, 40, 50);
+        Integer result = IterableUtils.find(list, i -> i > 45);
+        Assert.assertEquals(Integer.valueOf(50), result);
+    }
+
+    @Test
+    public void testFindWithCustomIterable() {
+        Iterable<Integer> customIterable = () -> Arrays.asList(5, 10, 15, 20, 25).iterator();
+        Integer result = IterableUtils.find(customIterable, i -> i % 10 == 0);
+        Assert.assertEquals(Integer.valueOf(10), result);
+    }
 }