org.codefx.libfx.collection.transform

Class OptionalTransformingSet<E>

java.lang.Object

org.codefx.libfx.collection.transform.OptionalTransformingSet<E>

Type Parameters:

E - the type of elements contained in the Optionals

All Implemented Interfaces:

Iterable<E>, Collection<E>, Set<E>

public final class OptionalTransformingSet<E>
extends Object

A transforming Set which is a flattened view on a set of Optionals, i.e. it only presents the contained values.

See the package documentation for general comments on transformation.

The inner set must not contain null elements. The empty Optional is mapped to an outer element specified during construction. If null is chosen for this, this set will accept null elements. Otherwise it will reject them with a NullPointerException.

The transformations used by this set preserve object identity of outer elements with the exception of the default element. This means if (non-default) elements are added to this set, an iteration over it will return the same instances. The default value instance will be used to represent the empty Optional, so when elements equal to it are added, they will be retrieved as that instance (thus loosing their identity).

This implementation mitigates the type safety problems by using type tokens. Optional.class is used as the inner type token. The outer type token can be specified during construction. This solves some of the critical situations but not all of them. In those other cases (e.g. if containsAll is called with a Collection<Optional<?>>) ClassCastExceptions might occur.

All method calls (of abstract and default methods existing in JDK 8) are forwarded to the same method on the wrapped set. This implies that all guarantees made by such methods (e.g. regarding atomicity) are upheld by the transformation.

Constructor Summary

Constructors

Constructor and Description
OptionalTransformingSet(Set<Optional<E>> innerSet) Creates a new transforming set.
OptionalTransformingSet(Set<Optional<E>> innerSet, Class<? super E> outerTypeToken) Creates a new transforming set which uses a type token to identify the outer elements.
OptionalTransformingSet(Set<Optional<E>> innerSet, Class<? super E> outerTypeToken, E outerDefaultElement) Creates a new transforming set which uses a type token to identify the outer elements.
OptionalTransformingSet(Set<Optional<E>> innerSet, E outerDefaultElement) Creates a new transforming set which uses the type of the specified default element as a token to identify the outer elements.

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()
protected Set<Optional<E>>	getInnerSet()
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 Optional<E>	transformToInner(E outerElement) Transforms the specified element to an instance of the inner type.
protected E	transformToOuter(Optional<E> 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.Set

add, addAll, clear, contains, containsAll, isEmpty, iterator, remove, removeAll, retainAll, size, spliterator, toArray, toArray

Methods inherited from interface java.util.Collection

parallelStream, removeIf, stream

Methods inherited from interface java.lang.Iterable

forEach

Constructor Detail

OptionalTransformingSet

public OptionalTransformingSet(Set<Optional<E>> innerSet,
                               Class<? super E> outerTypeToken,
                               E outerDefaultElement)

Creates a new transforming set which uses a type token to identify the outer elements.

Parameters:

innerSet - the wrapped set

outerTypeToken - the token for the outer type

outerDefaultElement - the element used to represent Optional.empty(); can be null; it is of crucial importance that this element does not occur inside a non-empty optional because then the transformations from that optional to an element and back are not inverse, which will cause unexpected behavior

OptionalTransformingSet

public OptionalTransformingSet(Set<Optional<E>> innerSet)

Creates a new transforming set.

Parameters:

innerSet - the wrapped set

OptionalTransformingSet

public OptionalTransformingSet(Set<Optional<E>> innerSet,
                               Class<? super E> outerTypeToken)

Creates a new transforming set which uses a type token to identify the outer elements.

Parameters:

innerSet - the wrapped set

outerTypeToken - the token for the outer type

OptionalTransformingSet

public OptionalTransformingSet(Set<Optional<E>> innerSet,
                               E outerDefaultElement)

Creates a new transforming set which uses the type of the specified default element as a token to identify the outer elements.

Parameters:

innerSet - the wrapped set

outerDefaultElement - the non-null element used to represent Optional.empty(); it is of crucial importance that this element does not occur inside an optional because then the transformations from that optional to an element and back are not inverse, which will cause unexpected behavior; the instance's class will be used as the outer type token

Method Detail

getInnerSet

protected Set<Optional<E>> getInnerSet()

Returns:

the inner set wrapped by this transforming set

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 E transformToOuter(Optional<E> 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 Optional<E> transformToInner(E 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

getInnerCollection

protected final Collection<I> getInnerCollection()

Returns:

the inner collection wrapped by this transforming collection

equals

public final boolean equals(Object object)

Specified by:

equals in interface Collection<O>

Specified by:

equals in interface Set<O>

hashCode

public final int hashCode()

Specified by:

hashCode in interface Collection<O>

Specified by:

hashCode in interface Set<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