Tutoriel sur Pattern Command : Undo, variations Compensation/Replay/Memento

Dans le cas spatial, la commande est typiquement créée localement et exécutée sur un serveur distant/remote (les rôles du pattern Command sont indiqués sous forme de stéréotypes UML quand ils diffèrent des types propres à la variation Remote Command) :

La cinématique de la création d'une commande côté local et de son exécution côté distant est la suivante :

• Le Client (attention, pas au sens client-serveur) instancie la ConcreteCommand en lui passant les paramètres propres à une opération particulière.
• Le constructeur de la ConcreteCommand capture ces paramètres.
• Côté local, le LocalInvocator (ex. : un client-proxy EJB) déclenche l'exécution de la commande en l'envoyant au RemoteInvocator distant (sérialisation/remoting).
• Côté serveur, la commande est reçue par le RemoteInvocator (ex. : un serveur proxy EJB).
• Le RemoteInvocator instancie un ConcreteExecutionEnvironment, en passant au constructeur de ce dernier les ressources techniques nécessaires (EntityManager...). Le RemoteInvocator peut par exemple être un EJB @Remote.
• Le ConcreteExecutionEnvironment construit les récepteurs concrets (DAO...) en utilisant les ressources techniques fournies par le RemoteInvocator (EntityManager...)
• Le RemoteInvocator invoque la méthode execute de la commande en lui passant cette instance de ConcreteExecutionEnvironment.
• La méthode execute de la commande concrète invoque un ou plusieurs récepteurs abstraits (ex: Repository). Pour ce faire, elle récupère les Receptors cibles de la commande dans l'ExecutionEnvironment (ex: executionEnvironment.getRepository()).

Dans le cas temporel, le problème est différent : la commande peut être exécutée tout de suite, mais elle doit pouvoir être annulée ou rejouée à un instant ultérieur et indéfini. Comme le dit le GOF, un objet Commande peut avoir une durée de vie indépendante de la requête originelle. Il est donc nécessaire qu'un contexte maintienne une référence vers la commande exécutée. Dans la suite, on nomme ce contexte Conversation. Ce découplage temporel peut être utilisé de plusieurs façons :

• introduire un niveau d'asynchronisme (léger différé) entre la création de la commande et son exécution ;
• rejouer la commande ou son inverse (déclenché par la conversation).

Dans le cas qui nous intéresse ici, la conversation mémorise les commandes exécutées et déclenche l'undo/redo. Chacune des commandes stockées par la conversation continue à contenir les paramètres spécifiques à une exécution particulière, qui avaient été capturés lors de l'instanciation de la commande. Ce type de commande est typiquement exécuté dans le même environnement que celui où la commande a été instanciée, et la méthode execute n'a donc pas besoin d'un paramètre ExecutionEnvironnement (les ressources nécessaires à l'exécution peuvent être passées dès l'instanciation).

L'undo par commande a la structure suivante (les rôles du pattern Command sont indiqués sous forme de stéréotypes UML quand ils diffèrent des types propres à la variation Undo Command - en UML on devrait utiliser une « collaboration paramétrée », mais par facilité on utilise ici de simples stéréotypes) :

Il est évidemment possible de cumuler les deux difficultés, auquel cas le serveur devra à la fois fournir un ExecutionEnvironment et maintenir une pile des commandes déjà exécutées (un EJB Stateful permet par exemple de remplir ces deux fonctionnalités). Puisque ce post concerne l'undo, on simplifiera cependant en supposant que les commandes sont locales (intra-JVM, sans remoting).

Puisqu'on se place dans le cas simple sans ExecutionEnvironment, l'interface Command est la suivante :

@FunctionalInterface
public interface Command {
  void execute();
}

L'annotation @FunctionalInterface n'est pas obligatoire, mais elle a les avantages suivants :

• demande au compilateur de vérifier que notre interface est une Single Abstract Method Interface, qui peut être implémentée par un lambda ;
• documente ce fait aux utilisateurs de l'interface, et signale l'engagement de l'auteur du framework à maintenir cette caractéristique dans les versions futures.

Introduisons la conversation, qui est le scope dans lequel on exécute, annule, et rejoue des commandes :

public interface Conversation<C extends Command> {
  void exec(C cmd);
  void undo();
  void redo();
}

Le nom Conversation souligne le fait qu'il arrive souvent que le résultat d'une suite de commandes soit committé atomiquement, ce qui correspond à un scope conversation. La conversation est identifiée à l'Invocator (du pattern Command du GOF), qui a le double rôle de mémoriser et de déclencher les commandes. Ici, c'est le même Client qui instancie les commandes concrètes et qui demande à l'Invocator de les déclencher. Notons que l'interface Conversation est générique : elle porte un type parameter C extends Command. Le but est d'avoir une seule interface Conversation commune aux trois variations d'undo, tout en permettant l'utilisation par ses implémentations des trois déclinaisons de Command que nous allons présenter.

