Base de connaissancesCentre d’examen
FRFrançais
Choisir la langue13

CKTIS / Java

Contrats de Java Flow : abonnement, demande et fin

Apprenez à établir un abonnement Flow sous Java SE 21, à borner la demande d’éléments et à distinguer la fin normale, l’échec et l’annulation.

Version : Java SE 21

Syntaxe

import java.util.concurrent.Flow;

// Flow.Publisher<T>
void subscribe(Flow.Subscriber<? super T> subscriber);

// Flow.Subscriber<T>
void onSubscribe(Flow.Subscription subscription);
void onNext(T item);
void onError(Throwable error);
void onComplete();

// Flow.Subscription
void request(long n);
void cancel();

Dans Java SE 21, les types Flow font partie du paquet java.util.concurrent. Flow.Publisher<T>.subscribe accepte un Flow.Subscriber<? super T>, capable de traiter T ou un supertype. Si l’inscription réussit, le producteur transmet un nouvel abonnement à onSubscribe(Flow.Subscription) avant tout autre rappel pour cet abonnement. Passer null à subscribe lève une NullPointerException. Une inscription en double alors que l’abonné est déjà inscrit, ou un refus lié aux règles du producteur, est signalé par onError avec une IllegalStateException.

L’abonné conserve la référence dans onSubscribe et appelle dessus request(long n). Un n positif s’ajoute à la demande en attente sans la remplacer. Chaque onNext(T item) livre un élément et consomme une unité de demande bornée. Appeler request(1) après le traitement d’un élément permet de les recevoir un par un. La demande limite la livraison, pas la capacité du tampon du producteur. Long.MAX_VALUE peut être considéré comme une demande pratiquement illimitée. Sur un abonnement actif, n <= 0 entraîne un signal onError avec une IllegalArgumentException, et non une exception levée de façon synchrone par request.

onComplete() indique une fin normale, tandis que onError(Throwable) signale un échec irrécupérable. Ces signaux ne consomment pas de demande d’éléments. Ils s’excluent mutuellement et aucun rappel ne suit l’un ou l’autre pour cet abonnement. Les rappels d’un même abonnement sont ordonnés par la relation happens-before, mais ne s’exécutent pas nécessairement sur le même thread. Ne laissez pas d’exception sortir de ces méthodes : le contrat ne garantit ni reprise ni notification distincte par onError.

cancel() ne concerne que l’abonnement visé. La livraison s’arrête dans la mesure du possible, pas forcément tout de suite : des signaux déjà en cours d’acheminement peuvent encore arriver. Une annulation n’est pas une fin normale ; n’attendez ni onComplete() ni onError(Throwable) après cet appel. L’exemple implémente un abonné et confie la gestion de l’abonnement et la livraison au SubmissionPublisher de la bibliothèque.

Exemples

import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.Flow;
import java.util.concurrent.SubmissionPublisher;
import java.util.concurrent.TimeUnit;

public class FlowContractsDemo {
    private enum Mode { COMPLETE, INVALID, CANCEL }

    public static void main(String[] args) throws Exception {
        try (ExecutorService executor = Executors.newSingleThreadExecutor()) {
            for (Mode mode : Mode.values()) {
                run(executor, mode);
            }
        }
    }

    private static void run(ExecutorService executor, Mode mode) throws Exception {
        System.out.println(mode);
        var done = new CompletableFuture<Void>();
        try (var publisher = new SubmissionPublisher<Integer>(executor, 8)) {
            publisher.subscribe(new Flow.Subscriber<Integer>() {
                private Flow.Subscription subscription;

                @Override
                public void onSubscribe(Flow.Subscription subscription) {
                    this.subscription = subscription;
                    System.out.println("onSubscribe");
                    subscription.request(mode == Mode.INVALID ? 0L : 1L);
                }

                @Override
                public void onNext(Integer item) {
                    System.out.println("onNext " + item);
                    if (mode == Mode.CANCEL) {
                        subscription.cancel();
                        System.out.println("cancel");
                        done.complete(null);
                    } else if (mode == Mode.COMPLETE && item == 10) {
                        subscription.request(1L);
                    }
                }

                @Override
                public void onError(Throwable error) {
                    if (mode == Mode.INVALID && error instanceof IllegalArgumentException) {
                        System.out.println("onError IllegalArgumentException");
                        done.complete(null);
                    } else {
                        done.completeExceptionally(error);
                    }
                }

                @Override
                public void onComplete() {
                    if (mode == Mode.COMPLETE) {
                        System.out.println("onComplete");
                        done.complete(null);
                    } else {
                        done.completeExceptionally(new IllegalStateException("Unexpected completion"));
                    }
                }
            });

            if (mode != Mode.INVALID) {
                publisher.submit(10);
            }
            if (mode == Mode.COMPLETE) {
                publisher.submit(20);
                publisher.close();
            }
            done.get(10, TimeUnit.SECONDS);
        }
    }
}

Résultat

COMPLETE
onSubscribe
onNext 10
onNext 20
onComplete
INVALID
onSubscribe
onError IllegalArgumentException
CANCEL
onSubscribe
onNext 10
cancel

Dans `COMPLETE`, l’abonné demande un élément, en demande un autre après `10` et reçoit `onComplete` après `20`. Dans `INVALID`, `request(0)` déclenche `onError` sans publication d’éléments. Dans `CANCEL`, l’abonné annule après l’unique élément publié. Le programme attend l’événement prévu plutôt qu’une durée fixe : `close()` n’attend pas la fin de tous les rappels aux abonnés, et le cas d’annulation n’attend pas de signal terminal.

Leçons associées

  • Java · Leçon 44 · Avancé · Version : 2

Sources