A Guide to Apache Commons Collections CollectionUtils

1. Overview

Simply put, the Apache CollectionUtils provides utility methods for common operations which cover a wide range of use cases and helps in avoiding writing boilerplate code. The library targets older JVM releases because currently, similar functionality is provided by the Java 8’s Stream API.

2. Maven Dependencies

We need to add the following dependency to get going with CollectionUtils:

<dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-collections4</artifactId>
    <version>4.1</version>
</dependency>

The latest version of the library can be found here.

3. Setup

Let’s add Customer and Address classes:

public class Customer {
    private Integer id;
    private String name;
    private Address address;

    // standard getters and setters
}

public class Address {
    private String locality;
    private String city;
   
    // standard getters and setters
}

We will also keep handy the following Customer and List instances ready to test our implementation:

Customer customer1 = new Customer(1, "Daniel", "locality1", "city1");
Customer customer2 = new Customer(2, "Fredrik", "locality2", "city2");
Customer customer3 = new Customer(3, "Kyle", "locality3", "city3");
Customer customer4 = new Customer(4, "Bob", "locality4", "city4");
Customer customer5 = new Customer(5, "Cat", "locality5", "city5");
Customer customer6 = new Customer(6, "John", "locality6", "city6");

List<Customer> list1 = Arrays.asList(customer1, customer2, customer3);
List<Customer> list2 = Arrays.asList(customer4, customer5, customer6);
List<Customer> list3 = Arrays.asList(customer1, customer2);

List<Customer> linkedList1 = new LinkedList<>(list1);

4. CollectionUtils

Let’s go through some of the most used methods in Apache Commons CollectionUtils class.

4.1. Adding Only Non-Null Elements

We can use CollectionUtils’s addIgnoreNull method to add only non-null elements to a provided collection.

The first argument to this method is the collection to which we want to add the element and the second argument is the element that we want to add:

@Test
public void givenList_whenAddIgnoreNull_thenNoNullAdded() {
    CollectionUtils.addIgnoreNull(list1, null);
 
    assertFalse(list1.contains(null));
}

Notice that the null was not added to the list.

4.2. Collating Lists

We can use collate method to collate two already sorted lists. This method takes both lists, that we want to merge, as arguments and returns a single sorted list:

@Test
public void givenTwoSortedLists_whenCollated_thenSorted() {
    List<Customer> sortedList = CollectionUtils.collate(list1, list2);

    assertEquals(6, sortedList.size()); 
    assertTrue(sortedList.get(0).getName().equals("Bob"));
    assertTrue(sortedList.get(2).getName().equals("Daniel"));
}

4.3. Transforming Objects

We can use the transform method to transform objects of class A into different objects of class B. This method takes a list of objects of class A and a transformer as arguments.

The result of this operation is a list of objects of class B:

@Test
public void givenListOfCustomers_whenTransformed_thenListOfAddress() {
    Collection<Address> addressCol = CollectionUtils.collect(list1, 
      new Transformer<Customer, Address>() {
        public Address transform(Customer customer) {
            return customer.getAddress();
        }
    });
    
    List<Address> addressList = new ArrayList<>(addressCol);
    assertTrue(addressList.size() == 3);
    assertTrue(addressList.get(0).getLocality().equals("locality1"));
}

4.4. Filtering Objects

Using filter we can remove objects which do not satisfy a given condition from a list. The method takes the list as the first argument and a Predicate as its second argument.

The filterInverse method does the opposite. It removes objects from the list when the Predicate returns true.

Both filter and filterInverse return true if the input list was modified, i.e. if at least one object was filtered out from the list:

@Test
public void givenCustomerList_WhenFiltered_thenCorrectSize() {
    
    boolean isModified = CollectionUtils.filter(linkedList1, 
      new Predicate<Customer>() {
        public boolean evaluate(Customer customer) {
            return Arrays.asList("Daniel","Kyle").contains(customer.getName());
        }
    });
     
    assertTrue(linkedList1.size() == 2);
}

We can use select and selectRejected if we want the resultant list to be returned rather than a boolean flag.

4.5.  Checking For Non-Empty

The isNotEmpty method is quite handy when we want to check if there is at least single element in a list. The other way of checking the same is:

boolean isNotEmpty = (list != null && list.size() > 0);

Though the above line of code does the same, CollectionUtils.isNotEmpty keeps our code cleaner:

@Test
public void givenNonEmptyList_whenCheckedIsNotEmpty_thenTrue() {
    assertTrue(CollectionUtils.isNotEmpty(list1));
}

The isEmpty does the opposite. It checks whether the given list is null or there are zero elements in the list:

List<Customer> emptyList = new ArrayList<>();
List<Customer> nullList = null;
 
assertTrue(CollectionUtils.isEmpty(nullList));
assertTrue(CollectionUtils.isEmpty(emptyList));

4.6. Checking Inclusion

We can use isSubCollection to check if a collection is contained in another collection. isSubCollection takes two collections as arguments and returns true if the first collection is a subcollection of the second collection:

@Test
public void givenCustomerListAndASubcollection_whenChecked_thenTrue() {
    assertTrue(CollectionUtils.isSubCollection(list3, list1));
}

A collection is sub-collection of another collection if the number of times an object occurs in the first collection is less than or equal to the number of times it occurs in the second collection.

4.7. Intersection Of Collections

We can use CollectionUtils.intersection method to get the intersection of two collections. This method takes two collections and returns a collection of elements of which are common in both the input collections:

@Test
public void givenTwoLists_whenIntersected_thenCheckSize() {
    Collection<Customer> intersection = CollectionUtils.intersection(list1, list3);
    assertTrue(intersection.size() == 2);
}

The number of times an element occurs in the resultant collection is a minimum of the number of times it occurs in each of the given collections.

4.8. Subtracting Collections

CollectionUtils.subtract takes two collections as input and returns a collection which contains elements which are there in the first collection but not in the second collection:

@Test
public void givenTwoLists_whenSubtracted_thenCheckElementNotPresentInA() {
    Collection<Customer> result = CollectionUtils.subtract(list1, list3);
    assertFalse(result.contains(customer1));
}

The number of times a collection occurs in the result is the number of times it occurs in first collection minus the number of times it occurs in the second collection.

4.9. Union Of Collections

CollectionUtils.union does the union of two collections and returns a collection which contains all the elements which are there in either the first or the second collection.

@Test
public void givenTwoLists_whenUnioned_thenCheckElementPresentInResult() {
    Collection<Customer> union = CollectionUtils.union(list1, list2);
 
    assertTrue(union.contains(customer1));
    assertTrue(union.contains(customer4));
}

The number of times an element occurs in the resulting collection is the maximum of the number of times it occurs in each of the given collections.

5. Conclusion

And we’re done.

We went through some of the commonly used methods of CollectionUtils – which is very much useful to avoid boilerplate when we’re working with collections in our Java projects.

As usual, the code is available over on GitHub.