OptionalTransformingList (LibFX 0.3.0 API)

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

Type Parameters:

E - the type of elements contained in the Optionals

All Implemented Interfaces:

Iterable<E>, Collection<E>, List<E>
```
public final class OptionalTransformingList<E>
extends Object
```
A transforming List which is a flattened view on a list of Optionals, i.e. it only presents the contained values.
See the package documentation for general comments on transformation.
The inner list must not contain null elements. The empty Optional is mapped to an outer element specified during construction. If null is chosen for this, this list will accept null elements. Otherwise it will reject them with a NullPointerException.
The transformations used by this list preserve object identity of outer elements with the exception of the default element. This means if (non-default) elements are added to this list, 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
`OptionalTransformingList(List<Optional<E>> innerList)` Creates a new transforming list.
`OptionalTransformingList(List<Optional<E>> innerList, Class<? super E> outerTypeToken)` Creates a new transforming list which uses a type token to identify the outer elements.
`OptionalTransformingList(List<Optional<E>> innerList, Class<? super E> outerTypeToken, E outerDefaultElement)` Creates a new transforming list which uses a type token to identify the outer elements.
`OptionalTransformingList(List<Optional<E>> innerList, E outerDefaultElement)` Creates a new transforming list 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
`void`	`add(int index, O element)`
`boolean`	`add(O element)`
`boolean`	`addAll(Collection<? extends O> otherCollection)`
`boolean`	`addAll(int index, 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`	`callAddAllOnInner(int startIndex, Collection<? extends O> otherCollection)` Wraps the specified collection into a transformation and calls `addAll` on the `innerList`.
`protected boolean`	`callAddOnThis(Collection<? extends O> otherCollection)` Iterates over the specified collection and calls `add(O)` (on this collection) for each element.
`protected boolean`	`callAddOnThis(int startIndex, Collection<? extends O> otherCollection)` Iterates over the specified collection and calls `add()` (on this list) 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)`
`O`	`get(int index)`
`protected Collection<I>`	`getInnerCollection()`
`protected List<Optional<E>>`	`getInnerList()`
`int`	`hashCode()`
`int`	`indexOf(Object object)`
`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()`
`int`	`lastIndexOf(Object object)`
`ListIterator<O>`	`listIterator()`
`ListIterator<O>`	`listIterator(int startIndex)`
`O`	`remove(int index)`
`boolean`	`remove(Object object)`
`boolean`	`removeAll(Collection<?> otherCollection)`
`boolean`	`removeIf(Predicate<? super O> filter)`
`void`	`replaceAll(UnaryOperator<O> operator)`
`boolean`	`retainAll(Collection<?> otherCollection)`
`protected boolean`	`retainByCallingRemoveOnThis(Collection<?> otherCollection)` Iterates over this collection (i.e.
`O`	`set(int index, O element)`
`int`	`size()`
`void`	`sort(Comparator<? super O> comparator)`
`Spliterator<O>`	`spliterator()`
`List<O>`	`subList(int fromIndex, int toIndex)`
`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.List
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
  - OptionalTransformingList
```
public OptionalTransformingList(List<Optional<E>> innerList,
                                Class<? super E> outerTypeToken,
                                E outerDefaultElement)
```
    Creates a new transforming list which uses a type token to identify the outer elements.
    
    Parameters:
    
    innerList - the wrapped list
    
    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
  - OptionalTransformingList
```
public OptionalTransformingList(List<Optional<E>> innerList)
```
    Creates a new transforming list.
    
    Parameters:
    
    innerList - the wrapped list
  - OptionalTransformingList
```
public OptionalTransformingList(List<Optional<E>> innerList,
                                Class<? super E> outerTypeToken)
```
    Creates a new transforming list which uses a type token to identify the outer elements.
    
    Parameters:
    
    innerList - the wrapped set
    
    outerTypeToken - the token for the outer type
  - OptionalTransformingList
