CKTIS / Java
Contratti di Java Flow: sottoscrizione, domanda e terminazione
Scopri come stabilire una sottoscrizione Flow in Java SE 21, ricevere elementi con domanda limitata e distinguere completamento normale, errore e annullamento.
Versione: Java SE 21
Sintassi
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();In Java SE 21 i tipi Flow appartengono al package java.util.concurrent. Flow.Publisher<T>.subscribe accetta un Flow.Subscriber<? super T>, cioè un sottoscrittore in grado di gestire T o un suo supertipo. Se la registrazione riesce, il publisher passa una nuova sottoscrizione a onSubscribe(Flow.Subscription) prima di qualsiasi altro callback per quella sottoscrizione. Passare null a subscribe causa il lancio di una NullPointerException. Una registrazione duplicata quando il sottoscrittore è già iscritto o respinta in base alle regole del publisher viene segnalata tramite onError con una IllegalStateException.
Il sottoscrittore salva il riferimento in onSubscribe e chiama request(long n) su di esso. Un n positivo si somma alla domanda residua, senza sostituirla. Ogni onNext(T item) consegna un elemento e consuma un’unità di domanda limitata. Chiamare request(1) dopo l’elaborazione di un elemento permette di riceverne uno alla volta. La domanda limita la consegna, non la capacità del buffer del publisher. Long.MAX_VALUE può essere trattato come domanda di fatto illimitata. Su una sottoscrizione attiva, n <= 0 produce un segnale onError con una IllegalArgumentException, che non viene lanciata in modo sincrono da request.
onComplete() segnala il completamento normale; onError(Throwable) segnala un errore irreversibile. I due segnali non consumano domanda di elementi. Si escludono a vicenda e nessun altro callback è invocato per quella sottoscrizione dopo uno dei due. I callback relativi alla stessa sottoscrizione rispettano la relazione happens-before, ma non devono necessariamente essere eseguiti sullo stesso thread. Non lasciare che le eccezioni si propaghino da questi metodi: il contratto non garantisce né il ripristino né una notifica separata tramite onError.
cancel() agisce soltanto sulla sottoscrizione interessata. La consegna viene interrotta per quanto possibile, ma non necessariamente all’istante: possono ancora arrivare segnali già in transito. L’annullamento non equivale al completamento normale; non attendere onComplete() o onError(Throwable) dopo la chiamata. L’esempio implementa un sottoscrittore e affida la gestione della sottoscrizione e la consegna al SubmissionPublisher della libreria.
Esempi
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);
}
}
}Risultato
COMPLETE onSubscribe onNext 10 onNext 20 onComplete INVALID onSubscribe onError IllegalArgumentException CANCEL onSubscribe onNext 10 cancel
In `COMPLETE`, il sottoscrittore chiede un elemento, ne chiede un altro dopo `10` e riceve `onComplete` dopo `20`. In `INVALID`, `request(0)` produce `onError` senza che venga pubblicato alcun elemento. In `CANCEL`, il sottoscrittore annulla dopo l’unico elemento pubblicato. Il programma attende l’evento previsto anziché fare una pausa fissa: `close()` non attende la fine di tutti i callback dei sottoscrittori e il caso di annullamento non attende un segnale terminale.
Lezioni correlate
- Java · Lezione 44 · Avanzato · Versione: 2