The Command Pattern

An action as an object

Everything in this module has been building toward this. A command is an object whose purpose is to represent something to be done, rather than doing it immediately.

interface Command {
    void execute();
}

That is the minimal form. Because the action is an object, you can put it in a list, hand it to another method, keep it for later, or store enough information to reverse it.

Command spinUp = () -> shooter.set(0.9);
Command stop   = () -> shooter.set(0.0);

Neither has run. They are values describing work, created with lambdas.

Why not just call the method?

If you only ever want the action to happen right now, call it — the pattern is unnecessary overhead.

It earns its place when you need one of these:

Adding lifecycle

A single execute() is enough for instant actions, but most real work takes several cycles — driving to a position, spinning a flywheel up to speed. That needs a richer shape:

interface Command {
    default void initialize() {}          // once, at the start
    void execute();                        // repeatedly, each cycle
    default boolean isFinished() {         // when should it stop?
        return false;
    }
    default void end(boolean interrupted) {}  // once, at the end
}

default methods let an implementation override only what it cares about. A simple command supplies execute and nothing else.

class SpinUpShooter implements Command {
    private final Shooter shooter;
    private final double targetRpm;

    SpinUpShooter(Shooter shooter, double targetRpm) {
        this.shooter = shooter;
        this.targetRpm = targetRpm;
    }

    @Override public void initialize() {
        shooter.setTarget(targetRpm);
    }

    @Override public void execute() {
        shooter.update();
    }

    @Override public boolean isFinished() {
        return shooter.atTargetSpeed();
    }

    @Override public void end(boolean interrupted) {
        if (interrupted) shooter.stop();
    }
}

The dependencies arrive through the constructor — dependency injection — so this class is testable with a fake shooter.

A scheduler

Something has to run these. The loop is short:

class Scheduler {
    private final List<Command> running = new ArrayList<>();

    void schedule(Command command) {
        command.initialize();
        running.add(command);
    }

    void run() {
        Iterator<Command> it = running.iterator();
        while (it.hasNext()) {
            Command c = it.next();
            c.execute();
            if (c.isFinished()) {
                c.end(false);
                it.remove();          // safe removal during iteration
            }
        }
    }

    void cancelAll() {
        for (Command c : running) {
            c.end(true);              // interrupted
        }
        running.clear();
    }
}

Using an Iterator with it.remove() is what allows removal mid-loop. A for-each with running.remove(c) would throw ConcurrentModificationException — the trap from the ArrayLists lesson.

Call run() once per cycle and every scheduled command advances one step.

Composing commands

Because commands are objects, you can build commands out of other commands. This is where the pattern becomes genuinely powerful.

class SequentialCommand implements Command {
    private final List<Command> steps;
    private int index = 0;

    SequentialCommand(Command... steps) {
        this.steps = List.of(steps);
    }

    @Override public void initialize() {
        index = 0;
        if (!steps.isEmpty()) steps.get(0).initialize();
    }

    @Override public void execute() {
        if (index >= steps.size()) return;

        Command current = steps.get(index);
        current.execute();

        if (current.isFinished()) {
            current.end(false);
            index++;
            if (index < steps.size()) {
                steps.get(index).initialize();
            }
        }
    }

    @Override public boolean isFinished() {
        return index >= steps.size();
    }
}

SequentialCommand is a Command, so it can be scheduled like any other — or nested inside another sequence.

Command autonomous = new SequentialCommand(
    new DriveDistance(drivetrain, 2.0),
    new SpinUpShooter(shooter, 4000),
    new Shoot(shooter, feeder),
    new DriveDistance(drivetrain, -2.0)
);

scheduler.schedule(autonomous);

An entire autonomous routine is one object. A parallel version — running several at once and finishing when all are done — follows the same shape.

Undo

Where the pattern is used for editing rather than scheduling, add a reverse operation:

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

class SetPosition implements UndoableCommand {
    private final Arm arm;
    private final double target;
    private double previous;

    SetPosition(Arm arm, double target) {
        this.arm = arm;
        this.target = target;
    }

    @Override public void execute() {
        previous = arm.getPosition();     // remember, so undo is possible
        arm.moveTo(target);
    }

    @Override public void undo() {
        arm.moveTo(previous);
    }
}

Push executed commands onto a stack; undo pops and reverses. That is how every editor’s undo works.

Related

Apply it on a robot