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

dk.rode.thesis.command
Class CommandProcessor

java.lang.Object
  extended by dk.rode.thesis.command.CommandProcessor

@Participant(value="Invoker")
public class CommandProcessor
extends Object

A command processor can execute and possibly undo a given group of commands.

Implementation notes:
This class is a variant of the POSA Command Processor pattern suggested by Schmidt et al. [Schmidt00, p.397] that also handles commands spawned by other commands during execution. This enables commands to express business-like semantics that can alter the behaviour at runtime depending on data. For example, a given command could based on data decide to spawn a new type of command to handle the data invariants, which in turn could spawn other commands, etc. The execution is depth-first, which ensures that changes performed by previously spawned commands will be available for later commands in the (original) list of commands to execute. An example of a command that possibly will spawn other commands is the ReverseCommand.

The support for spawned commands lessen the need for composite commands considerably, if not all together. In the general case, we feel it is better to let the command processor handle execution and undo of any command, including those otherwise stored in composites. This ensures uniform handling of all commands, consistent log format, more control, etc.

The supplied group of commands acts as part of a local history list, though in conjunction with possibly spawned commands, as described by Gamma et al. [Gamma95, p.238], but processors are stateless otherwise.

Command processors are not generic, but use generic methods to handle any type of command result value.

Author:
Gunni Rode / rode.dk
See Also:
execute(List), CommandProcessingResult

Constructor Summary
CommandProcessor()
          No-arg constructor.
 
Method Summary
<E> CommandProcessingResult<E>
execute(Command<E>... commands)
          Executes the commands supplied as commands, in order, or tries to undo executed commands in case of execution failure.
<E> CommandProcessingResult<E>
execute(List<Command<E>> commands)
          Executes the commands supplied as commands, in order, or tries to undo executed commands in case of execution failure.
private
<E> boolean
execute(List<Command<E>> commands, List<Command<E>> executedCommands)
          Executes the commands supplied as commands, in order, or tries to undo executed commands in case of execution failure.
 String toString()
          Returns the string representation of this processor.
private
<E> boolean
undo(List<Command<E>> executedCommands)
          Undoes the executed commands supplied as executedCommands, if possible.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

CommandProcessor

public CommandProcessor()
No-arg constructor.

Method Detail

execute

public <E> CommandProcessingResult<E> execute(Command<E>... commands)
                                   throws CommandException
Executes the commands supplied as commands, in order, or tries to undo executed commands in case of execution failure.

If the execution and undo fails, an exception is thrown. Otherwise a CommandProcessingResult is returned with the status and possible result of the execution. The result is that of the last executed command, which may be a spawned command.

Type Parameters:
E - The type of result obtained by executing the commands in commands.
Parameters:
commands - The group of commands to execute; cannot be null. A null command will cause an execution failure with a following attempt at undoing of previous executed commands.
Returns:
The result of the execution; never null.
Throws:
NullPointerException - If commands is null.
CommandException - If the execution (and undo) fails.
See Also:
execute(List)

execute

public <E> CommandProcessingResult<E> execute(List<Command<E>> commands)
                                   throws CommandException
Executes the commands supplied as commands, in order, or tries to undo executed commands in case of execution failure.

If the execution and undo fails, an exception is thrown. Otherwise a CommandProcessingResult is returned with the status and possible result of the execution. The result is that of the last executed command, which may be a spawned command.

Type Parameters:
E - The type of result obtained by executing the commands in commands.
Parameters:
commands - The list (group) of commands to execute. A null entry will cause an execution failure with a following attempt at undoing of previous executed commands.
Returns:
The result of the execution; never null.
Throws:
NullPointerException - If commands is null.
CommandException - If the execution (and undo) fails.
See Also:
execute(Command...)

execute

private <E> boolean execute(List<Command<E>> commands,
                            List<Command<E>> executedCommands)
                 throws CommandException
Executes the commands supplied as commands, in order, or tries to undo executed commands in case of execution failure.

Each executed command is added to the history list of executed commands supplied as executedCommands, which is the list that will be tried undone in case of execution failure.

If the execution and undo fails, an exception is thrown. If the execution fails, but all commands could be undone, this method returns false. Otherwise true to indicate execution success.

Type Parameters:
E - The type of result obtained by executing the commands in commands.
Parameters:
commands - The list (group) of commands to execute. A null entry will cause an execution failure with a following attempt at undoing of previous executed commands.
executedCommands - The history list of executed commands; never null.
Returns:
True if the execution succeeded, false if it failed but could be undone.
Throws:
NullPointerException - If either argument is null.
CommandException - If the execution and undo fails.

toString

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

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

undo

private <E> boolean undo(List<Command<E>> executedCommands)
              throws Exception
Undoes the executed commands supplied as executedCommands, if possible.

If the undo of a given undoable command fails, this method will throw an exception. If a given command is not undoable, this method returns false. True is returned if all commands could be undone.

Type Parameters:
E - The type of result obtained from the executed commands.
Parameters:
executedCommands - The executed commands to undo; cannot be null.
Returns:
True if all commands could be undone, false if not.
Throws:
NullPointerException - If executedCommands is null.
Exception - If the undo of a command fails.

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.