Command

About 3 min

The Command design pattern encapsulates a request as an object, thereby allowing for parameterization of clients with queues, requests, and operations. It also allows for the support of undoable operations.

Explanation

Real-world example

There is a wizard casting spells on a goblin. The spells are executed on the goblin one by one. The first spell shrinks the goblin and the second makes him invisible. Then the wizard reverses the spells one by one. Each spell here is a command object that can be undone.

In plain words

Storing requests as command objects allows performing an action or undoing it at a later time.

Wikipedia says

In object-oriented programming, the command pattern is a behavioral design pattern in which an object is used to encapsulate all information needed to perform an action or trigger an event at a later time.

Programmatic Example

Here's the sample code with wizard and goblin. Let's start from the Wizard class.


@Slf4j
public class Wizard {

    private final Deque<Runnable> undoStack = new LinkedList<>();
    private final Deque<Runnable> redoStack = new LinkedList<>();

    public Wizard() {
    }

    public void castSpell(Runnable runnable) {
        runnable.run();
        undoStack.offerLast(runnable);
    }

    public void undoLastSpell() {
        if (!undoStack.isEmpty()) {
            var previousSpell = undoStack.pollLast();
            redoStack.offerLast(previousSpell);
            previousSpell.run();
        }
    }

    public void redoLastSpell() {
        if (!redoStack.isEmpty()) {
            var previousSpell = redoStack.pollLast();
            undoStack.offerLast(previousSpell);
            previousSpell.run();
        }
    }

    @Override
    public String toString() {
        return "Wizard";
    }
}

Next, we have the goblin who's the target of the spells.


@Slf4j
public abstract class Target {

    private Size size;

    private Visibility visibility;

    public Size getSize() {
        return size;
    }

    public void setSize(Size size) {
        this.size = size;
    }

    public Visibility getVisibility() {
        return visibility;
    }

    public void setVisibility(Visibility visibility) {
        this.visibility = visibility;
    }

    @Override
    public abstract String toString();

    public void printStatus() {
        LOGGER.info("{}, [size={}] [visibility={}]", this, getSize(), getVisibility());
    }
}

public class Goblin extends Target {

    public Goblin() {
        setSize(Size.NORMAL);
        setVisibility(Visibility.VISIBLE);
    }

    @Override
    public String toString() {
        return "Goblin";
    }

    public void changeSize() {
        var oldSize = getSize() == Size.NORMAL ? Size.SMALL : Size.NORMAL;
        setSize(oldSize);
    }

    public void changeVisibility() {
        var visible = getVisibility() == Visibility.INVISIBLE
                ? Visibility.VISIBLE : Visibility.INVISIBLE;
        setVisibility(visible);
    }
}

Finally, we have the wizard in the main function casting spells.

public static void main(String[]args){
        var wizard=new Wizard();
        var goblin=new Goblin();

        // casts shrink/unshrink spell
        wizard.castSpell(goblin::changeSize);

        // casts visible/invisible spell
        wizard.castSpell(goblin::changeVisibility);

        // undo and redo casts
        wizard.undoLastSpell();
        wizard.redoLastSpell();

Here's the whole example in action.

var wizard=new Wizard();
        var goblin=new Goblin();

        goblin.printStatus();
        wizard.castSpell(goblin::changeSize);
        goblin.printStatus();

        wizard.castSpell(goblin::changeVisibility);
        goblin.printStatus();

        wizard.undoLastSpell();
        goblin.printStatus();

        wizard.undoLastSpell();
        goblin.printStatus();

        wizard.redoLastSpell();
        goblin.printStatus();

        wizard.redoLastSpell();
        goblin.printStatus();

Here's the program output:

Goblin,[size=normal][visibility=visible]
        Goblin,[size=small][visibility=visible]
        Goblin,[size=small][visibility=invisible]
        Goblin,[size=small][visibility=visible]
        Goblin,[size=normal][visibility=visible]
        Goblin,[size=small][visibility=visible]
        Goblin,[size=small][visibility=invisible]

Class diagram

Applicability

Use the Command pattern when you want to:

Parameterize objects by an action to perform. You can express such parameterization in a procedural language with a callback function, that is, a function that's registered somewhere to be called at a later point. Commands are an object-oriented replacement for callbacks.
Specify, queue, and execute requests at different times. A Command object can have a life independent of the original request. If the receiver of a request can be represented in an address space-independent way, then you can transfer a command object for the request to a different process and fulfill the request there.
Support undo. The Command's execute operation can store state for reversing its effects in the command itself. The Command interface must have an added un-execute operation that reverses the effects of a previous call to execute. The executed commands are stored in a history list. Unlimited-level undo and redo functionality is achieved by traversing this list backward and forward calling un-execute and execute, respectively.
Support logging changes so that they can be reapplied in case of a system crash. By augmenting the Command interface with load and store operations, you can keep a persistent log of changes. Recovering from a crash involves reloading logged commands from the disk and re-executing them with the execute operation.
Structure a system around high-level operations build on primitive operations. Such a structure is common in information systems that support transactions. A transaction encapsulates a set of data changes. The Command pattern offers a way to model transactions. Commands have a common interface, letting you invoke all transactions the same way. The pattern also makes it easy to extend the system with new transactions.
Keep a history of requests.
Implement callback functionality.
Implement the undo functionality.

Known uses

GUI Buttons and menu items in desktop applications.
Operations in database systems and transactional systems that support rollback.
Macro recording in applications like text editors and spreadsheets.
java.lang.Runnableopen in new window
org.junit.runners.model.Statementopen in new window
Netflix Hystrixopen in new window
javax.swing.Actionopen in new window

Consequences

Benefits:

Decouples the object that invokes the operation from the one that knows how to perform it.
It's easy to add new Commands, because you don't have to change existing classes.
You can assemble a set of commands into a composite command.

Trade-offs:

Increases the number of classes for each individual command.
Can complicate the design by adding multiple layers between senders and receivers.

Compositeopen in new window: Commands can be composed using the Composite pattern to create macro commands.
Mementoopen in new window: Can be used for implementing undo mechanisms.
Observeropen in new window: The pattern can be observed for changes that trigger commands.

Command

Also known as

Intent

Explanation

Class diagram

Applicability

Known uses

Consequences

Credits