dk.rode.thesis.memento
Class SequenceMemento<E>

java.lang.Object
  dk.rode.thesis.memento.SequenceMemento<E>

Type Parameters:

E - The type of values delivered by applicable memorizable sequences.

All Implemented Interfaces:

Stringable<Sequence<E>>

Direct Known Subclasses:

GuardedSequenceMemento

@Participant(value="Memento")
public class SequenceMemento<E>
extends Object
implements Stringable<Sequence<E>>

A sequence memento represents a snap-shot of a given sequence at the time the SequenceMemento(Sequence) constructor or the setSequence(Sequence) method was invoked.

A memento can represent any type of sequence, but only memorizable sequences have a direct interface for getting and setting the sequence value based on mementos.

Sequence mementos are thread-safe.

Implementation notes:
Sequence mementos uses the Prototype pattern to save the state of a given sequence by copying its state.

All memento functionality has to be declared public if it must be used outside this package. It cannot have "two interfaces" in Java, a narrow (public) and a wide (public and private), as described by Gamma et al. [Gamma95, p.285-287]. This class corresponds to the private part of the wide interface, while the MemorizableSequence corresponds to the narrow (public) interface. No access check is made in this class, but the GuardedSequenceMemento provides an alternative, and tests if the caller is a sequence of the proper type.

Author:

Gunni Rode / rode.dk

Field Summary

private Sequence<E>

sequence A local (copy) sequence instance that stores internal state.

Constructor Summary

SequenceMemento()
No-arg constructor.

SequenceMemento(Sequence<E> sequence)
Constructor.

Method Summary

E	current() Returns the value stored in the memorised sequence.
Sequence<E>	getSequence() Return the sequence memorised by this memento.
StringablePolicy<? super Sequence<E>>	getStringablePolicy(StringablePolicy<? super Sequence<E>> policy) Always return a non-null policy: policy is not null: policy is returned.
void	setSequence(Sequence<E> sequence) Memorises the state of the Sequence supplied as sequence by copying it.
String	toString() Returns the string representation of this memento.
CharSequence	toString(StringablePolicy<? super Sequence<E>> 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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

sequence

private Sequence<E> sequence

A local (copy) sequence instance that stores internal state.

Can be null until set.

Constructor Detail

SequenceMemento

public SequenceMemento()

No-arg constructor.

The sequence representing the state to memorise must be set explicitly using the setSequence(Sequence) method.

SequenceMemento

public SequenceMemento(Sequence<E> sequence)

Constructor.

Parameters:

sequence - The sequence representing the state to memorise; cannot be null. This memento does not keep a reference to sequence, but copies it.

Throws:

NullPointerException - If sequence is null.

Method Detail

current

public E current()

Returns the value stored in the memorised sequence.

Returns:

The current (fixed) value; never null.

Throws:

IllegalStateException - If no sequence has been set.

getSequence

public Sequence<E> getSequence()

Return the sequence memorised by this memento.

Mutating the returned sequence will not alter the internal state of this memento.

Returns:

The memorised sequence; never null.

Throws:

IllegalStateException - If no sequence has been set.

See Also:

setSequence(Sequence)

getStringablePolicy

public StringablePolicy<? super Sequence<E>> getStringablePolicy(StringablePolicy<? super Sequence<E>> 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<E>>

Parameters:

policy - The supplied policy; can be null.

Returns:

The policy to use; never null.

See Also:

Stringable.toString(StringablePolicy)

setSequence

public void setSequence(Sequence<E> sequence)

Memorises the state of the Sequence supplied as sequence by copying it. The copy can then be retrieved using the getSequence() method.

Parameters:

sequence - The sequence representing the state to memorise; cannot be null. This memento does not keep a reference to sequence, but copies it.

Throws:

NullPointerException - If sequence is null.

IllegalStateException - If a sequence has already been set.

toString

public String toString()

Returns the string representation of this memento.

Overrides:

toString in class Object

Returns:

The string representation; never null.

toString

public CharSequence toString(StringablePolicy<? super Sequence<E>> 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<E>>

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