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