org.pf.util
Class CollectionUtil

java.lang.Object
  org.pf.util.CollectionUtil

public class CollectionUtil
extends java.lang.Object

This class implements the singleton pattern. Access the sole instance with the method current(). Provides helpful functions on collections.

Version:

1.9

Author:

Manfred Duchrow

Field Summary

static java.util.List	EMPTY_LIST A constant that contains an immutable empty List.
static java.util.Map	EMPTY_MAP A constant that contains an immutable empty Map.
static java.util.Set	EMPTY_SET A constant that contains an immutable empty Set.

Method Summary

void	addAll(java.util.Collection collection, java.lang.Object[] objects) Adds all given objects to the specified collection.
void	addAllNew(java.util.Collection collection, java.lang.Object[] objects) Adds all given objects to the specified collection, if they are not already in the collection.
java.util.Iterator	asIterator(java.util.Enumeration enumeration) Returns an iterator based on the given enumeration or null if the input parameter is null, too.
java.util.List	asList(java.util.Enumeration enumeration) Returns a list containing all elements of the given enumeration.
boolean	contains(int[] valueArray, int value) Returns true only if the given value is found in the given array.
boolean	contains(long[] valueArray, long value) Returns true only if the given value is found in the given array.
boolean	contains(java.lang.Object[] objArray, java.lang.Object searchObj) Returns true if the search object exists in the given object array.
boolean	containsIdentical(java.lang.Object[] objArray, java.lang.Object searchObj) Returns true if the search object exists in the given object array.
java.util.Collection	copy(java.util.Collection objects, IObjectFilter filter) Returns a copy of the given collection which contains only those objects that match the given filter.
java.util.Map	copy(java.util.Map map, IObjectFilter filter) Returns a copy of the given map which contains only those objects that match the given filter.
java.lang.Object[]	copy(java.lang.Object[] objects) Returns a copy of the given object array.
java.lang.Object[]	copy(java.lang.Object[] objects, IObjectFilter filter) Returns a copy of the given object array which contains only those objects that match the given filter.
void	copyPropertiesStartingWith(java.util.Properties source, java.util.Properties destination, java.lang.String prefix, boolean cutPrefix) Copies all properties that start with the given prefix from the specified source properties object to the destination properties.
java.util.Collection	copyWithout(java.util.Collection objects, IObjectFilter filter) Returns a copy of the specified collection that contains only those elements that do NOT match the given filter.
java.util.Map	copyWithout(java.util.Map map, IObjectFilter filter) Returns a copy of the specified map that contains only those elements that do NOT match the given filter.
java.lang.Object[]	copyWithout(java.lang.Object[] objArray, IObjectFilter filter) Returns a copy of the specified array that contains only those elements that do NOT match the given filter.
java.lang.Object[]	copyWithout(java.lang.Object[] objArray, java.lang.Object[] skipArray) Returns a copy of the first array that contains only elements that are not in the second array.
java.lang.Object[]	copyWithoutIdentical(java.lang.Object[] objArray, java.lang.Object[] skipArray) Returns a copy of the first array that contains only elements that are not in the second array.
static CollectionUtil	current() Returns the one and only instance of this class.
int	indexOf(java.util.List list, IObjectFilter filter) Returns the index of the first object in the given list that matches the given filter.
int	indexOf(java.lang.Object[] objArray, IObjectFilter filter) Returns the index of the first object in the given object array that matches the given filter.
int	indexOf(java.lang.Object[] objArray, java.lang.Object searchObj) Returns the index of the search object in the given object array.
int	indexOfIdentical(java.lang.Object[] objArray, java.lang.Object searchObj) Returns the index of the search object in the given object array.
boolean	isNullOrEmpty(AssociationList associationList) Returns true if the given association list is null or has no elements.
boolean	isNullOrEmpty(java.util.Collection collection) Returns true if the given collection is null or has no elements.
boolean	isNullOrEmpty(java.util.Map map) Returns true if the given map is null or has no elements.
boolean	isNullOrEmpty(java.lang.Object[] array) Returns true if the given array is null or has no elements.
java.util.Iterator	iterator(java.lang.Object[] objects) Returns an iterator on the given array.
int	lastIndexOf(java.util.List list, IObjectFilter filter) Returns the index of the last object in the given list that matches the given filter.
int	lastIndexOf(java.lang.Object[] objArray, IObjectFilter filter) Returns the index of the last object in the given object array that matches the given filter.
java.util.Properties	propertiesStartingWith(java.util.Properties source, java.lang.String prefix) Returns a new properties object with all properties that start with the given prefix copied from the specified source properties object.
java.util.Properties	propertiesStartingWith(java.util.Properties source, java.lang.String prefix, boolean cutPrefix) Returns a new properties object with all properties that start with the given prefix copied from the specified source properties object.
java.lang.Object[]	removeNull(java.lang.Object[] array) Removes all null values from the given array.
void	reverse(java.lang.Object[] array) Puts all elements in the specified array into reverse order.
java.lang.Object[]	reverseCopy(java.lang.Object[] array) Returns a new array that contains all elements of the given array in reverse order.
java.lang.Object[]	toArray(java.util.Collection objects) Returns an which has elements of the type of the first element in the given collection.
java.lang.Object[]	toArray(java.util.Collection objects, java.lang.Class elementType) Returns an array which has elements of the specified element type.
java.util.List	toList(java.lang.Object[] objects) Returns an ArrayList that contains all objects from the given array.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

