org.apache.commons.collections
Class ListUtils

java.lang.Object
  |
  +--org.apache.commons.collections.ListUtils

public class ListUtils
extends java.lang.Object

Contains static utility methods and decorators for List instances.

Since:
1.0
Author:
Federico Barbieri, Peter Donald, Paul Jack, Stephen Colebourne

Constructor Summary
ListUtils()
          Please don't ever instantiate a ListUtils.
 
Method Summary
static java.util.List fixedSizeList(java.util.List list)
          Returns a fixed-sized list backed by the given list.
static java.util.List intersection(java.util.List list1, java.util.List list2)
          Returns a new list containing all elements that are contained in both given lists.
static java.util.List lazyList(java.util.List list, Factory factory)
          Returns a "lazy" list whose elements will be created on demand.
static java.util.List predicatedList(java.util.List list, Predicate predicate)
          Returns a predicated list backed by the given list.
static java.util.List subtract(java.util.List list1, java.util.List list2)
          Subtracts all elements in the second list from the first list, placing the results in a new list.
static java.util.List sum(java.util.List list1, java.util.List list2)
          Returns the sum of the given lists.
static java.util.List union(java.util.List list1, java.util.List list2)
          Returns a new list containing the second list appended to the first list.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ListUtils

public ListUtils()
Please don't ever instantiate a ListUtils.

Method Detail

intersection

public static java.util.List intersection(java.util.List list1,
                                          java.util.List list2)
Returns a new list containing all elements that are contained in both given lists.

Parameters:
list1 - the first list
list2 - the second list
Returns:
the intersection of those two lists
Throws:
java.lang.NullPointerException - if either list is null

subtract

public static java.util.List subtract(java.util.List list1,
                                      java.util.List list2)
Subtracts all elements in the second list from the first list, placing the results in a new list. This differs from List.removeAll(Collection) in that cardinality is respected; if list1 contains two occurrences of null and list2 only contains one occurrence, then the returned list will still contain one occurrence.

Parameters:
list1 - the list to subtract from
list2 - the lsit to subtract
Returns:
a new list containing the results
Throws:
java.lang.NullPointerException - if either list is null

sum

public static java.util.List sum(java.util.List list1,
                                 java.util.List list2)
Returns the sum of the given lists. This is their intersection subtracted from their union.

Parameters:
list1 - the first list
list2 - the second list
Returns:
a new list containing the sum of those lists
Throws:
java.lang.NullPointerException - if either list is null

union

public static java.util.List union(java.util.List list1,
                                   java.util.List list2)
Returns a new list containing the second list appended to the first list. The List.addAll(Collection) operation is used to append the two given lists into a new list.

Parameters:
list1 - the first list
list2 - the second list
Returns:
a new list containing the union of those lists
Throws:
java.lang.NullPointerException - if either list is null

predicatedList

public static java.util.List predicatedList(java.util.List list,
                                            Predicate predicate)
Returns a predicated list backed by the given list. Only objects that pass the test in the given predicate can be added to the list. It is important not to use the original list after invoking this method, as it is a backdoor for adding unvalidated objects.

Parameters:
list - the list to predicate, must not be null
predicate - the predicate for the list, must not be null
Returns:
a predicated list backed by the given list
Throws:
java.lang.IllegalArgumentException - if the List or Predicate is null

lazyList

public static java.util.List lazyList(java.util.List list,
                                      Factory factory)
Returns a "lazy" list whose elements will be created on demand.

When the index passed to the returned list's 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.

For instance:

 Factory factory = new Factory() {
     public Object create() {
         return new Date();
     }
 }
 List lazy = ListUtils.lazyList(new ArrayList(), factory);
 Object obj = lazy.get(3);
 
After the above code is executed, obj will contain a new Date instance. Furthermore, that Date instance is the fourth element in the list. The first, second, and third element are all set to null.

Parameters:
list - the list to make lazy, must not be null
factory - the factory for creating new objects, must not be null
Returns:
a lazy list backed by the given list
Throws:
java.lang.IllegalArgumentException - if the List or Factory is null

fixedSizeList

public static java.util.List fixedSizeList(java.util.List list)
Returns a fixed-sized list backed by the given list. Elements may not be added or removed from the returned list, but existing elements can be changed (for instance, via the List.set(int,Object) method).

Parameters:
list - the list whose size to fix, must not be null
Returns:
a fixed-size list backed by that list
Throws:
java.lang.IllegalArgumentException - if the List is null


Copyright © 2001-2004 The Apache Software Foundation. All Rights Reserved.