Znalostná bázaCentrum skúšok
SKSlovenčina
Vybrať jazyk13

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

Zdroje