EMPTY_SET

public static final java.util.Set EMPTY_SET

A constant that contains an immutable empty Set. Be aware that it is not possible to add objects to this set. The clone() method will NOT return a copy, but the empty Set itself!

EMPTY_LIST

public static final java.util.List EMPTY_LIST

A constant that contains an immutable empty List. Be aware that it is not possible to add objects to this list. The clone() method will NOT return a copy, but the empty List itself!

EMPTY_MAP

public static final java.util.Map EMPTY_MAP

A constant that contains an immutable empty Map. Be aware that it is not possible to add objects to this map. The clone() method will NOT return a copy, but the empty Map itself!

Method Detail

current

public static CollectionUtil current()

Returns the one and only instance of this class.

propertiesStartingWith

public java.util.Properties propertiesStartingWith(java.util.Properties source,
                                                   java.lang.String prefix)

Returns a new properties object with all properties that start with the given prefix copied from the specified source properties object. The keys of the copied properties are cut off the prefix in the return object. If source is null the method returns an empty Properties object.

Parameters:

source - The properties to copy from

prefix - The prefix all properties to copy have in common

propertiesStartingWith

public java.util.Properties propertiesStartingWith(java.util.Properties source,
                                                   java.lang.String prefix,
                                                   boolean cutPrefix)

Returns a new properties object with all properties that start with the given prefix copied from the specified source properties object. The cutPrefix specifies whether or not the keys of the copied properties must be cut off the prefix in the destination object. If any of the input parameters is null the method returns an empty Properties object.

Parameters:

source - The properties to copy from

prefix - The prefix all properties to copy have in common

cutPrefix - If true, the prefix gets cut off the keys in the destination object

copyPropertiesStartingWith

public void copyPropertiesStartingWith(java.util.Properties source,
                                       java.util.Properties destination,
                                       java.lang.String prefix,
                                       boolean cutPrefix)

Copies all properties that start with the given prefix from the specified source properties object to the destination properties. The cutPrefix specifies whether or not the keys of the copied properties must be cut off the prefix in the destination object.

Parameters:

source - The properties to copy from (if null nothing happens at all)

destination - The destination object where the properties are copied to (if null nothing happens at all)

prefix - The prefix all properties to copy have in common (if null nothing happens at all)

cutPrefix - If true, the prefix gets cut off the keys in the destination object

copy

public java.lang.Object[] copy(java.lang.Object[] objects)

Returns a copy of the given object array.

copy

public java.lang.Object[] copy(java.lang.Object[] objects,
                               IObjectFilter filter)

Returns a copy of the given object array which contains only those objects that match the given filter. If the given array is null, the result is null too. If the given filter is null, the result is an empty array

copy

public java.util.Collection copy(java.util.Collection objects,
                                 IObjectFilter filter)

Returns a copy of the given collection which contains only those objects that match the given filter. If the given collection is null, the result is null too. If the given filter is null, the result is an empty collection. If the result collection cannot be instantiated (e.g. due to missing public no-argument constructor) a RuntimeException will be thrown.

copy

public java.util.Map copy(java.util.Map map,
                          IObjectFilter filter)

Returns a copy of the given map which contains only those objects that match the given filter. If the given map is null, the result is null too. If the given filter is null, the result is an empty collection. The class of the given map must have a public non-argument constructor. The specified filter must be able to handle Map.Entry objects. If the result map cannot be instantiated (e.g. due to missing public no-argument constructor) a RuntimeException will be thrown.

