Package eu.simuline.util

Class CollectionsExt<E>

java.lang.Object

eu.simuline.util.CollectionsExt<E>

Type Parameters:

E - the class of the elements of collections under consideration.

public abstract class CollectionsExt<E>
extends Object

An add on of the core class Collections. This class provides various kinds of immutable collections, where immutability is configurable via a CollectionsExt.Modification object.

Also this class yields weak hash sets via weakHashSet(). Moreover, there are methods to convert arrays and lists in one another also recursively. Finally, there are methods getUnique(Collection) to retrieve the unique element and reverse(List) reverses a list.

Version:

1.0

Author:

Ernst Reissner

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	CollectionsExt.AbstractImmutableCollection<C extends Collection<E>,E>	A class of Collections of elements of class E extending C initially throwing an UnsupportedOperationException when trying to modify the collection either directly or via its iterator(s) or via a transparent view like List.subList(int, int).
(package private) static class	CollectionsExt.AbstractImmutableMultiSet<C extends MultiSet<E>,E>	A MultiSet which prevents being modified by throwing an exception for the modifying methods.
static class	CollectionsExt.ImmutableCollection<E>	A collection which prevents being modified by throwing an exception for the modifying methods.
static class	CollectionsExt.ImmutableCyclicList<E>	Represents an immutable cyclic list by throwing an exception when invoking a method which modifies this list.
static class	CollectionsExt.ImmutableList<E>	A list which prevents being modified by throwing an exception for the modifying methods.
private static class	CollectionsExt.ImmutableMultiplicity	An immutable implementation of the multiplicity interface.
(package private) static class	CollectionsExt.ImmutableMultiSet<E>	A multi-set which prevents being modified by throwing an exception for the modifying methods.
static class	CollectionsExt.ImmutableSet<E>	A set which prevents being modified by throwing an exception for the modifying methods.
(package private) static class	CollectionsExt.ImmutableSortedMultiSet<E>	A sorted multi-set which prevents being modified by throwing an exception for the modifying methods.
static class	CollectionsExt.ImmutableSortedSet<E>	A sorted set which prevents being modified by throwing an exception for the modifying methods.
static class	CollectionsExt.Modification	Enumerates the kinds of modifications on a Collection.
static class	CollectionsExt.NonModifyingCyclicIterator<E>	An interator which prevents modification on the underlying list, by throwing an exception for the modifying methods.

Constructor Summary

Constructors

Constructor	Description
CollectionsExt()

Method Summary

Modifier and Type	Method	Description
static <E> CollectionsExt.ImmutableCollection<E>	getImmutableCollection(Collection<E> coll)	Returns an unmodifiable view of the specified collection coll.
static <E> CyclicList<E>	getImmutableCyclicList(CyclicList<E> cyc)
static <E> CollectionsExt.ImmutableList<E>	getImmutableList(List<E> list)
static <E> MultiSet<E>	getImmutableMultiSet(MultiSet<E> mSet)
static <E> CollectionsExt.ImmutableSet<E>	getImmutableSet(Set<E> set)
static <E> MultiSet<E>	getImmutableSortedMultiSet(SortedMultiSet<E> mSet)
static <E> CollectionsExt.ImmutableSortedSet<E>	getImmutableSortedSet(SortedSet<E> set)
static <T> T	getUnique(Collection<? extends T> coll)	Returns the unique element of the collection coll.
static void	main(String[] args)
static Object	recToArray(Object source, Class<?> cls)	Converts source which is typically a List, recursively into an array with the given type.
static Object	recToArray(Object source, Class<?> cls, Caster caster)	Converts source which is typically a Collection, recursively into an array with the given type using the specified caster for the elementary objects in source.
static Object[]	recToArray(List<?> list)	Converts the list given recursively into an array.
static <T> List<T>	reverse(List<T> list)	Returns the reverse of the given list.
static <E> Set<E>	weakHashSet()	Retuns a weak hash set, i.e. a hash set of weak references.

Methods inherited from class java.lang.Object

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

Constructor Detail

CollectionsExt

public CollectionsExt()

Method Detail

getImmutableCollection

public static <E> CollectionsExt.ImmutableCollection<E> getImmutableCollection(Collection<E> coll)

Returns an unmodifiable view of the specified collection coll. This method allows modules to provide users with "read-only" access to internal collections. Query operations on the returned collection "read through" to the specified collection, and attempts to modify the returned collection, whether direct or via its iterator, result in an UnsupportedOperationException.

Parameters:

coll - an instance of a Collection.

Returns:

a Collection which equals coll, i.e. with the same elements returned by the iterator in the same ordering but is immutable. Note that the return type offers methods #allowModification(CollectionsExt.Modification), CollectionsExt.AbstractImmutableCollection.allowedModifications() and CollectionsExt.ImmutableCollection.unrestricted().

