Baza wiedzyCentrum egzaminacyjne
PLPolski
Wybierz język13

CKTIS / Java

Kontrakty Java Flow: subskrypcja, żądanie elementów i zakończenie

Dowiedz się, jak w Java SE 21 nawiązać subskrypcję Flow, odbierać elementy w ograniczonych porcjach oraz odróżniać normalne zakończenie, błąd i anulowanie.

Wersja: Java SE 21

Składnia

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

W Java SE 21 typy Flow należą do pakietu java.util.concurrent. Metoda Flow.Publisher<T>.subscribe przyjmuje Flow.Subscriber<? super T>, czyli subskrybenta obsługującego T lub jego nadtyp. Po udanej rejestracji wydawca przekazuje nową subskrypcję w onSubscribe(Flow.Subscription), przed innymi wywołaniami dla tej subskrypcji. Przekazanie null do subscribe powoduje zgłoszenie NullPointerException; ponowna rejestracja już zapisanego subskrybenta lub odrzucenie rejestracji zgodnie z regułami wydawcy są sygnalizowane przez onError z IllegalStateException.

Subskrybent zapisuje uchwyt w onSubscribe i wywołuje na nim request(long n). Dodatnie n zwiększa liczbę elementów, na które subskrybent jeszcze czeka; nie zastępuje poprzedniego żądania. Każde onNext(T item) dostarcza jeden element i zużywa jedną jednostkę ograniczonego zapotrzebowania. request(1) po przetworzeniu elementu pozwala odbierać po jednym naraz. Zapotrzebowanie ogranicza dostarczanie, a nie pojemność bufora wydawcy. Long.MAX_VALUE może oznaczać praktycznie nieograniczone zapotrzebowanie. W aktywnej subskrypcji n <= 0 skutkuje sygnałem onError z IllegalArgumentException, a nie synchronicznym zgłoszeniem tego wyjątku przez request.

onComplete() oznacza normalny koniec, a onError(Throwable) — błąd nie do naprawienia. Sygnały te nie zużywają zapotrzebowania na elementy. Wykluczają się, a po jednym z nich nie ma kolejnych wywołań dla tej subskrypcji. Wywołania subskrybenta dla danej subskrypcji są uporządkowane relacją happens-before, ale nie muszą odbywać się w tym samym wątku. Nie pozwalaj wyjątkom wydostać się z tych metod: kontrakt nie gwarantuje odtworzenia poprawnego działania ani osobnego onError.

cancel() dotyczy tylko danej subskrypcji. Zatrzymuje dostarczanie możliwie szybko, ale nie gwarantuje natychmiastowego odcięcia: mogą jeszcze nadejść sygnały będące w toku. Anulowanie nie jest normalnym zakończeniem; nie czekaj po nim na onComplete() ani onError(Throwable). Przykład implementuje subskrybenta, a obsługę subskrypcji i dostarczania pozostawia bibliotecznemu SubmissionPublisher.

Przykłady

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);
        }
    }
}

Wynik

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

W `COMPLETE` subskrybent żąda jednego elementu, po `10` żąda jeszcze jednego i po `20` odbiera `onComplete`. W `INVALID` wywołanie `request(0)` daje `onError` bez publikowania elementów. W `CANCEL` subskrybent anuluje subskrypcję po jedynym opublikowanym elemencie. Program czeka na oczekiwane zdarzenie, a nie na upływ stałej przerwy: `close()` nie czeka na zakończenie wszystkich wywołań odbiorców, a przypadek anulowania nie czeka na sygnał końcowy.

Powiązane lekcje

  • Java · Lekcja 44 · Zaawansowany · Wersja: 2

Źródła