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

dk.rode.thesis.command
Class SequenceCommand<E>

java.lang.Object
  extended by dk.rode.thesis.command.SequenceCommand<E>
Type Parameters:
E - The type of values returned by this command, i.e. the type of values delivered by the receiving sequence.
All Implemented Interfaces:
Command<E>, Copyable<Command<E>>, StrictCopyable<Command<E>>
Direct Known Subclasses:
NextCommand, ResetCommand, ReverseCommand

@Participant(value="Command")
public abstract class SequenceCommand<E>
extends Object
implements Command<E>

A sequence command is a command that manipulates the state of a sequence when it is executed. The sequence in question is the receiver.

Sequence commands are not thread-safe and cannot be shared, as they carry information required for a specific execution. However, sequence commands supply a copy method to return a new command of the same type using the same sequence as is. Any state related to the execution is not copied.

By default, two sequence commands having the exact same class and using the same sequence are considered equal.

Implementation notes:
A simple version of the Template Method pattern is applied here [Gamma95, p.325]: the (final) execute() method is the template method that utilises the primitive operation doExecute(boolean), which sub-classes must implement. If the sequence in question is a memorizable sequence, this command is able to be undone using the default isUndoable() and undo() implementations as execute() saves the before state. Hence, isUndoable() and undo() are hook operations that can be overridden by sub-commands if specific control of the undo mechanism is required, as for example done in the ResetCommand class.

Author:
Gunni Rode / rode.dk

Field Summary
private  SequenceMemento<E> memento
          A sequence memento to restore the previous state if sequence is a memorizable sequence.
protected  E result
          The result of the execution.
protected  Sequence<E> sequence
          The sequence receiver used by this command.
 
Constructor Summary
protected SequenceCommand(Sequence<E> sequence)
          Constructor, which creates this sequence command to use the Sequence supplied as sequence as the receiver.
 
Method Summary
protected abstract  List<Command<E>> doExecute(boolean saved)
          Performs the actual execution of this command.
 boolean equals(Object object)
          Returns true if object has the same class as this sequence command and uses the same sequence receiver, false if not.
 List<Command<E>> execute()
          Saves the before state of this sequence command if the receiver sequence is a memorizable sequence before execution.
 E getResult()
          Returns the result of the execution of this command.
 int hashCode()
          Returns the hash code of this sequence command.
 boolean isUndoable()
          Returns true if this sequence command has been executed and can be undone by this sequence command, false if not.
 String toString()
          Returns the string representation of this sequence command.
 E undo()
          Performs undo of this sequence command if possible.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface dk.rode.thesis.command.Command
copy
 

Field Detail

memento

private SequenceMemento<E> memento
A sequence memento to restore the previous state if sequence is a memorizable sequence.

Will only be set if execute() is invoked by sub-classes before their actual execution.

Can be null.


result

protected E result
The result of the execution.

Can be null.


sequence

@Participant(value="Receiver")
protected final Sequence<E> sequence
The sequence receiver used by this command.

Never null.

Constructor Detail

SequenceCommand

protected SequenceCommand(@Participant(value="Receiver")
                          Sequence<E> sequence)
Constructor, which creates this sequence command to use the Sequence supplied as sequence as the receiver.

Parameters:
sequence - The sequence; cannot be null.
Throws:
NullPointerException - If sequence is null.
Method Detail

doExecute

protected abstract List<Command<E>> doExecute(boolean saved)
                                       throws CommandException
Performs the actual execution of this command.

After successful execution, the result of the execution can be obtained via the getResult() method.

Parameters:
saved - True if the before state was successfully saved before this method is invoked, false if not.
Returns:
A list of spawned commands, if any, to be executed by the command processor currently executing this command. Can be null or empty.
Throws:
CommandException - If the execution fails.
See Also:
execute()

equals

public boolean equals(Object object)
Returns true if object has the same class as this sequence command and uses the same sequence receiver, false if not.

Overrides:
equals in class Object
Parameters:
object - The object to test; can be null.
Returns:
True if equal, false if not.

execute

public final List<Command<E>> execute()
                               throws CommandException
Saves the before state of this sequence command if the receiver sequence is a memorizable sequence before execution.

Specified by:
execute in interface Command<E>
Returns:
A list of spawned commands, if any, to be executed by the command processor currently executing this command. Can be null or empty.
Throws:
CommandException - If the execution fails.
See Also:
doExecute(boolean)

getResult

public E getResult()
Description copied from interface: Command
Returns the result of the execution of this command.

Invoking this method before execution will cause an illegal state exception to be thrown. If undone, this command must be re-executed before the result can be fetched again.

Specified by:
getResult in interface Command<E>
Returns:
The result of the execution; can be null.

hashCode

public int hashCode()
Returns the hash code of this sequence command.

Overrides:
hashCode in class Object
Returns:
The hash code.

isUndoable

public boolean isUndoable()
Returns true if this sequence command has been executed and can be undone by this sequence command, false if not.

Specified by:
isUndoable in interface Command<E>
Returns:
Returns true of the receiving sequence is a memorizable sequence that has been executed, false if not.

toString

public String toString()
Returns the string representation of this sequence command.

Overrides:
toString in class Object
Returns:
The string representation; never null.

undo

public E undo()
       throws CommandException
Performs undo of this sequence command if possible.

If this command is not undoable an exception will be thrown. If this command cannot be undone otherwise, null will be returned.

The command result value is cleared.

Specified by:
undo in interface Command<E>
Returns:
If this command could be undone, the (new) current sequence value is returned; otherwise null.
Throws:
CommandException - In case this command is not undoable.

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.