On montre les tests (ce qu'on veut faire) avant de montrer l'implémentation (comment on le fait). Les tests utilisent une commande TypeString qui représente la saisie d'un String dans un Display (les interfaces CompensableCommand et MementoableCommand sont expliquées dans les parties sur les variations correspondantes).

public class TypeString implements CompensableCommand, MementoableCommand {
 
  private final Display display;
  private final String stringToType;
 
  public TypeString(Display display, String stringToType) {
    this.display = display;
    this.stringToType = stringToType;
  }
 
  @Override public void execute() {
    display.append(stringToType);
  }
 
[...]
}

Le code passé sous silence pour l'instant est spécifique à une des trois variations.

Le receptor (cf. partie Rappels sur le pattern Command) Display est la cible de la commande concrète Typing :

public class Display {
 
  private final LinkedList<String> displayElements = new LinkedList<>();
 
  public void append(String stringToAppend) {
    displayElements.addLast(stringToAppend);
  }
 
  public String displayed() {
    // Collectors.joining est équivalent à un foreach+StringBuilder mais plus fonctionnel 
    // (évite l'itération externe/style impératif)
    return displayElements.stream().collect(Collectors.joining());
  }
 
[...]
}

Le code passé sous silence est spécifique à une des trois variations.

Pour s'assurer que les trois variations sont fonctionnellement équivalentes, on écrit les tests dans une classe abstraite CommandUndoTest_Typing. Les tests commencent par les cas triviaux et vont jusqu'à une conversation complexe :

/**
* Undo is noop when there were no execs
* undo --> ""
*/
@Test public void basicNoopUndo() {
  Conversation<C> commands = newConversation();
 
  commands.undo();
  assertEquals("", display.displayed());
}
 
/**
* Redo is noop when there were no undos
* redo --> ""
*/
@Test public void basicNoopRedo() {
  Conversation<C> commands = newConversation();
 
  commands.redo();
  assertEquals("", display.displayed());
}
 
/**
* Basic undo
* a    --> "a"
* undo --> ""
*/
@Test public void basicUndo() {
  Conversation<C> commands = newConversation();
 
  commands.exec(typeString("a"));
  assertEquals("a", display.displayed());
 
  commands.undo();
  assertEquals("", display.displayed());
}
 
/**
* Basic redo
* a    --> "a"
* undo --> ""
* redo --> "a"
*/
@Test public void basicRedo() {
  Conversation<C> commands = newConversation();
 
  commands.exec(typeString("a"));
  assertEquals("a", display.displayed());
 
  commands.undo();
  assertEquals("", display.displayed());
 
  commands.redo(); 
  assertEquals("a", display.displayed());
}
 
/**
* a    --> "a"
* b    --> "ab"
* undo --> "a"
* undo --> ""
* redo --> "a"
* redo --> "ab"
*/
@Test public void exec_exec_undo_undo_redo_redo() {
  Conversation<C> commands = newConversation();
 
  commands.exec(typeString("a"));
  assertEquals("a", display.displayed());
 
  commands.exec(typeString("b"));
  assertEquals("ab", display.displayed());
 
  commands.undo();
  assertEquals("a", display.displayed());
 
  commands.undo();
  assertEquals("", display.displayed());
 
  commands.redo();
  assertEquals("a", display.displayed());
 
  commands.redo();
  assertEquals("ab", display.displayed());
}

Certains des tests peuvent être consultés dans le code sur Github, mais ne sont pas mentionnés ici pour alléger l'article.

Les classes concrètes spécifiques aux trois variations ne font qu'instancier un type différent de Conversation (à un détail technique près, propre aux génériques Java) :

public class CommandUndoTest_Compensation_Typing_Test extends CommandUndoTest_Typing<CompensableCommand> {
    @Override protected Conversation<CompensableCommand> newConversation() {
        return new CompensationConversation();
    }
 
    @Override protected CompensableCommand typeString(String stringToType) {
        return new TypeString(display, stringToType);
    }
}
 
public class CommandUndoTest_Replay_Typing_Test extends CommandUndoTest_Typing<Command> {
    @Override protected Conversation<Command> newConversation() {
        return new ReplayConversation(()->{
            display.reset();
        });
    }
 
    @Override protected Command typeString(String stringToType) {
        return new TypeString(display, stringToType);
    }
}
 
public class CommandUndoTest_Memento_Typing_Test extends CommandUndoTest_Typing<MementoableCommand> {
    @Override protected Conversation<MementoableCommand> newConversation() {
        return new MementoConversation();
    }
 
    @Override protected MementoableCommand typeString(String stringToType) {
        return new TypeString(display, stringToType);
    }
}

Le cœur de l'implémentation est l'utilisation de deux stacks (FIFO), une pour l'undo et une pour le redo : intuitivement, on sent bien que :

• chaque exécution de commande rajoute un undo potentiel ;
• chaque undo rajoute un redo potentiel.

La classe AbstractConversation utilise deux paramètres de type, C et S. En effet, chacune des trois implémentations concrètes de Conversation a besoin de connaître :

• le type de commandes exécutées (paramètre C), qui dérive de Command. Par exemple, CompensationConversation ne peut accepter que des CompensableCommand ;
• le type d'état conversationnel stocké (paramètre S). Dans la variante Memento, on ne mémorise pas les commandes, mais plutôt des snapshots de l'état du système (dans l'interface Conversation, il n'y a toujours que le paramètre C, car le type d'état conversationnel stocké est un détail d'implémentation du point de vue de l'utilisateur de l'API Conversation).

La classe AbstractConversation se présente ainsi :

/**
*  @param <C> Type of executed commands
* @param <S> Type of stored state (commands or mementos)
*/
public abstract class AbstractConversation<C extends Command, S> implements Conversation<C> {
    protected final Stack<S> undos, redos;
 
    public AbstractConversation() {
        this.undos= new Stack<S>();
        this.redos= new Stack<S>();
    }
}
AbstractConversation utilise la classe Stack (classe interne au framework):
 
public class Stack<T> {
 
    //Delegate to avoid exposing too many Deque methods
    private final Deque<T> stack = new LinkedList<>();
 
    /**
     * @return null if stack is empty
     */
    public T pop() {
        return stack.pollLast(); //Not using pop since it throws NoSuchElementException if the deque is empty
    }
 
    public void push(T cmd) {
        stack.addLast(cmd);
    }
 
    public void clear() {
        stack.clear();
    }
 
    public void forEachFifo(Consumer<? super T> action) {
        stack.stream().forEachOrdered(action);
    }
}

Stack délègue à une Deque (double-ended queue) l'implémentation de la stack ; en effet, il existe une classe java.util.Stack mais elle est obsolète, comme Vector. Déléguer à LinkedList plutôt que l'étendre présente deux avantages :

• évite la pollution d'API : Stack n'expose que les méthodes utiles pour notre framework ;
• liberté de nommage : dans Deque, push() et pop() n'ont pas la sémantique souhaitée (pop() : exception si vide), donc on utilise pollLast()/addLast(). Mais push et pop sont plus compréhensibles, donc ce sont ces noms-là qu'on expose à notre framework.

Enfin, précisons que forEachFifo() est utilisé par la variation Replay. FIFO signifie first-in first-out, donc un parcours dans l'ordre d'insertion.

L'infrastructure étant en place, regardons la première variation qui est la plus naturelle. Une action compensatoire d'une action A consiste à effectuer l'action inverse -A. Par exemple, l'action compensatoire d'un débit erroné de x EUR est un crédit de x EUR.

Dans le pattern Command, ceci se traduit par une commande compensable :

public interface CompensableCommand extends Command {
  void compensate();
}

On a vu dans le paragraphe « Découplage temporel : l'undo » que la conversation pouvait être identifiée à l'acteur Invocator du pattern Command du GOF. CompensationConversation est l'Invocator spécialisé pour les commandes compensables :

public class CompensationConversation extends AbstractConversation<CompensableCommand, CompensableCommand> {
 
    @Override public void exec(CompensableCommand todo) {
        todo.execute();
        undos.push(todo);
        redos.clear();
    }
 
    @Override public void undo() {
        CompensableCommand latestCmd = undos.pop();
        if(latestCmd==null) return;
        latestCmd.compensate();
        redos.push(latestCmd);
    }
 
    @Override public void redo() {
        CompensableCommand latestCmd = redos.pop();
        if(latestCmd==null) return;
        latestCmd.execute();
        undos.push(latestCmd);
    }
}

Dans la variation Compensation, les deux types parameters sont identiques (S=C=CompensableCommand dans AbstractConversation<C,S>), puisque l'état mémorisé est constitué de commandes. En effet, la compensation utilise les commandes déjà exécutées pour les compenser (undo) ou les exécuter de nouveau (redo).

À la fin d'exec(), on vide la stack de redo : les commandes annulées qui précèdent l'exécution d'une commande sont complètement effacées de la mémoire. La raison de ce choix est de se conformer aux conventions de toutes les IHM offrant un undo/redo (principe de moindre surprise).

public class TypeString implements CompensableCommand {
    @Override public void compensate() {
        display.unappend();
    }
}

Il est parfois difficile de trouver une action compensatrice. Dans ce cas, si on a invoqué N commandes, une implémentation alternative de l'undo est de réinitialiser l'état à zéro, puis de rejouer les N-1 premières commandes. Le redo consiste ensuite à rejouer la Nième commande.

Contrairement à la variation Compensation, puisque la variation Replay se repose uniquement sur l'exécution des commandes dans leur sens normal, ReplayConversation n'a pas besoin d'un type particulier de commandes : S=C=Command dans AbstractConversation<C,S>). Par contre, elle a besoin d'une instance de commande capable de remettre l'état à zéro :

public class ReplayConversation extends AbstractConversation<Command, Command> {
    private final Command reset;
 
    public ReplayConversation(Command reset) {
        this.reset = reset;
    }
 
    @Override public void exec(Command todo) {
        todo.execute();
        undos.push(todo);
        redos.clear();
    }
 
    @Override public void undo() {
        Command latestCmd = undos.pop() ;
        if(latestCmd==null) return;
        redos.push(latestCmd);
        reset.execute();
        undos.forEachFifo(cmd->cmd.execute());
    }
 
    @Override public void redo() {
        Command latestCmd = redos.pop() ;
        if(latestCmd==null) return;
        latestCmd.execute();
        undos.push(latestCmd);
    }
}

La réinitialisation de l'état utilise une commande spécifique au type d'état modifié par les commandes. Dans le cas de la commande Typing (saisie) qui modifie un Display (affichage), on peut simplement effacer complètement l'affichage :

public class CommandUndoTest_Replay_Typing_Test extends CommandUndoTest_Typing<Command> {
    @Override protected Conversation<Command> newConversation() {
        return new ReplayConversation(()->{
            display.clear();
        });
    }
}

Le lambda qui est passé au constructeur de ReplayConversation correspond au champ ReplayConversation.reset. Il vide l'affichage.

Plutôt que de mémoriser les commandes, on peut aussi implémenter l'undo en mémorisant leur effet, plus précisément l'état du système avant et après chaque exécution.

Cela évoque un autre pattern du GOF, le Memento :

L'Originator instancie un Memento en passant à son constructeur un snapshot de l'état du système. Le CareTaker est chargé de connaître le Memento, afin de pouvoir demander, ultérieurement, la restauration de l'état capturé.

Le Memento doit être capable de restaurer un état capturé antérieurement, d'où l'exigence d'immutabilité. On ne veut pas voir les changements de l'état du système postérieurs au snapshot, il faut donc utiliser des techniques comme la copie défensive. Comme Memento est une interface, on précise cette exigence dans le contrat sous forme de Javadoc :

/**
* Implementations must be immutable (the memento must capture a snapshot)
*/
@FunctionalInterface
public interface Memento {
  void restore();
}

Chaque type de commande peut modifier un type d'état différent, pour lequel la façon de capturer un Memento sera différente. Par exemple, la capture d'un état persisté en BDD sera très différente de la capture de l'état d'un logiciel de dessin. Le plus simple est donc de spécialiser Command en MementoableCommand, pour que les implémentations de MementoableCommand réalisent à la fois la modification et la capture de cet état, suivant les spécificités de ce dernier :

public interface MementoableCommand extends Command {
    Memento takeSnapshot();
}

Dans la variation Memento, les deux types parameters ne sont pas identiques (C=MementoableCommand, S=BeforeAfter dans AbstractConversation<C,S>), puisque l'état mémorisé est constitué de captures successives de l'état et non de commandes. Petite subtilité : pour implémenter le redo, on a besoin de capturer l'état avant ET après exécution de la commande:

public class MementoConversation extends AbstractConversation<MementoableCommand, BeforeAfter> {
 
    @Override public void exec(MementoableCommand todo) {
        Memento before = todo.takeSnapshot();
        todo.execute();
        Memento after = todo.takeSnapshot();
 
        undos.push(new BeforeAfter(before, after));
        redos.clear();
    }
 
    @Override public void undo() {
        BeforeAfter latestMemento = undos.pop();
        if(latestMemento==null) return;
        Memento latestBefore = latestMemento.before;
        latestBefore.restore();
        redos.push(latestMemento);
    }
 
    @Override public void redo() {
        BeforeAfter latestMemento = redos.pop();
        if(latestMemento==null) return;
        Memento latestAfter = latestMemento.after;
        latestAfter.restore();
        undos.push(latestMemento);
    }
}
 
//@Immutable
class BeforeAfter {
 
    final Memento before, after;
 
    /**
    * @param before must be immutable
    * @param after  must be immutable
    */
    public BeforeAfter(Memento before, Memento after) {
        this.before = before;
        this.after = after;
    }
}

Dans cette variation, la commande est donc l'Originator du pattern Memento du GOF (l'acteur qui déclenche le snapshot), et la conversation en est le Caretaker (l'acteur qui mémorise les Mementos). Les rôles du pattern Memento sont indiqués sous forme de stéréotypes UML quand ils diffèrent des types propres à la variation Memento Undo Command).

Facteurs favorables :

• la Compensation est la plus naturelle (symétrie entre la commande et son inverse) ;
• cette variation est idéale quand il existe une commande inverse naturelle dont le nom est évident: le contraire d'une création est une suppression (et vice-versa), le contraire d'un débit est un crédit (vice-versa) ;
• ceci fonctionne bien quand la sémantique de la commande est très précise et a peu de degrés de liberté ;
• du point de vue de l'utilisation mémoire, une pile de commandes est souvent plus légère que des snapshots de l'état complet (VS Memento) ;
• du point de vue de la performance, elle évite de rejouer une séquence de commandes (VS Replay) ou de repositionner un gros état (VS Memento).

Facteurs défavorables :

• Les commandes non compensables ne peuvent utiliser cette variation. Par exemple, l'écriture dans un log ne peut être compensée.
• Une commande très générale comme un "update" est difficile à compenser: il faut mémoriser tous les champs mis à jour, utiliser l'introspection...
• Le nombre et la variété de commandes concrètes : pour choisir cette variation, il faut être sûr à l'avance qu'on pourra compenser toutes les commandes (même celles qui peuvent être introduites par une évolution future de l'application).
• Il est difficile de compenser les modifications de relations entre objets d'un graphe, surtout si ces relations sont bidirectionnelles.

Remarques :

• La méthode Domain Driven Design préconise de toute façon d'éviter les commandes très générales comme l'update générique (POST), et de modéliser les changements d'état par des transitions déclenchées par des événements (PUT /event {eventData}). Les transitions ont une sémantique plus précise et sont plus faciles à compenser.
• Quand tous les changements de l'état applicatif sont stockés comme une séquence d'événements (Event Sourcing), doit-on forcément utiliser les actions compensatoires ? Pas forcément, tant que l'événement qu'on veut annuler n'est pas définitif (tant qu'il fait partie d'une conversation pas encore commitée).

Facteurs favorables :

• quand les commandes individuelles ne sont pas (ou difficilement) compensables, ou que le système présente une hystérésis ;
• quand l'API du Receptor donne un moyen direct de réaliser des snapshots ;
• quand on peut modifier ou wrapper un Receptor existant pour se ramener au cas précédent.

Facteurs défavorables :

• quand le Receptor est write-only ou qu'il est difficile de capturer son état ;
• lorsque les contraintes sur la mémoire sont trop importantes.

Facteurs favorables :

• Quand toute autre action a échoué : cette variation est celle qui fait le moins d'hypothèses sur le Receptor : il suffit qu'il puisse être remis à zéro.
• Si on ne peut pas utiliser la variation Compensation, le Replay utilise dans la plupart des cas moins de mémoire, car les commandes prennent moins de place que les Mementos.

Facteurs défavorables :

• Pas très élégant quand on peut faire autrement ;
• Ne doit pas être rédhibitoire du point de vue des performances.

Dans notre exemple, les piles d'undo/redo ont une profondeur illimitée. Cela peut provoquer une OutOfMemoryError, et de toute façon l'utilisateur ne se rappelle plus les opérations trop anciennes. Le principe GRASP (attribution de responsabilités) expert en information nous suggère de placer la gestion de cette limitation dans le type qui a la connaissance de la profondeur actuelle de la pile, donc Stack.

À partir du pattern Command, il est très simple de définir des macros : il suffit d'utiliser en plus le pattern Composite (les rôles du pattern Composite sont indiqués sous forme de stéréotypes UML quand ils diffèrent des types propres à la variation Command Macro) :

Les macros sont simples à implémenter avec le pattern Command

public class Macro implements Command {
 
  private final List<Command> parts;
  public Macro(List<Command> parts) {
    this.parts = parts;
  }
 
  @Override public void execute() {
    this.parts.forEach(c -> c.execute());
  }
}