HOWTO · Java

Idempotent en Java

Ce didacticiel illustre l'utilisation d'Idempotent en Java.

Sur cette page

Une opération est idempotente lorsque son application une ou plusieurs fois produit le même effet attendu sur l’état concerné. Les réponses ou les valeurs de retour peuvent différer : seul l’état obtenu compte. Cette propriété est utile lorsqu’un client réessaie une requête après un délai d’attente, car il peut ignorer si la première tentative a atteint le serveur.

Ce que signifie l’idempotence en Java

Prenons une opération qui définit le statut d’un utilisateur sur "active". Définir ce statut une ou plusieurs fois sur cette valeur le laisse actif : le changement d’état est donc idempotent. À l’inverse, incrémenter un compteur modifie sa valeur à chaque fois ; répéter cette opération produit donc des effets supplémentaires.

La distinction porte sur l’effet de l’opération, et non sur le fait que le code s’exécute de nouveau ou renvoie le même message. Une méthode qui définit une valeur peut tout de même déclencher des effets secondaires distincts, comme l’envoi d’un courriel à chaque appel ; ces effets doivent aussi être pris en compte dans l’évaluation de l’opération.

Implémenter une opération idempotente en Java

Réaffecter true est en soi idempotent : après le premier appel, l’abonnement est actif, et chaque appel suivant le laisse actif. Le programme complet ci-dessous illustre ce comportement.

Exécutez ce programme complet en Java. Les libellés du programme et de sa sortie restent en anglais :

public class IdempotentActivation {
    private boolean active;

    public void activate() {
        active = true;
    }

    public boolean isActive() {
        return active;
    }

    public static void main(String[] args) {
        IdempotentActivation subscription = new IdempotentActivation();
        subscription.activate();
        subscription.activate();
        System.out.println("Active: " + subscription.isActive());
    }
}

Le programme appelle activate() deux fois avant d’afficher l’état de l’abonnement. Voici sa sortie ; le libellé affiché reste en anglais :

Active: true

Dans un service, le changement d’état doit généralement avoir lieu dans une transaction de base de données. Un identifiant de requête peut aussi éviter les traitements en double, mais l’identifiant et le résultat doivent être enregistrés de façon atomique avec le changement. Un ensemble conservé uniquement en mémoire est perdu au redémarrage et ne peut pas coordonner plusieurs instances du service.

Tester les appels répétés et leurs effets

Vérifiez cette propriété en appliquant la même opération plusieurs fois et en contrôlant l’état après chaque appel. Pour le programme ci-dessus, isActive() doit renvoyer true après le premier appel et rester à true après le second. Pour tester un service réel, examinez aussi l’état persistant et les éventuels effets secondaires, comme les messages émis ou les frais facturés : constater la même valeur affichée ne prouve pas que ces effets ont été répétés sans risque.

Un test utile compare l’état après un appel à celui obtenu après plusieurs appels identiques. Si le deuxième appel modifie de nouveau l’état visé, l’opération n’est pas idempotente. S’il laisse cet état tel qu’attendu, les tentatives répétées peuvent être plus sûres, même si la concurrence et le comportement des transactions nécessitent leurs propres vérifications.

L’idempotence des méthodes HTTP

L’idempotence en HTTP décrit l’effet attendu sur le serveur de requêtes identiques répétées. Elle n’exige pas que chaque réponse ait le même code d’état ou le même corps. Par exemple, un second DELETE peut renvoyer une réponse différente une fois la ressource supprimée, tout en produisant le même effet attendu.

Méthode Idempotente par définition ? Signification pratique
GET Oui Récupère une représentation ; ne devrait pas demander de changement d’état.
HEAD Oui Comme GET, mais renvoie les en-têtes sans le corps de la réponse.
OPTIONS Oui Indique les options de communication de la cible.
TRACE Oui Renvoie la requête telle qu’elle a été reçue, à des fins de diagnostic.
PUT Oui Crée ou remplace la représentation de la cible par l’état fourni.
DELETE Oui Demande la suppression de la cible ; répéter la requête produit le même effet attendu.
POST Non, en général Crée souvent une ressource ou déclenche une action ; une API peut ajouter un mécanisme de déduplication.
PATCH Pas nécessairement Applique une modification partielle ; la sûreté d’une répétition dépend de l’opération de modification.

Une API donnée peut définir des protections supplémentaires, mais les clients ne doivent se fier à la sémantique des méthodes que si le serveur la respecte. Une requête qui incrémente une valeur ne devient pas idempotente simplement parce qu’elle utilise PUT ou PATCH : chaque nouvelle tentative peut appliquer l’incrément une fois de plus.

Idées reçues et limites courantes

L’idempotence ne signifie pas qu’il ne se passe rien : le premier appel peut modifier l’état. Elle ne garantit pas non plus des réponses identiques, n’empêche pas les mises à jour concurrentes et ne rend pas atomique un processus en plusieurs étapes. Une opération peut être idempotente pour une ressource tout en répétant un effet secondaire sans rapport.

Pour concevoir une opération compatible avec les tentatives répétées, définissez quels états et effets secondaires constituent son résultat, puis rendez la mise à jour conditionnelle ou dédupliquez les requêtes à l’aide d’un stockage persistant. Vérifiez à la fois l’état obtenu et les effets secondaires concernés. Ces contrôles clarifient la garantie visée sans supposer que tout appel répété d’une méthode est sans risque.