Evaluating Software Design Patterns
— the "Gang of Four" patterns implemented in Java 6

dk.rode.thesis.composite
Interface CompositeSequence<E>

Type Parameters:
E - The type of values delivered by this composite sequence.
All Superinterfaces:
Copyable<Sequence<E>>, Iterable<Sequence<? extends E>>, Sequence<E>, StrictCopyable<Sequence<E>>, Stringable<Sequence<E>>
All Known Implementing Classes:
AbstractCompositeSequence, CharSequenceCompositeSequence, VisitableCompositeSequence

@ParticipantUsage(value={"Component","Leaf"},
                  type=Sequence.class)
@Participant(value="Composite")
public interface CompositeSequence<E>
extends Sequence<E>, Iterable<Sequence<? extends E>>

A composite sequence is a sequence that represents an number of other contained sequences, possibly composite as well. Sequence methods are propagated to each contained sequence in either a depth or breath first manner, determined via a changeable strategy.

The value returned by the current() and next() methods is sub-class specific.

Composite sequences are simple containers that do not maintain parent references. Contained sequences do not know they are contained unless this information is stored locally. Hence, graph traversal is top-down only.

Composite sequences are bounded and consistent if each contained sequence is bound and consistent, respectively, but composite sequences cannot be guaranteed to be unique even if all contained sequences are unique. Hence, composite sequences are per definition not unique.

Implementation notes:
Any sequence delivering a sequence value of type <? extends E> can be stored in a composite sequence of type E. This offers greater flexibility, while ensuring that all sequences in a composite sequence will match the E, and can thus be "concatenated in a proper fashion", for example appending strings, adding different types of numbers, etc.

Author:
Gunni Rode / rode.dk
See Also:
ObservableSequence

Nested Class Summary
 
Nested classes/interfaces inherited from interface dk.rode.thesis.meta.model.Sequence
Sequence.State
 
Method Summary
 boolean addSequence(Sequence<? extends E> sequence)
          Associates the sequence supplied as sequence to this composite sequence, if not already.
 CompositeStrategy getCompositeStrategy()
          Return the current strategy used by this composite sequence to traverse the associated sequence graph.
 List<Sequence<? extends E>> getSequences()
          Returns the sequences currently associated with this composite sequence, in order.
<V extends Sequence<?>>
List<V>
getSequences(Class<V> clazz)
          Returns the sequences currently associated with this composite sequence, in order, assignable to the type supplied as clazz.
 List<Sequence<? extends E>> getSequences(CompositeStrategy strategy, boolean includeSelf, Boolean type)
          Returns the sequences currently reachable from this composite sequence, in the order specified by strategy.
<V extends Sequence<?>>
List<V>
getSequences(CompositeStrategy strategy, boolean includeSelf, Boolean type, Class<V> clazz)
          Returns the sequences currently reachable from this composite sequence, in the order specified by strategy.
 boolean removeSequence(Sequence<?> sequence)
          Removes the sequence supplied as sequence from this composite sequence, if associated.
 void setCompositeStrategy(CompositeStrategy strategy)
          Sets the current strategy used by this composite sequence to traverse the associated sequence graph to strategy.
 int size()
          Returns the number of sequences associated to this composite sequence.
 
Methods inherited from interface dk.rode.thesis.meta.model.Sequence
bounded, consistent, copy, current, next, reset, state, unique
 
Methods inherited from interface dk.rode.thesis.strategy.Stringable
getStringablePolicy, toString
 
Methods inherited from interface java.lang.Iterable
iterator
 

Method Detail

addSequence

boolean addSequence(Sequence<? extends E> sequence)
Associates the sequence supplied as sequence to this composite sequence, if not already.

If already added, this method does nothing.

Parameters:
sequence - The sequence to add; cannot be null.
Returns:
True if sequence was added, false if not, i.e. if already added.
Throws:
NullPointerException - If sequence is null.
IllegalArgumentException - If sequence is not a valid sequence to add to this composite sequence.
See Also:
removeSequence(Sequence)

