KennisbankExamencentrum
NL · NLNederlands (Nederland)
Taal kiezen13

CKTIS / Java

Java Flow-contracten: abonnement, vraag en beëindiging

Leer hoe je in Java SE 21 een Flow-abonnement opzet, elementen met begrensde vraag ontvangt en normale voltooiing, fouten en annulering van elkaar onderscheidt.

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

In Java SE 21 staan de Flow-typen in java.util.concurrent. Flow.Publisher<T>.subscribe accepteert een Flow.Subscriber<? super T>: een abonnee die T of een supertype kan verwerken. Bij een geslaagde aanmelding geeft de uitgever een nieuw abonnement door aan onSubscribe(Flow.Subscription), vóór alle andere callbacks voor dat abonnement. subscribe gooit een NullPointerException als je null doorgeeft. Een dubbele aanmelding terwijl de abonnee al geabonneerd is, of een afwijzing op grond van de regels van de uitgever, wordt gemeld via onError met een IllegalStateException.

De abonnee bewaart de referentie in onSubscribe en roept daarop request(long n) aan. Een positieve n wordt bij de openstaande vraag opgeteld en vervangt die niet. Elke onNext(T item) levert één element en verbruikt één eenheid begrensde vraag. Roep na de verwerking van een element request(1) aan om elementen één voor één te ontvangen. De vraag begrenst de aflevering, niet de buffercapaciteit van de uitgever. Long.MAX_VALUE mag als praktisch onbegrensde vraag worden behandeld. Bij een actief abonnement leidt n <= 0 tot een onError-signaal met een IllegalArgumentException; request gooit die uitzondering niet synchroon.

onComplete() meldt normale voltooiing; onError(Throwable) meldt een onherstelbare fout. Deze signalen verbruiken geen vraag naar elementen. Ze sluiten elkaar uit en na een van beide volgen geen callbacks meer voor dat abonnement. De callbacks voor één abonnement zijn geordend volgens de happens-before-relatie, maar hoeven niet op dezelfde thread te draaien. Laat geen uitzonderingen uit deze methoden ontsnappen: het contract garandeert geen herstel of aparte melding via onError.

cancel() heeft alleen gevolgen voor dat abonnement. De aflevering stopt voor zover dat mogelijk is, niet noodzakelijk meteen: signalen die al onderweg zijn, kunnen nog aankomen. Annuleren is geen normale voltooiing; wacht daarna niet op onComplete() of onError(Throwable). Het voorbeeld implementeert een abonnee en laat het beheer van het abonnement en de aflevering over aan SubmissionPublisher uit de bibliotheek.

Voorbeelden

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

Resultaat

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

In `COMPLETE` vraagt de abonnee één element, vraagt na `10` nog een element en ontvangt na `20` het signaal `onComplete`. In `INVALID` leidt `request(0)` tot `onError` zonder dat er elementen worden gepubliceerd. In `CANCEL` annuleert de abonnee na het enige gepubliceerde element. Het programma wacht op de verwachte gebeurtenis in plaats van een vaste pauze te nemen: `close()` wacht niet tot alle callbacks van abonnees klaar zijn, en bij annulering wacht het programma niet op een eindsignaal.

Gerelateerde lessen

  • Java · Les 44 · Gevorderd · Versie: 2

Bronnen