OptionalTransformingCollection (LibFX 0.3.0 API)

java.lang.Object
- org.codefx.libfx.collection.transform.OptionalTransformingCollection<E>

Type Parameters:

E - the type of elements contained in the Optionals

All Implemented Interfaces:

Iterable<E>, Collection<E>
```
public final class OptionalTransformingCollection<E>
extends Object
```
A transforming Collection which is a flattened view on a collection of Optionals, i.e. it only presents the contained values.
See the package documentation for general comments on transformation.
The inner collection must not contain null elements. The empty Optional is mapped to an outer element specified during construction. If null is chosen for this, this collection will accept null elements. Otherwise it will reject them with a NullPointerException.
The transformations used by this collection preserve object identity of outer elements with the exception of the default element. This means if (non-default) elements are added to this collection, an iteration over it will return the same instances. The default value instance will be used to represent the empty Optionals, 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 collection. This implies that all guarantees made by such methods (e.g. regarding atomicity) are upheld by the transformation.

Constructor Summary

Constructors
Constructor and Description
`OptionalTransformingCollection(Collection<Optional<E>> innerCollection)` Creates a new transforming collection.
`OptionalTransformingCollection(Collection<Optional<E>> innerCollection, Class<? super E> outerTypeToken)` Creates a new transforming collection which uses a type token to identify the outer elements.
`OptionalTransformingCollection(Collection<Optional<E>> innerCollection, Class<? super E> outerTypeToken, E outerDefaultElement)` Creates a new transforming collection which uses a type token to identify the outer elements.
`OptionalTransformingCollection(Collection<Optional<E>> innerCollection, E outerDefaultElement)` Creates a new transforming collection which uses the type of the specified default element as a token to identify the outer elements.

Method Summary

All Methods Instance Methods Concrete Methods
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<Optional<E>>`	`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 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.Collection
parallelStream, stream

Methods inherited from interface java.lang.Iterable
forEach

- Constructor Detail
  - OptionalTransformingCollection
```
public OptionalTransformingCollection(Collection<Optional<E>> innerCollection,
                                      Class<? super E> outerTypeToken,
                                      E outerDefaultElement)
```
    Creates a new transforming collection which uses a type token to identify the outer elements.
    
    Parameters:
    
    innerCollection - the wrapped collection
    
    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
  - OptionalTransformingCollection
```
public OptionalTransformingCollection(Collection<Optional<E>> innerCollection)
```
    Creates a new transforming collection.
    
    Parameters:
    
    innerCollection - the wrapped collection
  - OptionalTransformingCollection
```
public OptionalTransformingCollection(Collection<Optional<E>> innerCollection,
                                      Class<? super E> outerTypeToken)
```
    Creates a new transforming collection which uses a type token to identify the outer elements.
    
    Parameters:
    
    innerCollection - the wrapped collection
    
    outerTypeToken - the token for the outer type
  - OptionalTransformingCollection
```
public OptionalTransformingCollection(Collection<Optional<E>> innerCollection,
                                      E outerDefaultElement)
```
    Creates a new transforming collection which uses the type of the specified default element as a token to identify the outer elements.
    
    Parameters:
    
    innerCollection - the wrapped collection
    
    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
  - getInnerCollection
```
protected Collection<Optional<E>> 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 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
  - equals
```
public boolean equals(Object object)
```
    Specified by:
    
    equals in interface Collection<E>
  - hashCode
```
public int hashCode()
```
    Specified by:
    
    hashCode in interface Collection<E>
  - 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

This documentation is licensed under CC-BY 4.0, attributed to Nicolai Parlog from CodeFX.

Class OptionalTransformingCollection<E>

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.util.Collection

Methods inherited from interface java.lang.Iterable

Constructor Detail

OptionalTransformingCollection

OptionalTransformingCollection

OptionalTransformingCollection

OptionalTransformingCollection

Method Detail

getInnerCollection

isInnerElement

transformToOuter

isOuterElement

transformToInner

equals

hashCode

isThisCollection

size

isEmpty

contains

containsAll

callContainsAllOnInner

callContainsOnThis

add

addAll

callAddAllOnInner

callAddOnThis

remove

removeIf

removeAll

clearToRemoveAll

callRemoveAllOnInner

callRemoveOnThis

retainAll

callRetainAllOnInner

retainByCallingRemoveOnThis

clear

iterator

spliterator

toArray

toArray

toString