net.sf.mmm.util.reflect.api

Interface CollectionReflectionUtil

All Known Implementing Classes:

CollectionReflectionUtilImpl

public interface CollectionReflectionUtil

This is the interface for a collection of utility functions to deal with Collections reflectively.

Since:

1.0.2

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

See Also:

ReflectionUtil, CollectionReflectionUtilImpl, GenericType.getComponentType()

Method Summary

Modifier and Type	Method and Description
Object	add(Object arrayOrCollection, Object item) This method adds the given item to the given arrayOrCollection.
Object	get(Object arrayOrList, int index) This method gets the item at the given index from arrayOrCollection.
Object	get(Object arrayOrList, int index, boolean ignoreIndexOverflow) This method gets the item at the given index from arrayOrCollection.
int	getSize(Object arrayMapOrCollection) This method gets the size of the given arrayMapOrCollection.
boolean	isArrayOrList(Object object) This method determines if the given object is an array or List.
Object	remove(Object arrayOrCollection, Object item) This method removes the given item from the given arrayOrCollection.
Object	set(Object arrayOrList, int index, Object item) This method sets the given item at the given index in arrayOrCollection.
Object	set(Object arrayOrList, int index, Object item, GenericBean<Object> arrayReceiver) This method sets the given item at the given index in arrayOrCollection.
Object	set(Object arrayOrList, int index, Object item, GenericBean<Object> arrayReceiver, int maximumGrowth) This method sets the given item at the given index in arrayOrCollection.
Object	toArray(Collection<?> collection, Class<?> componentType) This method converts the given Collection to an array of the given componentType.
<T> T[]	toArrayTyped(Collection<T> collection, Class<T> componentType) This method converts the given Collection to an array of the given componentType.

Method Detail

isArrayOrList

boolean isArrayOrList(Object object)

This method determines if the given object is an array or List.

Parameters:

object - is the object to check.

Returns:

true if the given object is an array or List, false otherwise.

getSize

int getSize(Object arrayMapOrCollection)
     throws IllegalArgumentException

This method gets the size of the given arrayMapOrCollection. If arrayMapOrCollection is an array, then its length is returned. If it is a Map or Collection, its size is returned.

Parameters:

arrayMapOrCollection - the array, Map or Collection.

Returns:

the length or size of arrayMapOrCollection.

Throws:

IllegalArgumentException - if the given arrayMapOrCollection is invalid ( null or neither array nor Map or Collection).

get

Object get(Object arrayOrList,
           int index)
    throws IllegalArgumentException

This method gets the item at the given index from arrayOrCollection.
It sets ignoreIndexOverflow to true.

Parameters:

arrayOrList - is the array or List.

index - is the position of the requested item.

Returns:

the item at the given index. May be null if the item itself is null or the index is greater than the size or arrayOrCollection.

Throws:

IllegalArgumentException - if the given arrayOrList is invalid (null or neither array nor List).

See Also:

get(Object, int, boolean)

get

Object get(Object arrayOrList,
           int index,
           boolean ignoreIndexOverflow)
    throws IllegalArgumentException

This method gets the item at the given index from arrayOrCollection.

Parameters:

arrayOrList - is the array or List.

index - is the position of the requested item.

ignoreIndexOverflow - - if false an the given index is greater or equal to the size of arrayOrCollection an IndexOutOfBoundsException will be thrown. Else if true, null is returned in this case.

Returns:

the item at the given index. May be null if the item itself is null or the index is greater or equal to the size of arrayOrCollection.

Throws:

IllegalArgumentException - if the given arrayOrList is invalid (null or neither array nor List).

See Also:

List.get(int)

set

Object set(Object arrayOrList,
           int index,
           Object item)
    throws IllegalArgumentException

This method sets the given item at the given index in arrayOrCollection. It uses a default value for maximumGrowth and no arrayReceiver ( null).

Parameters:

arrayOrList - is the array or List.

index - is the position where to set the item.

item - is the item to set.

Returns:

the item at position index in arrayOrList that has been replaced by item. This can be null. Additional if the arrayOrList has been increased, null is returned.

Throws:

IllegalArgumentException - if the given arrayOrList is invalid (null or neither array nor List).

See Also:

set(Object, int, Object, GenericBean, int)

