CKTIS / Java
Kontrakty Java Flow: odber, dopyt a ukončenie
Zisti, ako v Java SE 21 nadviazať odber Flow, prijímať prvky s obmedzeným dopytom a rozlišovať riadne dokončenie, chybu a zrušenie odberu.
Verzia: Java SE 21
Syntax
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();V Java SE 21 patria typy Flow do balíka java.util.concurrent. Metóda Flow.Publisher<T>.subscribe prijíma Flow.Subscriber<? super T>, teda odberateľa, ktorý dokáže spracovať T alebo jeho nadtyp. Pri úspešnej registrácii vydavateľ odovzdá nový odber do onSubscribe(Flow.Subscription) pred každým ďalším volaním pre tento odber. Odovzdanie null metóde subscribe vyvolá NullPointerException. Duplicitnú registráciu už prihláseného odberateľa alebo odmietnutie podľa pravidiel vydavateľa oznámi onError s IllegalStateException.
Odberateľ si v onSubscribe uloží referenciu a cez ňu zavolá request(long n). Kladné n sa pripočíta k neuspokojenému dopytu, nenahradí ho. Každé onNext(T item) doručí jeden prvok a spotrebuje jednu jednotku obmedzeného dopytu. Volaním request(1) po spracovaní prvku možno prvky prijímať po jednom. Dopyt obmedzuje doručovanie, nie kapacitu vyrovnávacej pamäte vydavateľa. Long.MAX_VALUE možno považovať za prakticky neobmedzený dopyt. V aktívnom odbere vedie n <= 0 k signálu onError s IllegalArgumentException; request túto výnimku nevyvolá synchrónne.
onComplete() oznamuje riadne dokončenie, onError(Throwable) neodstrániteľné zlyhanie. Tieto signály nespotrebúvajú dopyt po prvkoch. Navzájom sa vylučujú a po ktoromkoľvek z nich už pre daný odber nenasleduje ďalšie volanie. Volania metód odberateľa pri jednom odbere sú usporiadané vzťahom happens-before, ale nemusia prebiehať v tom istom vlákne. Nedovoľ, aby z týchto metód unikli výnimky: kontrakt nezaručuje zotavenie ani samostatné oznámenie cez onError.
cancel() sa týka len daného odberu. Doručovanie zastaví, len čo je to možné, nie však nevyhnutne okamžite: signály, ktoré už boli na ceste, môžu ešte doraziť. Zrušenie nie je riadne dokončenie; po ňom nečakaj na onComplete() ani na onError(Throwable). Príklad implementuje odberateľa a správu odberu aj doručovanie ponecháva knižničnej triede SubmissionPublisher.
Príklady
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);
}
}
}Výsledok
COMPLETE onSubscribe onNext 10 onNext 20 onComplete INVALID onSubscribe onError IllegalArgumentException CANCEL onSubscribe onNext 10 cancel
V režime `COMPLETE` si odberateľ vyžiada jeden prvok, po `10` si vyžiada ďalší a po `20` dostane `onComplete`. V režime `INVALID` vedie `request(0)` k `onError` bez publikovania prvkov. V režime `CANCEL` odberateľ zruší odber po jedinom publikovanom prvku. Program čaká na očakávanú udalosť namiesto pevnej pauzy: `close()` nečaká na dokončenie všetkých volaní metód odberateľov a pri zrušení program nečaká na koncový signál.
Súvisiace lekcie
- Java · Lekcia 44 · Pokročilá · Verzia: 2