getCompositeStrategy

CompositeStrategy getCompositeStrategy()
Return the current strategy used by this composite sequence to traverse the associated sequence graph.

Returns:
The strategy; never null.

getSequences

List<Sequence<? extends E>> getSequences()
Returns the sequences currently associated with this composite sequence, in order.

Modifying the returned collection will not affect this sequence.

Returns:
The collection of associated sequences; never null, but can be empty.

getSequences

<V extends Sequence<?>> List<V> getSequences(Class<V> clazz)
Returns the sequences currently associated with this composite sequence, in order, assignable to the type supplied as clazz.

Invoking this method with the Sequence interface corresponds to invoking getSequences().

Modifying the returned collection will not affect this sequence.

Type Parameters:
V - The type of applicable sequences.
Parameters:
clazz - The (super-)class of sequences to include; cannot be null.
Returns:
The collection of associated sequences of the type supplied as clazz; never null, but can be empty.
Throws:
NullPointerException - If clazz is null.

getSequences

List<Sequence<? extends E>> getSequences(CompositeStrategy strategy,
                                         boolean includeSelf,
                                         Boolean type)
Returns the sequences currently reachable from this composite sequence, in the order specified by strategy.

This sequence is included in the returned list if includeSelf is true and it matches type; type determines the types of sequences to include in the returned list:

If strategy is null, the default strategy for this sequence is used.

Modifying the returned collection will not affect this sequence.

Parameters:
strategy - The strategy dictating the traversal; can be null.
includeSelf - True to include this composite sequence in the returned list (if it matches type), false to exclude.
type - The type of sequences to include in the returned list; can be null.
Returns:
The list of reachable sequences; never null, but can be empty.

getSequences

<V extends Sequence<?>> List<V> getSequences(CompositeStrategy strategy,
                                             boolean includeSelf,
                                             Boolean type,
                                             Class<V> clazz)
Returns the sequences currently reachable from this composite sequence, in the order specified by strategy. Each sequence included in the returned list is assignable to the type supplied as clazz.

This sequence is included in the returned list if it matches clazz and type; type determines the types of sequences to include in the returned list:

If strategy is null, the default strategy for this sequence is used.

Modifying the returned collection will not affect this sequence.

Type Parameters:
V - The type of applicable sequences.
Parameters:
strategy - The strategy dictating the traversal; can be null.
includeSelf - True to include this composite sequence in the returned list (if it matches type and clazz), false to exclude.
type - The type of sequences to include in the returned list; can be null.
clazz - The (super-)class of sequences to include; cannot be null.
Returns:
The collection of reachable sequences of the type supplied as clazz; never null, but can be empty.
Throws:
NullPointerException - If clazz is null.

removeSequence

boolean removeSequence(Sequence<?> sequence)
Removes the sequence supplied as sequence from this composite sequence, if associated.

If not associated, this method does nothing.

Parameters:
sequence - The sequence to remove; cannot be null.
Returns:
True if sequence was removed, false if not, i.e. if not previously added.
Throws:
NullPointerException - If sequence is null.
See Also:
addSequence(Sequence)

setCompositeStrategy

void setCompositeStrategy(CompositeStrategy strategy)
Sets the current strategy used by this composite sequence to traverse the associated sequence graph to strategy.

Parameters:
strategy - The strategy; can be null, in which case the default strategy is used.

size

int size()
Returns the number of sequences associated to this composite sequence.

Returns:
The number of sequences.

Gunni Rode / rode.dk

Feel free to use and/or modify the Java 6 source code developed for this thesis AT YOUR OWN RISK, but note that the source code comes WITHOUT ANY — and I do mean WITHOUT ANY — form of warranty WHAT SO EVER!

The original thesis and source code are available at rode.dk/thesis.