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