reverseCopy

public java.lang.Object[] reverseCopy(java.lang.Object[] array)

Returns a new array that contains all elements of the given array in reverse order.

reverse

public void reverse(java.lang.Object[] array)

Puts all elements in the specified array into reverse order.

addAll

public void addAll(java.util.Collection collection,
                   java.lang.Object[] objects)

Adds all given objects to the specified collection. All null values in the objects array will be skipped.

Parameters:

collection - The collection to which the objects are added

objects - The objects to add to the collection

addAllNew

public void addAllNew(java.util.Collection collection,
                      java.lang.Object[] objects)

Adds all given objects to the specified collection, if they are not already in the collection. All null values in the objects array will be skipped.

Parameters:

collection - The collection to which the objects are added

objects - The objects to add to the collection

indexOfIdentical

public int indexOfIdentical(java.lang.Object[] objArray,
                            java.lang.Object searchObj)

Returns the index of the search object in the given object array. The search object is compared to the array elements by identity check (i.e. == ). The index of the first occurance is returned!
If the object was not found the method returns -1.

Parameters:

objArray - The array to search in

searchObj - The object to search for (might be null)

Returns:

The index of the first occurance or -1 if not found

indexOf

public int indexOf(java.lang.Object[] objArray,
                   java.lang.Object searchObj)

Returns the index of the search object in the given object array. The search object is compared to the array elements by equality check (i.e. equals() ). The index of the first occurance is returned!
If the object was not found the method returns -1.

Parameters:

objArray - The array to search in

searchObj - The object to search for (might be null)

Returns:

The index of the first occurance or -1 if not found

indexOf

public int indexOf(java.lang.Object[] objArray,
                   IObjectFilter filter)

Returns the index of the first object in the given object array that matches the given filter.
If no matching object was not found the method returns -1.

Parameters:

objArray - The array to search in

filter - The filter to determine the object to look for (must not be null)

Returns:

The index of the first occurance or -1 if not found

lastIndexOf

public int lastIndexOf(java.lang.Object[] objArray,
                       IObjectFilter filter)

Returns the index of the last object in the given object array that matches the given filter.
If no matching object was not found the method returns -1.

Parameters:

objArray - The array to search in

filter - The filter to determine the object to look for (must not be null)

Returns:

The index of the last occurance or -1 if not found

indexOf

public int indexOf(java.util.List list,
                   IObjectFilter filter)

Returns the index of the first object in the given list that matches the given filter.
If no matching object was not found the method returns -1.

Parameters:

list - The list to search in

filter - The filter to determine the object to look for (must not be null)

Returns:

The index of the first occurance or -1 if not found

lastIndexOf

public int lastIndexOf(java.util.List list,
                       IObjectFilter filter)

Returns the index of the last object in the given list that matches the given filter.
If no matching object was not found the method returns -1.

Parameters:

list - The list to search in

filter - The filter to determine the object to look for (must not be null)

Returns:

The index of the last occurance or -1 if not found

containsIdentical

public boolean containsIdentical(java.lang.Object[] objArray,
                                 java.lang.Object searchObj)

Returns true if the search object exists in the given object array. The search object is compared to the array elements by identity check (i.e. == ).

Parameters:

objArray - The array to search in

searchObj - The object to search for (might be null)

contains

public boolean contains(java.lang.Object[] objArray,
                        java.lang.Object searchObj)

Returns true if the search object exists in the given object array. The search object is compared to the array elements by equality check (i.e. equals() ).

Parameters:

objArray - The array to search in

searchObj - The object to search for (might be null)

contains

public boolean contains(int[] valueArray,
                        int value)

Returns true only if the given value is found in the given array. This works also for unsorted arrays. If you have a sorted array it is better to user Arrays.binarySearch() bevause it is faster.

Parameters:

valueArray - The array in which to look for the value

value - The value to look for

contains

public boolean contains(long[] valueArray,
                        long value)

Returns true only if the given value is found in the given array. This works also for unsorted arrays. If you have a sorted array it is better to user Arrays.binarySearch() bevause it is faster.

Parameters:

valueArray - The array in which to look for the value

value - The value to look for

copyWithoutIdentical

public java.lang.Object[] copyWithoutIdentical(java.lang.Object[] objArray,
                                               java.lang.Object[] skipArray)

