dk.rode.thesis.adapter
Class SequenceAdapter<E,T>

java.lang.Object
  dk.rode.thesis.adapter.SequenceAdapter<E,T>

Type Parameters:

E - The adaptee type adapted by this sequence adapter.

T - The adapted (target) type delivered by this sequence adapter.

All Implemented Interfaces:

Sequence<T>, Copyable<Sequence<T>>, StrictCopyable<Sequence<T>>, Stringable<Sequence<T>>

@ParticipantUsage(value="Target",
                  type=Sequence.class)
@Participant(value="Adapter")
public class SequenceAdapter<E,T>
extends Object
implements Sequence<T>

The sequence adapter acts as a generic type adapter for sequence parameterised types, i.e. from Sequence<E> to Sequence<T>, by using an adapter delegate to perform the representation shift.

An sequence adapter exhibit the same bounded, consistent, and unique properties as the adapted sequence.

Implementation notes:
It is essentially an object adapter in that it forwards all sequence requests to the adapted sequence, but a bit unusual in that it does not adapt the raw type, but the instantiated generic type of its own raw type. In that respect it is more related to class adaptation than object adaptation. Of cause, a combination that adapts both the raw and parameter types can be made as well.

An adapted sequence based on the type parameters is more than just a cast into a given sequence type. Casting with type parameters is unsafe, and would cause a compiler warning and perhaps runtime errors, but a sequence adapter constructs a new generic type based on the type parameters supplied to it with full type-safety.

The <? super E,? extends T> bounds for the adapter delegate used ensures greater flexibility than just using <E,T>. For example, the AdapterStrategy.NUMBER_TO_STRING strategy can be used to adapt any sequence delivering sub-classes of java.lang.Number into a sequence delivering java.lang.String values:

   
   Sequence<Integer> integerSequence = ..;
   Sequence<String> stringSequence = 
     new SequenceAdapter<Integer,String>(
       integerSequence, 
       AdapterStrategy.NUMBER_TO_STRING // ok, Number super-class of Integer!
     );    
 

Author:

Gunni Rode / rode.dk

See Also:

AdapterDelegate, create(Sequence)

Nested Class Summary

Nested classes/interfaces inherited from interface dk.rode.thesis.meta.model.Sequence

Sequence.State

Field Summary

private AdapterDelegate<? super E,? extends T>	adapterDelegate The adapter delegate to transform sequence values of type E into type T.
(package private) Sequence<E>	sequence The original sequence handling type E.

Constructor Summary

SequenceAdapter(Sequence<E> sequence, AdapterDelegate<? super E,? extends T> adapterDelegate)
Constructor.

SequenceAdapter(SequenceAdapter<E,T> adapter)
Copy constructor.

Method Summary

boolean	bounded() Returns true if this sequence is bounded, i.e.
boolean	consistent() Returns true if this sequence is consistent, i.e. deliver the same values, in order, after restart or reset.
Sequence<T>	copy() Returns a copy of this sequence that will start at the same sequence index as this sequence.
static <V> Sequence<Object>	create(Sequence<V> sequence) Factory method that creates a sequence adapting the type of values supplied by sequence to Object.
T	current() Returns the current element from this sequence.
boolean	equals(Object object) Returns true if object is a sequence adapter adapting the same sequence as this adapter based on equals(Object), false if not.
AdapterDelegate<? super E,? extends T>	getAdapterDelegate() Returns the adapter delegate used to perform the representation shift from type E to type T.
StringablePolicy<? super Sequence<T>>	getStringablePolicy(StringablePolicy<? super Sequence<T>> policy) Always return a non-null policy: policy is not null: policy is returned.
int	hashCode() Returns the hash code of this sequence.
T	next() Returns the next element from this sequence.
void	reset() Resets this sequence to start over if it is consistent.
Sequence.State	state() Returns the internal state of this sequence.
String	toString()
CharSequence	toString(StringablePolicy<? super Sequence<T>> policy) Returns a char sequence representation of this stringable object using the format determined by policy or the default policy in case policy is null.
boolean	unique() Returns true if this sequence deliver a given sequence value at most one time until reset or restarted.

Methods inherited from class java.lang.Object

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

Field Detail

adapterDelegate

private final AdapterDelegate<? super E,? extends T> adapterDelegate

The adapter delegate to transform sequence values of type E into type T.

Never null.

sequence

@Participant(value="Adaptee")
final Sequence<E> sequence

The original sequence handling type E.

Never null.

Constructor Detail

SequenceAdapter

public SequenceAdapter(@Participant(value="Adaptee")
                       Sequence<E> sequence,
                       AdapterDelegate<? super E,? extends T> adapterDelegate)

Constructor.

Parameters:

sequence - The sequence adaptee; cannot be null.

adapterDelegate - The adapter delegate to adapt type E into type T; cannot be null.

Throws:

NullPointerException - If either argument is null.

SequenceAdapter

public SequenceAdapter(SequenceAdapter<E,T> adapter)

Copy constructor.

The adapted sequence is also copied.

Parameters:

adapter - The sequence adapter to copy; cannot be null.

Throws:

NullPointerException - If adapter is null.

Method Detail

bounded

public boolean bounded()

Description copied from interface: Sequence

Returns true if this sequence is bounded, i.e. deliver values between the initial sequence value and some upper bound.