```
public OptionalTransformingList(List<Optional<E>> innerList,
                                E outerDefaultElement)
```
    Creates a new transforming list which uses the type of the specified default element as a token to identify the outer elements.
    
    Parameters:
    
    innerList - the wrapped list
    
    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
  - getInnerList
```
protected List<Optional<E>> getInnerList()
```
    Returns:
    
    the inner list wrapped by this transforming list
  - 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
  - get
```
public O get(int index)
```
    Specified by:
    
    get in interface List<O>
  - indexOf
```
public int indexOf(Object object)
```
    Specified by:
    
    indexOf in interface List<O>
  - lastIndexOf
```
public int lastIndexOf(Object object)
```
    Specified by:
    
    lastIndexOf in interface List<O>
  - add
```
public void add(int index,
                O element)
```
    Specified by:
    
    add in interface List<O>
  - addAll
```
public boolean addAll(int index,
                      Collection<? extends O> otherCollection)
```
    Specified by:
    
    addAll in interface List<O>
  - callAddAllOnInner
```
protected final boolean callAddAllOnInner(int startIndex,
                                          Collection<? extends O> otherCollection)
```
    Wraps the specified collection into a transformation and calls addAll on the innerList.
    Subclasses may choose to use this method if they override addAll(int, Collection).
    Accessing the wrapped collection will lead to ClassCastExceptions when its elements are not of this list's outer type O. Consider using callAddOnThis(int, Collection).
    
    Parameters:
    
    startIndex - index at which to insert the first element from the specified collection
    
    otherCollection - the parameter to addAll
    
    Returns:
    
    result of the call to addAll
  - callAddOnThis
```
protected final boolean callAddOnThis(int startIndex,
                                      Collection<? extends O> otherCollection)
```
    Iterates over the specified collection and calls add() (on this list) for each element.
    Subclasses may choose to use this method if they override addAll(int, Collection).
    Manually iterating over the specified collection and calling this.add(int, Object) individually might break guarantees (e.g. regarding atomicity) or optimizations made by the inner collection. Consider using callAddAllOnInner(int, Collection).
    
    Parameters:
    
    startIndex - index at which to insert the first element from the specified collection
    
    otherCollection - the collection whose elements are passed to add
    
    Returns:
    
    true if at least one call to add returns true; otherwise false
  - set
```
public O set(int index,
             O element)
```
    Specified by:
    
    set in interface List<O>
  - replaceAll
```
public void replaceAll(UnaryOperator<O> operator)
```
    Specified by:
    
    replaceAll in interface List<O>
  - remove
```
public O remove(int index)
```
    Specified by:
    
    remove in interface List<O>
  - sort
```
public void sort(Comparator<? super O> comparator)
```
    Specified by:
    
    sort in interface List<O>
  - listIterator
```
public ListIterator<O> listIterator()
```
    Specified by:
    
    listIterator in interface List<O>
  - listIterator
```
public ListIterator<O> listIterator(int startIndex)
```
    Specified by:
    
    listIterator in interface List<O>
  - subList
```
public List<O> subList(int fromIndex,
                       int toIndex)
```
    Specified by:
    
    subList in interface List<O>
  - equals
```
public final boolean equals(Object object)
```
    Specified by:
    
    equals in interface Collection<O>
    
    Specified by:
    
    equals in interface List<O>
  - hashCode
```
public final int hashCode()
```
    Specified by:
    
    hashCode in interface Collection<O>
    
    Specified by:
    
    hashCode in interface List<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

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

Class OptionalTransformingList<E>

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.util.List

Methods inherited from interface java.util.Collection

Methods inherited from interface java.lang.Iterable

Constructor Detail

OptionalTransformingList

OptionalTransformingList

OptionalTransformingList

OptionalTransformingList

Method Detail

getInnerList

isInnerElement

transformToOuter

isOuterElement

transformToInner

getInnerCollection

get

indexOf

lastIndexOf

add

addAll

callAddAllOnInner

callAddOnThis

set

replaceAll

remove

sort

listIterator

listIterator

subList

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