set

Object set(Object arrayOrList,
           int index,
           Object item,
           GenericBean<Object> arrayReceiver)
    throws IllegalArgumentException

This method sets the given item at the given index in arrayOrCollection. If a List is given that has a size less or equal to the given index, the size of the List will be increased to index + 1 by adding null values so the item can be set. It uses a default value for maximumGrowth.

Parameters:

arrayOrList - is the array or List.

index - is the position where to set the item.

item - is the item to set.

arrayReceiver - is a GenericBean that allows to receive an array-copy of arrayOrList with an increased length. It can be null to disable array-copying.

Returns:

the item at position index in arrayOrList that has been replaced by item. This can be null. Additional if the arrayOrList has been increased, null is returned.

Throws:

IllegalArgumentException - if the given arrayOrList is invalid (null or neither array nor List).

See Also:

List.set(int, Object), set(Object, int, Object, GenericBean, int)

set

Object set(Object arrayOrList,
           int index,
           Object item,
           GenericBean<Object> arrayReceiver,
           int maximumGrowth)
    throws IllegalArgumentException

This method sets the given item at the given index in arrayOrCollection. If a List is given that has a size less or equal to the given index, the size of the List will be increased to index + 1 by adding null values so the item can be set. However the number of adds is limited to maximumGrowth.

Parameters:

arrayOrList - is the array or List.

index - is the position where to set the item.

item - is the item to set.

maximumGrowth - is the maximum number by which the size of arrayOrList will be increased (with null values) to reach index + 1 so the item can be set. Set this value to 0 to turn off this feature (and leave the size untouched). Please always specify a real maximum (<=65536) and do NOT use Integer.MAX_VALUE since this might cause memory holes if something goes wrong. If arrayOrList is an array, increasing can only happen by creating a new array. To receive such new array, you need to supply an arrayReceiver. Otherwise (if null) this method behaves for arrays as if maximumGrowth was 0. If an array should be increased, a new array with the size of index + 1 is created. The original items are copied, the given item is set on the copy instead while the original array remains unchanged. Then the new array is set to the arrayReceiver.

arrayReceiver - is a GenericBean that allows to receive an array-copy of arrayOrList with an increased length. It can be null to disable array-copying.

Returns:

the item at position index in arrayOrList that has been replaced by item. This can be null. Additional if the arrayOrList has been increased, null is returned.

Throws:

IllegalArgumentException - if the given arrayOrList is invalid (null or neither array nor List).

See Also:

List.set(int, Object)

add

Object add(Object arrayOrCollection,
           Object item)

This method adds the given item to the given arrayOrCollection.

Parameters:

arrayOrCollection - is the array or Collection.

item - is the item to add.

Returns:

the given arrayOrCollection if it was a Collection. Otherwise, in case of an array, a new array with a length increased by 1 and the elements of arrayOrCollection appended with the given item is returned.

remove

Object remove(Object arrayOrCollection,
              Object item)

This method removes the given item from the given arrayOrCollection.

Parameters:

arrayOrCollection - is the array or Collection.

item - is the item to remove.

Returns:

null if the given item was NOT contained in arrayOrCollection, the given arrayOrCollection if it was a Collection and the item has been removed. Otherwise, in case of an array, a new array with a length decreased by 1 and the elements of arrayOrCollection without the first occurrence of the given item is returned.

toArray

Object toArray(Collection<?> collection,
               Class<?> componentType)
        throws ClassCastException

This method converts the given Collection to an array of the given componentType. This method also allows to create primitive arrays. If NOT required please prefer using toArrayTyped(Collection, Class).

Parameters:

collection - is the Collection to convert to an array.

componentType - is the component type of the requested array. If this type is primitive, the according collection-values with be unboxed.

Returns:

the Array of the given componentType and with the values of the given Collection.

Throws:

ClassCastException - if the values of the Collection are NOT compatible with the given componentType.

toArrayTyped

<T> T[] toArrayTyped(Collection<T> collection,
                     Class<T> componentType)

This method converts the given Collection to an array of the given componentType.

Type Parameters:

T - is the generic type of the componentType.

Parameters:

collection - is the Collection to convert to an array.

componentType - is the component type of the requested array.

Returns:

the Array of the given componentType and with the values of the given Collection.