com.levigo.util.base.glazedlists
Class FunctionList<S,E>

java.lang.Object
  com.levigo.util.base.glazedlists.AbstractEventList<E>
      com.levigo.util.base.glazedlists.TransformedList<S,E>
          com.levigo.util.base.glazedlists.FunctionList<S,E>

All Implemented Interfaces:

ListEventListener<S>, EventList<E>, Iterable<E>, Collection<E>, EventListener, List<E>, RandomAccess

public final class FunctionList<S,E>
extends TransformedList<S,E>
implements RandomAccess

This List is meant to simplify the task of transforming each element of a source list to an element stored at the same index in this FunctionList. The logic of precisely how to transform the source elements is contained within a FunctionList.Function that must be supplied at the time of construction but can be changed afterward using setForwardFunction(com.levigo.util.base.glazedlists.FunctionList.Function). This FunctionList.Function is called the forward function because it creates elements in this FunctionList from elements that have been added or mutated within the source list. The forward function may be an implementation of either FunctionList.Function or FunctionList.AdvancedFunction.

An optional reverse FunctionList.Function which is capable of mapping the elements of this FunctionList back to the corresponding source element may be supplied in order to use the following mutating methods:

• AbstractEventList.add(Object)
• add(int, Object)
• set(int, Object)

If the reverse FunctionList.Function is not supplied then callers of those methods will receive an IllegalStateException explaining that those operations are not available without the reverse FunctionList.Function.

If specified, the reverse FunctionList.Function should do its best to maintain the invariant:

o.equals(reverseFunction.evaluate(forwardFunction.evaluate(o))) for any o that is non-null.

Note: if two source elements share the same identity (i.e. source.get(i) == source.get(j) when i != j), it is up to author of the FunctionList.Function to decide if and how to preserve the relationship of their identities after their transformation.

Warning: This class is thread ready but not thread safe. See EventList for an example of thread safe code.

EventList Overview

Overview

Writable:	yes
Concurrency:	thread ready, not thread safe
Performance:	reads: O(1), writes O(1) amortized
Memory:
Unit Tests:	FunctionList
Issues:	282

Nested Class Summary

static interface	FunctionList.AdvancedFunction<A,B> An AdvancedFunction is an extension of the simple Function interface which provides more hooks in the lifecycle of the transformation of a source element.
static interface	FunctionList.Function<A,B> A Function encapsulates the logic for transforming a list element into any kind of Object.

Field Summary

Fields inherited from class com.levigo.util.base.glazedlists.TransformedList

source

Fields inherited from class com.levigo.util.base.glazedlists.AbstractEventList

publisher, readWriteLock, updates

Constructor Summary

FunctionList(EventList<S> source, FunctionList.Function<S,E> forward)
Construct a FunctionList which stores the result of transforming each source element using the given forward FunctionList.Function.

FunctionList(EventList<S> source, FunctionList.Function<S,E> forward, FunctionList.Function<E,S> reverse)
Construct a FunctionList which stores the result of transforming each source element using the given forward FunctionList.Function.

Method Summary

void	add(int index, E value) Inserts the specified element at the specified position in this list (optional operation).
E	get(int index) Returns the element at the specified position in this list.
FunctionList.Function<S,E>	getForwardFunction() Returns the FunctionList.Function which maps source elements to elements stored within this FunctionList.
FunctionList.Function<E,S>	getReverseFunction() Returns the FunctionList.Function which maps elements stored within this FunctionList back to elements within the source list or null if no such FunctionList.Function was specified.
protected boolean	isWritable() Gets whether the source EventList is writable via this API.
void	listChanged(ListEvent<S> listChanges) When the underlying list changes, this notification allows the object to repaint itself or update itself as necessary.
E	remove(int index) Removes the element at the specified position in this list (optional operation).
E	set(int index, E value) Replaces the element at the specified position in this list with the specified element (optional operation).
void	setForwardFunction(FunctionList.Function<S,E> forward) Changes the FunctionList.Function that evaluates source elements to produce mapped elements.
void	setReverseFunction(FunctionList.Function<E,S> reverse) Changes the FunctionList.Function that evaluates FunctionList elements to produce the original source element with which it corresponds.

Methods inherited from class com.levigo.util.base.glazedlists.TransformedList

addAll, clear, dispose, getSourceIndex, removeAll, retainAll, size

Methods inherited from class com.levigo.util.base.glazedlists.AbstractEventList

add, addAll, addListEventListener, contains, containsAll, equals, getPublisher, getReadWriteLock, hashCode, indexOf, isEmpty, iterator, lastIndexOf, listIterator, listIterator, remove, removeListEventListener, subList, toArray, toArray, toString

