org.codefx.libfx.collection.transform

Class TransformingCollection<I,O>

java.lang.Object

org.codefx.libfx.collection.transform.TransformingCollection<I,O>

Type Parameters:

I - the inner type, i.e. the type of the elements contained in the wrapped/inner collection

O - the outer type, i.e. the type of elements appearing to be in this collection

All Implemented Interfaces:

Iterable<O>, Collection<O>

public final class TransformingCollection<I,O>
extends Object

A Collection which decorates another collection and transforms the element type from the inner type I to an outer type O.

See the package documentation for general comments on transformation.

This implementation mitigates the type safety problems by using a token of the inner and the outer type to check instances against them. This solves some of the critical situations but not all of them. In those other cases ClassCastExceptions might occur when an element can not be transformed by the transformation functions.

Null elements are allowed unless the inner collection does not accept them. These are handled explicitly and fixed to the transformation null -> null. The transforming functions specified during construction neither have to handle that case nor are they allowed to produce null elements.

If the stream returned by this collection is told to sort itself, it will do so on the base of the comparator returned by the inner collection's spliterator (e.g. based on the natural order of I if it has one).

TransformingCollections are created with a TransformingCollectionBuilder.

Method Summary

Modifier and Type	Method and Description
boolean	add(O element)
boolean	addAll(Collection<? extends O> otherCollection)
protected boolean	callAddAllOnInner(Collection<? extends O> otherCollection) Wraps the specified collection into a transformation and calls addAll on the innerCollection.
protected boolean	callAddOnThis(Collection<? extends O> otherCollection) Iterates over the specified collection and calls add(O) (on this collection) for each element.
protected boolean	callContainsAllOnInner(Collection<?> otherCollection) Wraps the specified collection into a transformation and calls containsAll on the innerCollection.
protected boolean	callContainsOnThis(Collection<?> otherCollection) Iterates over the specified collection and calls contains(Object) (on this collection) for each element.
protected boolean	callRemoveAllOnInner(Collection<?> otherCollection) Wraps the specified collection into a transformation and calls removeAll on the innerCollection.
protected boolean	callRemoveOnThis(Collection<?> otherCollection) Iterates over the specified collection and calls remove(Object) (on this collection) for each element.
protected boolean	callRetainAllOnInner(Collection<?> otherCollection) Wraps the specified collection into a transformation and calls retainAll on the innerCollection.
void	clear()
protected boolean	clearToRemoveAll() Calls clear() to remove all instances from the innerCollection.
boolean	contains(Object object)
boolean	containsAll(Collection<?> otherCollection)
boolean	equals(Object object)
protected Collection<I>	getInnerCollection()
int	hashCode()
boolean	isEmpty()
protected boolean	isInnerElement(Object object) Checks whether the specified object might be an inner element.
protected boolean	isOuterElement(Object object) Checks whether the specified object might be an outer element.
protected boolean	isThisCollection(Collection<?> otherCollection) Indicates whether the specified collection is equivalent to this one.
Iterator<O>	iterator()
boolean	remove(Object object)
boolean	removeAll(Collection<?> otherCollection)
boolean	removeIf(Predicate<? super O> filter)
boolean	retainAll(Collection<?> otherCollection)
protected boolean	retainByCallingRemoveOnThis(Collection<?> otherCollection) Iterates over this collection (i.e.
int	size()
Spliterator<O>	spliterator()
Object[]	toArray()
<T> T[]	toArray(T[] inputArray)
String	toString()
protected I	transformToInner(O outerElement) Transforms the specified element to an instance of the inner type.
protected O	transformToOuter(I innerElement) Transforms the specified element to an instance of the outer type.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Collection

parallelStream, stream

Methods inherited from interface java.lang.Iterable

forEach

Method Detail

getInnerCollection

protected Collection<I> getInnerCollection()

Returns:

the inner collection wrapped by this transforming collection

isInnerElement

protected boolean isInnerElement(Object object)

Checks whether the specified object might be an inner element.

This method does not have to be exact (which might be impossible due to involved generic types) and might produce false positives (but no false negatives).

Parameters:

object - the object to check; may be null

Returns:

true if the object might be an inner element

transformToOuter

protected O transformToOuter(I innerElement)

Transforms the specified element to an instance of the outer type.

It can not be guaranteed that the specified element is really of the inner type. If not, an exception can be thrown.

Parameters:

innerElement - the element to transform; may be null

Returns:

the transformed element

isOuterElement

protected boolean isOuterElement(Object object)

Checks whether the specified object might be an outer element.

This method does not have to be exact (which might be impossible due to involved generic types) and might produce false positives (but no false negatives).

Parameters:

object - the object to check; may be null

Returns:

true if the object might be an outer element

transformToInner

protected I transformToInner(O outerElement)

Transforms the specified element to an instance of the inner type.

It can not be guaranteed that the specified element is really of the outer type. If not, an exception can be thrown.

Parameters:

outerElement - the element to transform; may be null

Returns:

the transformed element

equals

public boolean equals(Object object)

Specified by:

equals in interface Collection<O>

hashCode

public int hashCode()

Specified by:

hashCode in interface Collection<O>

isThisCollection

protected final boolean isThisCollection(Collection<?> otherCollection)

Indicates whether the specified collection is equivalent to this one. This is the case if it is also an AbstractTransformingCollection and wraps the same innerCollection.

Parameters:

otherCollection - the Collection which is compared with this one

Returns:

true if this and the specified collection are equivalent

size

public int size()

Specified by:

size in interface Collection<O>

isEmpty

public boolean isEmpty()

Specified by:

isEmpty in interface Collection<O>

contains

public boolean contains(Object object)

Specified by:

contains in interface Collection<O>

containsAll

public boolean containsAll(Collection<?> otherCollection)

Specified by:

containsAll in interface Collection<O>

callContainsAllOnInner

protected final boolean callContainsAllOnInner(Collection<?> otherCollection)

Wraps the specified collection into a transformation and calls containsAll on the innerCollection.

Subclasses may chose to use this method if they override containsAll(Collection).

Accessing the wrapped collection will lead to ClassCastExceptions when its elements are not of this collection's outer type O. Consider using callContainsOnThis(Collection).

Parameters:

otherCollection - the parameter to containsAll

Returns:

result of the call to containsAll

callContainsOnThis

protected final boolean callContainsOnThis(Collection<?> otherCollection)

Iterates over the specified collection and calls contains(Object) (on this collection) for each element.

Subclasses may chose to use this method if they override containsAll(Collection).

Manually iterating over the specified collection and calling this.contains(Object) individually might break guarantees or optimizations made by the inner collection. Consider using callContainsAllOnInner(Collection).

Parameters:

otherCollection - the collection whose elements are passed to contains

Returns:

false if at least one call to contains returns false; otherwise true

add

public boolean add(O element)

Specified by:

add in interface Collection<O>

addAll

public boolean addAll(Collection<? extends O> otherCollection)

Specified by:

addAll in interface Collection<O>

callAddAllOnInner

protected final boolean callAddAllOnInner(Collection<? extends O> otherCollection)

Wraps the specified collection into a transformation and calls addAll on the innerCollection.

Subclasses may chose to use this method if they override addAll(Collection).

Accessing the wrapped collection will lead to ClassCastExceptions when its elements are not of this collection's outer type O. Consider using callAddOnThis(Collection).

Parameters:

otherCollection - the parameter to addAll

Returns:

result of the call to addAll

callAddOnThis

protected final boolean callAddOnThis(Collection<? extends O> otherCollection)

Iterates over the specified collection and calls add(O) (on this collection) for each element.

Subclasses may chose to use this method if they override addAll(Collection).

Manually iterating over the specified collection and calling this.add(Object) individually might break guarantees (e.g. regarding atomicity) or optimizations made by the inner collection. Consider using callAddAllOnInner(Collection).

Parameters:

otherCollection - the collection whose elements are passed to add

Returns:

true if at least one call to add returns true; otherwise false

remove

public boolean remove(Object object)

Specified by:

remove in interface Collection<O>

removeIf

public boolean removeIf(Predicate<? super O> filter)

Specified by:

removeIf in interface Collection<O>

removeAll

public boolean removeAll(Collection<?> otherCollection)

Specified by:

removeAll in interface Collection<O>

clearToRemoveAll

protected final boolean clearToRemoveAll()

Calls clear() to remove all instances from the innerCollection.

Returns:

true if the call changed the innerCollection

callRemoveAllOnInner

protected final boolean callRemoveAllOnInner(Collection<?> otherCollection)

Wraps the specified collection into a transformation and calls removeAll on the innerCollection.

Subclasses may chose to use this method if they override removeAll(Collection).

Accessing the wrapped collection will lead to ClassCastExceptions when its elements are not of this collection's outer type O. Consider using callRemoveOnThis(Collection).

Parameters:

otherCollection - the parameter to removeAll

Returns:

result of the call to removeAll

callRemoveOnThis

protected final boolean callRemoveOnThis(Collection<?> otherCollection)

Iterates over the specified collection and calls remove(Object) (on this collection) for each element.

Subclasses may chose to use this method if they override removeAll(Collection).

Manually iterating over the specified collection and calling this.remove(Object) individually might break guarantees (e.g. regarding atomicity) or optimizations made by the inner collection. Consider using callRemoveAllOnInner(Collection).

Parameters:

otherCollection - the collection whose elements are passed to remove

Returns:

true if at least one call to remove returns true; otherwise false

retainAll

public boolean retainAll(Collection<?> otherCollection)

Specified by:

retainAll in interface Collection<O>

callRetainAllOnInner

protected final boolean callRetainAllOnInner(Collection<?> otherCollection)

Wraps the specified collection into a transformation and calls retainAll on the innerCollection.

Subclasses may choose to use this method if they override retainAll(Collection).

Accessing the wrapped collection will lead to ClassCastExceptions when its elements are not of this collection's outer type O. Consider using retainByCallingRemoveOnThis(Collection).

Parameters:

otherCollection - the parameter to retainAll

Returns:

result of the call to retainAll

retainByCallingRemoveOnThis

protected final boolean retainByCallingRemoveOnThis(Collection<?> otherCollection)

Iterates over this collection (i.e. over the outer elements) and removes each element which is not contained in the specified collection.

Subclasses may choose to use this method if they override retainAll(Collection).

Manually iterating over this collection and calling this.remove(Object) individually might break guarantees (e.g. regarding atomicity) or optimizations made by the inner collection. Consider using callRetainAllOnInner(Collection).

Parameters:

otherCollection - the collection whose elements are not removed from this collection

Returns:

true if at least one element was removed; otherwise false

clear

public void clear()

Specified by:

clear in interface Collection<O>

iterator

public Iterator<O> iterator()

Specified by:

iterator in interface Iterable<O>

Specified by:

iterator in interface Collection<O>

spliterator

public Spliterator<O> spliterator()

Specified by:

spliterator in interface Iterable<O>

Specified by:

spliterator in interface Collection<O>

toArray

public Object[] toArray()

Specified by:

toArray in interface Collection<O>

toArray

public <T> T[] toArray(T[] inputArray)

Specified by:

toArray in interface Collection<O>

toString

public String toString()

Overrides:

toString in class Object