Throws:

NullPointerException - if coll==null.

getImmutableSet

public static <E> CollectionsExt.ImmutableSet<E> getImmutableSet(Set<E> set)

getImmutableSortedSet

public static <E> CollectionsExt.ImmutableSortedSet<E> getImmutableSortedSet(SortedSet<E> set)

getImmutableList

public static <E> CollectionsExt.ImmutableList<E> getImmutableList(List<E> list)

getImmutableCyclicList

public static <E> CyclicList<E> getImmutableCyclicList(CyclicList<E> cyc)

getImmutableMultiSet

public static <E> MultiSet<E> getImmutableMultiSet(MultiSet<E> mSet)

getImmutableSortedMultiSet

public static <E> MultiSet<E> getImmutableSortedMultiSet(SortedMultiSet<E> mSet)

weakHashSet

public static <E> Set<E> weakHashSet()

Retuns a weak hash set, i.e. a hash set of weak references.

See Also:

HashMap, Collections.newSetFromMap(Map)

recToArray

public static Object[] recToArray(List<?> list)

Converts the list given recursively into an array.

Parameters:

list - a List.

Returns:

an array array of objects satisfying array[i] == list.get(i) if list.get(i) is not a list; array[i] == recToArray(list.get(i)) otherwise. Note that array may be a nested array but that the dimension is always one.

See Also:

recToArray(Object, Class), ArraysExt.recAsList(Object[])

recToArray

public static Object recToArray(Object source,
                                Class<?> cls)

Converts source which is typically a List, recursively into an array with the given type.

Parameters:

source - an arbitrary Object, even an array but typically a List.

cls - Up to compatibility (see BasicTypesCompatibilityChecker.areCompatible(java.lang.Class<?>, java.lang.Object)), the type of the return value. Note that typically this is an array type such as Double[][][] or List[][][] or even int[][][] but this need not be the case.

Returns:

• if cls and source are compatible (see BasicTypesCompatibilityChecker.areCompatible(java.lang.Class<?>, java.lang.Object)), e.g. if source is an instance of cls or if source == null, the object source is returned.

  If cls is not an elementary type as e.g. Boolean.TYPE, and if source != null, compatibility means that source is an instance of the corresponding wrapper class.

• if cls and source are not compatible, cls must be an array type and source must be a list; otherwise an exception is thrown.

  In the former case, an array array of objects is returned satisfying array.length == ((List)source).size() and array[i] == recToArray(list.get(i), cls2) for all valid indices i is returned. The cls2 argument for the recursive invocation is the element type of cls.

  Note that although the return value is always an array, its type need not be a subtype of Object[] or of Object[][]. Consider for instance the case where source is a list of Integers and cls is int[]: This yields an

Throws:

IllegalArgumentException - if neither of the following is true:

• cls and source are compatible.
• cls is an array type and source is a List.

See Also:

ArraysExt.recAsList(Object, Class)

recToArray

public static Object recToArray(Object source,
                                Class<?> cls,
                                Caster caster)

Converts source which is typically a Collection, recursively into an array with the given type using the specified caster for the elementary objects in source.

Parameters:

source - an arbitrary Object, even an array but typically a Collection.

cls - Up to compatibility defined by caster, the type of the return value. Note that typically this is an array type such as Double[][][] or List[][][] or even int[][][] but this need not be the case. Note that the base type has to be compatible with the source objects with respect to the specified caster.

caster - performs the conversion of the top-level elements of the source.

Returns:

• if cls and source are compatible (see Caster.areCompatible(java.lang.Class<?>, java.lang.Object)), the cast of source is returned.

  Note that compatibility is up to wrapping of elementary types and unwrapping of their wrappers.

• if cls and source are not compatible, cls must be an array type and source must be a list; otherwise an exception is thrown.

  In the former case, an array array of objects is returned satisfying array.length == ((Collection)source).size() and array[i] == recToArray(list.get(i), ... , caster) for all valid indices i. The cls2 argument for the recursive invocation is the element type of cls.

  Note that although the return value is either the result of a casting process or an array, in the latter case its type need not be a subtype of Object[] or of Object[][]. Consider for instance the case where source is a list of Integers and cls is int[]:

Throws:

IllegalArgumentException - if neither of the following is true:

• cls and source are compatible with respect to caster.
• cls is an array type and source is a List.

See Also:

ArraysExt.recAsList(Object, Class, Caster)

getUnique

public static <T> T getUnique(Collection<? extends T> coll)

Returns the unique element of the collection coll.

Parameters:

coll - a collection of T's.

Returns:

the unique element of the collection coll.

Throws:

IllegalStateException - if coll does not contain a unique element.

reverse

public static <T> List<T> reverse(List<T> list)

Returns the reverse of the given list. In fact the list returned is an ArrayList.

main

public static void main(String[] args)