Returns a copy of the first array that contains only elements that are not in the second array.
Objects are compared by identity (i.e. == ). The return array is of the same type as the input array.

Parameters:

objArray - The array to take the elements from

skipArray - The array that contains all objects that must not be in the result array

copyWithout

public java.lang.Object[] copyWithout(java.lang.Object[] objArray,
                                      java.lang.Object[] skipArray)

Returns a copy of the first array that contains only elements that are not in the second array.
Objects are compared by equality (i.e. equals() ). The return array is of the same type as the input array.

Parameters:

objArray - The array to take the elements from

skipArray - The array that contains all objects that must not be in the result array

copyWithout

public java.lang.Object[] copyWithout(java.lang.Object[] objArray,
                                      IObjectFilter filter)

Returns a copy of the specified array that contains only those elements that do NOT match the given filter.
The return array is of the same type as the input array. If the given filter is null a complete copy of the given array is returned. If the given array is null then null is returned ;

Parameters:

objArray - The array to take the elements from

filter - A filter that defines all elements must not be copied into the result array

copyWithout

public java.util.Collection copyWithout(java.util.Collection objects,
                                        IObjectFilter filter)

Returns a copy of the specified collection that contains only those elements that do NOT match the given filter.
The return collection is of the same type as the input collection. If the given filter is null a complete copy of the given collection is returned. If the given collection is null then null is returned ;

Parameters:

objects - The collection to take the elements from

filter - A filter that defines all elements must not be copied into the result collection

copyWithout

public java.util.Map copyWithout(java.util.Map map,
                                 IObjectFilter filter)

Returns a copy of the specified map that contains only those elements that do NOT match the given filter.
The return map is of the same type as the input map. If the given filter is null then a complete copy of the given map is returned. If the given map is null then null is returned. The class of the input map must have a public non-argument constructor, otherwise a runtime exception will be thrown. The given filter must handle Map.Entry objects.

Parameters:

map - The map to take the elements from

filter - A filter that defines all elements must not be copied into the result map

iterator

public java.util.Iterator iterator(java.lang.Object[] objects)

Returns an iterator on the given array.

Parameters:

objects - The objects to provide an interator for

removeNull

public java.lang.Object[] removeNull(java.lang.Object[] array)

Removes all null values from the given array. Returns a new array that contains all none null values of the input array.

Parameters:

array - The array to be cleared of null values

toArray

public java.lang.Object[] toArray(java.util.Collection objects,
                                  java.lang.Class elementType)

Returns an array which has elements of the specified element type. If the collection or the element type is null then this method returns null.
This method is better than java.util.Collection.toArray() because it returns an array of the desired type (elementType[]) rather than Object[]. It also just creates one new array instance with the correct size.

Parameters:

objects - The object to be put into the result array

elementType - The type of the array elements

Throws:

java.lang.ArrayStoreException - if any element in the collection is not of the same type as the element type

toArray

public java.lang.Object[] toArray(java.util.Collection objects)

Returns an which has elements of the type of the first element in the given collection. If the collection is null or empty then this method returns null. So it is safe to do a type cast to the expected array type.
Example: Integer[] integers = (Integer[])util.toArray( intColl ) ; )

Throws:

java.lang.ArrayStoreException - if any element in the collection is not of the same type as the first element

toList

public java.util.List toList(java.lang.Object[] objects)

Returns an ArrayList that contains all objects from the given array. Null values will be skipped. If the given array is null, then null is returned.

isNullOrEmpty

public boolean isNullOrEmpty(java.util.Collection collection)

Returns true if the given collection is null or has no elements.

Parameters:

collection - The collection to check

isNullOrEmpty

public boolean isNullOrEmpty(java.lang.Object[] array)

Returns true if the given array is null or has no elements.

Parameters:

array - The array to check

isNullOrEmpty

public boolean isNullOrEmpty(java.util.Map map)

Returns true if the given map is null or has no elements.

Parameters:

map - The map to check

isNullOrEmpty

public boolean isNullOrEmpty(AssociationList associationList)

Returns true if the given association list is null or has no elements.

Parameters:

associationList - The association list to check

asIterator

public java.util.Iterator asIterator(java.util.Enumeration enumeration)

Returns an iterator based on the given enumeration or null if the input parameter is null, too.

asList

public java.util.List asList(java.util.Enumeration enumeration)

Returns a list containing all elements of the given enumeration. If enumeration is null an empty list will be returned. Null elements in the enumeration will be skipped.