The same type of sequence may represent both bounded and unbounded sequences and the behaviour is determined and fixed at construction time. Bounded sequences will restart if they deliver consistent values.

Specified by:

bounded in interface Sequence<T>

Returns:

True if bounded, false if not.

See Also:

Sequence.unique()

consistent

public boolean consistent()

Description copied from interface: Sequence

Returns true if this sequence is consistent, i.e. deliver the same values, in order, after restart or reset.

Only bounded consistent sequences will restart. Consistent sequences need not deliver unique sequence values.

Instances of the same type of sequences are always consistent or inconsistent; it is determined at design time, not construction time.

Specified by:

consistent in interface Sequence<T>

Returns:

True if consistent, false if not.

copy

public Sequence<T> copy()

Description copied from interface: Sequence

Returns a copy of this sequence that will start at the same sequence index as this sequence.

Specified by:

copy in interface Sequence<T>

Specified by:

copy in interface Copyable<Sequence<T>>

Returns:

A copy of this sequence; never null.

create

public static <V> Sequence<Object> create(Sequence<V> sequence)

Factory method that creates a sequence adapting the type of values supplied by sequence to Object.

This is useful if wild-cards is to be used as sequence values, but where the type must still be known locally, for example in case of decoration.

Implementation notes:
The returned type is not just a cast into Sequence<Object>, which would cause an unchecked warning by the way, but a new type with the specific generic type Sequence<Object>. The generic type parameter V is required for the actual SequenceAdapter created, and hence a wild-card cannot be used.

Type Parameters:

V - The type of values delivered by sequence.

Parameters:

sequence - The sequence to adapt; cannot be null.

Returns:

An adapted sequence, where the returned values are of type Object; never null.

Throws:

NullPointerException - If sequence is null.

current

public T current()

Description copied from interface: Sequence

Returns the current element from this sequence.

This method can be invoked even if Sequence.next() has not been invoked yet, thus delivering the initial value of this sequence.

Specified by:

current in interface Sequence<T>

Returns:

The current element; never null.

equals

public boolean equals(Object object)

Returns true if object is a sequence adapter adapting the same sequence as this adapter based on equals(Object), false if not.

Overrides:

equals in class Object

Parameters:

object - The object to test; can be null.

Returns:

True if equal, false if not.

getAdapterDelegate

public AdapterDelegate<? super E,? extends T> getAdapterDelegate()

Returns the adapter delegate used to perform the representation shift from type E to type T.

Returns:

The delegate; never null.

getStringablePolicy

public StringablePolicy<? super Sequence<T>> getStringablePolicy(StringablePolicy<? super Sequence<T>> policy)

Description copied from interface: Stringable

Always return a non-null policy:

1. policy is not null: policy is returned.

2. policy is null: a default, non-null policy is returned.

Specified by:

getStringablePolicy in interface Stringable<Sequence<T>>

Parameters:

policy - The supplied policy; can be null.

Returns:

The policy to use; never null.

See Also:

Stringable.toString(StringablePolicy)

hashCode

public int hashCode()

Returns the hash code of this sequence.

Overrides:

hashCode in class Object

Returns:

The hash code.

next

public T next()

Description copied from interface: Sequence

Returns the next element from this sequence.

Specified by:

next in interface Sequence<T>

Returns:

The next element; never null.

See Also:

Sequence.current(), Sequence.state()

reset

public void reset()

Description copied from interface: Sequence

Resets this sequence to start over if it is consistent.

If this sequence is consistent, the sequence will restart.

Specified by:

reset in interface Sequence<T>

state

public Sequence.State state()

Description copied from interface: Sequence

Returns the internal state of this sequence.

Specified by:

state in interface Sequence<T>

Returns:

The internal state; never null.

toString

public String toString()

Overrides:

toString in class Object

toString

public CharSequence toString(StringablePolicy<? super Sequence<T>> policy)

Description copied from interface: Stringable

Returns a char sequence representation of this stringable object using the format determined by policy or the default policy in case policy is null.

In Foo, a typical implementation of this method could be:

    public CharSequence toString(StringablePolicy<? super Foo> policy) {
      return this.getStringablePolicy(policy).toString(this);
    }
 

There are two approaches to formatting this stringable object into a char sequence representation:

1. Let policy decide the entire format, as in the Foo example above; or

2. Use policy to format part of the overall representation, for example letting this method append certain text regardless of the policy used.

Bullet 1) is not always applicable because a given policy implementation may not have access to all required information in its StringablePolicy.toString(Object) method, for example in case multiple stringable objects should be formatted into an overall representation.

In case an implementation uses the approach from bullet 2), care must be take to respect the policy hints so the overall format remains meaningful.

Specified by:

toString in interface Stringable<Sequence<T>>

Parameters:

policy - The policy to dictate the formatting; can be null, in which case the result of toString method is returned.

Returns:

The char sequence representation; never null.

See Also:

StringablePolicy.Type

unique

public boolean unique()

Description copied from interface: Sequence

Returns true if this sequence deliver a given sequence value at most one time until reset or restarted.

Unbounded sequences that are unique will never deliver the same sequence value more than once.

The same type of sequence may represent both unique and not unique sequences and the behaviour is determined and fixed at construction time.

Specified by:

unique in interface Sequence<T>

Returns:

True if unique, false if not.

See Also:

Sequence.consistent()