Znalostní bázeCentrum zkoušek
CSČeština
Vybrat jazyk13

CKTIS / Java

Kontrakty Java Flow: odběr, poptávka a ukončení

Zjisti, jak v Java SE 21 navázat odběr Flow, přijímat prvky s omezenou poptávkou a rozlišovat řádné dokončení, chybu a zrušení odběru.

Verze: 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();

V Java SE 21 jsou typy Flow součástí balíčku java.util.concurrent. Metoda Flow.Publisher<T>.subscribe přijímá Flow.Subscriber<? super T>, tedy odběratele schopného zpracovat T nebo některý jeho nadtyp. Při úspěšné registraci vydavatel předá nový odběr do onSubscribe(Flow.Subscription) dříve, než pro tento odběr zavolá jinou metodu odběratele. Předání null metodě subscribe vyvolá NullPointerException. Duplicitní registraci již přihlášeného odběratele nebo odmítnutí podle pravidel vydavatele oznámí onError s IllegalStateException.

Odběratel si v onSubscribe uloží odkaz a volá na něm request(long n). Kladné n se přičte k dosud neuspokojené poptávce, nenahradí ji. Každé onNext(T item) doručí jeden prvek a spotřebuje jednu jednotku omezené poptávky. Voláním request(1) po zpracování prvku lze prvky přijímat po jednom. Poptávka omezuje doručování, ne kapacitu vyrovnávací paměti vydavatele. Long.MAX_VALUE lze považovat za prakticky neomezenou poptávku. V aktivním odběru vede n <= 0 k signálu onError s IllegalArgumentException; request tuto výjimku nevyvolá synchronně.

onComplete() oznamuje řádné dokončení, onError(Throwable) selhání, ze kterého se nelze zotavit. Tyto signály nespotřebovávají poptávku po prvcích. Vzájemně se vylučují a po kterémkoli z nich už pro tento odběr nenásleduje žádné volání. Volání metod odběratele pro jeden odběr jsou uspořádána vztahem happens-before, ale nemusejí běžet ve stejném vlákně. Nenechávej z těchto metod unikat výjimky: kontrakt nezaručuje zotavení ani samostatné oznámení přes onError.

cancel() se týká pouze daného odběru. Doručování zastaví, jakmile je to možné, nikoli nutně okamžitě: signály, které už byly na cestě, mohou ještě dorazit. Zrušení není řádné dokončení; po něm nečekej na onComplete() ani onError(Throwable). Příklad implementuje odběratele a správu odběru a doručování ponechává knihovní třídě SubmissionPublisher.

Pří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ýsledek

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

V režimu `COMPLETE` si odběratel vyžádá jeden prvek, po `10` si vyžádá další a po `20` obdrží `onComplete`. V režimu `INVALID` vede `request(0)` k `onError`, aniž se publikuje jediný prvek. V režimu `CANCEL` odběratel zruší odběr po jediném publikovaném prvku. Program čeká na očekávanou událost místo pevné prodlevy: `close()` nečeká na dokončení všech volání metod odběratelů a při zrušení se nečeká na koncový signál.

Související lekce

  • Java · Lekce 44 · Pokročilá · Verze: 2

Zdroje