Command Pattern

Description

Command is the behavioral pattern for turning a request into an object: instead of calling editor.deleteLast(5) right away, you create a DeleteCommand that knows what to do and to whom. Because the request is now a thing, it can be stored, queued, logged, undone, redone or replayed. Undo/redo, job queues, macros and CQRS all rest on this idea. This skill covers the pattern, an undo/redo history, and what changes when commands travel through queues.

A text editor has Type, Delete and Paste buttons. Each button calls the editor directly:

typeButton.onClick(() -> editor.insert(text));
deleteButton.onClick(() -> editor.deleteLast(5));

type_button.on_click(lambda: editor.insert(text))
delete_button.on_click(lambda: editor.delete_last(5))

Now users want Undo and Redo, a keyboard shortcut for every action, and recordable macros. None of that is possible, because the actions happen immediately and leave nothing behind to undo, replay or queue.

We'll go from simple to more technical:

1. The pattern: commands, receivers and invokers.
2. Undo and redo with two stacks, step by step.
3. Where you'll see commands: executors, UI actions, job queues, CQRS.
4. What undo needs to remember, and the rules for commands that are queued or retried.

The pattern

Command turns a request into an object. The object knows what to do and to whom (the receiver), so it can be executed later, stored in a history, undone, or replayed.

interface Command {
    void execute();
    void undo();
}

class DeleteCommand implements Command {
    private final Editor editor;
    private final int count;
    private String deleted;                  // remembered so undo can restore it

    DeleteCommand(Editor editor, int count) { this.editor = editor; this.count = count; }

    public void execute() { deleted = editor.deleteLast(count); }
    public void undo()    { editor.insert(deleted); }
}

class History {
    private final Deque<Command> undoStack = new ArrayDeque<>();
    private final Deque<Command> redoStack = new ArrayDeque<>();

    void run(Command c) { c.execute(); undoStack.push(c); redoStack.clear(); }
    void undo() { if (!undoStack.isEmpty()) { Command c = undoStack.pop(); c.undo(); redoStack.push(c); } }
    void redo() { if (!redoStack.isEmpty()) { Command c = redoStack.pop(); c.execute(); undoStack.push(c); } }
}

from abc import ABC, abstractmethod


class Command(ABC):
    @abstractmethod
    def execute(self) -> None: ...

    @abstractmethod
    def undo(self) -> None: ...


class DeleteCommand(Command):
    def __init__(self, editor: Editor, count: int):
        self._editor = editor
        self._count = count
        self._deleted = ""                  # remembered so undo can restore it

    def execute(self) -> None:
        self._deleted = self._editor.delete_last(self._count)

    def undo(self) -> None:
        self._editor.insert(self._deleted)


class History:
    def __init__(self):
        self._undo: list[Command] = []      # a list is Python's stack: append / pop
        self._redo: list[Command] = []

    def run(self, c: Command) -> None:
        c.execute()
        self._undo.append(c)
        self._redo.clear()

    def undo(self) -> None:
        if self._undo:
            c = self._undo.pop()
            c.undo()
            self._redo.append(c)

    def redo(self) -> None:
        if self._redo:
            c = self._redo.pop()
            c.execute()
            self._undo.append(c)

How it works, step by step

1. Define a Command interface: execute() and, if you need it, undo().
2. Each concrete command stores its receiver and parameters, plus anything needed to undo.
3. An invoker (a button, a history, a job queue) calls execute() without knowing what the command does.
4. For undo/redo, keep two stacks: executing a new command pushes it on the undo stack and clears the redo stack.
5. A macro is just a command that holds a list of commands.

Where you'll see it

• Runnable and Callable handed to an ExecutorService are commands waiting to be run - in Python, functions and functools.partial objects handed to concurrent.futures, or tasks queued in Celery.
• UI frameworks' action objects (Swing Action) bind one command to a button, a menu item and a shortcut.
• Job queues and schedulers store commands (as serialized messages) to run later or retry.
• CQRS architectures model every write as a command object (PlaceOrder, CancelOrder).

Choosing among the behavioral patterns

Common mistakes

Check yourself

Try to answer before opening each one - recalling beats re-reading.

1. What must a DeleteCommand remember so that undo() works?

2. You undo twice, then run a new command. What happens to the redo history?

3. Why must commands sent through a job queue be idempotent?

Key takeaways

• A command is a request turned into an object: it can be executed later, queued, logged, undone or replayed.
• To undo, a command must remember what it changed.
• A new command clears the redo stack; failed commands never enter the history.
• Queued commands should be serializable and idempotent.
• A command is a request that may be rejected; an event is a fact that already happened.