Methods inherited from class java.lang.Object

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

Constructor Detail

FunctionList

public FunctionList(EventList<S> source,
                    FunctionList.Function<S,E> forward)

Construct a FunctionList which stores the result of transforming each source element using the given forward FunctionList.Function. No reverse FunctionList.Function will be specified implying that AbstractEventList.add(Object), add(int, Object) and set(int, Object) will throw IllegalArgumentException if they are called.

Parameters:

source - the EventList to decorate with a function transformation

forward - the function to execute on each source element

FunctionList

public FunctionList(EventList<S> source,
                    FunctionList.Function<S,E> forward,
                    FunctionList.Function<E,S> reverse)

Construct a FunctionList which stores the result of transforming each source element using the given forward FunctionList.Function. If the reverse FunctionList.Function is not null, AbstractEventList.add(Object), add(int, Object) and set(int, Object) will execute as expected.

Note: an FunctionList.AdvancedFunction can be specified for the forward FunctionList.Function which allows the implementor a chance to examine the prior value that was mapped to a source element when it must be remapped due to a modification (from a call to List.set(int, E)).

Parameters:

source - the EventList to decorate with a function transformation

forward - the function to execute on each source element

reverse - the function to map elements of FunctionList back to element values in the source list

Method Detail

setForwardFunction

public void setForwardFunction(FunctionList.Function<S,E> forward)

Changes the FunctionList.Function that evaluates source elements to produce mapped elements. Calling this method with a different forward Function will cause all elements in this FunctionList to be reevaluated.

Callers of this method typically also want to update the reverse function using setReverseFunction(com.levigo.util.base.glazedlists.FunctionList.Function) if one exists.

getForwardFunction

public FunctionList.Function<S,E> getForwardFunction()

Returns the FunctionList.Function which maps source elements to elements stored within this FunctionList. The FunctionList.Function is guaranteed to be non-null.

setReverseFunction

public void setReverseFunction(FunctionList.Function<E,S> reverse)

Changes the FunctionList.Function that evaluates FunctionList elements to produce the original source element with which it corresponds. The reverse Function will be used in all subsequent calls to:

• AbstractEventList.add(Object)
• add(int, Object)
• set(int, Object)

This method should typically be called at the same time the forward function is changed using setForwardFunction(com.levigo.util.base.glazedlists.FunctionList.Function).

getReverseFunction

public FunctionList.Function<E,S> getReverseFunction()

Returns the FunctionList.Function which maps elements stored within this FunctionList back to elements within the source list or null if no such FunctionList.Function was specified.

isWritable

protected boolean isWritable()

Gets whether the source EventList is writable via this API.

Extending classes must override this method in order to make themselves writable.

Specified by:

isWritable in class TransformedList<S,E>

listChanged

public void listChanged(ListEvent<S> listChanges)

When the underlying list changes, this notification allows the object to repaint itself or update itself as necessary.

It is mandatory that the calling thread has obtained the write lock on the source list. This is because the calling thread will have written to the source list to cause this event. This condition guarantees that no writes can occur while the listener is handling this event. It is an error to write to the source list while processing an event.

Specified by:

listChanged in interface ListEventListener<S>

Specified by:

listChanged in class TransformedList<S,E>

get

public E get(int index)

Returns the element at the specified position in this list.

Specified by:

get in interface List<E>

Overrides:

get in class TransformedList<S,E>

Parameters:

index - index of element to return.

Returns:

the element at the specified position in this list.

remove

public E remove(int index)

Removes the element at the specified position in this list (optional operation). Shifts any subsequent elements to the left (subtracts one from their indices). Returns the element that was removed from the list.

Specified by:

remove in interface List<E>

Overrides:

remove in class TransformedList<S,E>

Parameters:

index - the index of the element to removed.

Returns:

the element previously at the specified position.

set

public E set(int index,
             E value)

Replaces the element at the specified position in this list with the specified element (optional operation).

Specified by:

set in interface List<E>

Overrides:

set in class TransformedList<S,E>

Parameters:

index - index of element to replace.

value - element to be stored at the specified position.

Returns:

the element previously at the specified position.

add

public void add(int index,
                E value)

Inserts the specified element at the specified position in this list (optional operation). Shifts the element currently at that position (if any) and any subsequent elements to the right (adds one to their indices).

Specified by:

add in interface List<E>

Overrides:

add in class TransformedList<S,E>

Parameters:

index - index at which the specified element is to be inserted.

value - element to be inserted.