CKTIS / Java
Java-Flow-Verträge: Abonnement, Bedarf und Beendigung
Lerne, wie du in Java SE 21 ein Flow-Abonnement einrichtest, Elemente mit begrenztem Bedarf empfängst und regulären Abschluss, Fehler und Abbruch unterscheidest.
Version: 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 liegen die Flow-Typen im Paket java.util.concurrent. Flow.Publisher<T>.subscribe akzeptiert einen Flow.Subscriber<? super T>, der T oder einen Obertyp verarbeiten kann. Bei erfolgreicher Anmeldung übergibt der Publisher mit onSubscribe(Flow.Subscription) ein neues Abonnement, bevor weitere Rückrufe für dieses Abonnement erfolgen. subscribe wirft bei null eine NullPointerException. Ist der Subscriber bereits angemeldet oder lehnt der Publisher die Anmeldung aufgrund seiner Regeln ab, meldet onError eine IllegalStateException.
Der Subscriber speichert die Referenz in onSubscribe und ruft darauf request(long n) auf. Ein positives n erhöht den noch offenen Bedarf, statt ihn zu ersetzen. Jedes onNext(T item) liefert ein Element und verbraucht eine Einheit des begrenzten Bedarfs. Wer nach der Verarbeitung eines Elements request(1) aufruft, kann Elemente einzeln empfangen. Der Bedarf begrenzt die Auslieferung, nicht die Pufferkapazität des Publishers. Long.MAX_VALUE darf als praktisch unbegrenzt gelten. Bei einem aktiven Abonnement führt n <= 0 zu onError mit einer IllegalArgumentException; request wirft sie nicht synchron.
onComplete() meldet den regulären Abschluss, onError(Throwable) einen nicht behebbaren Fehler. Beide verbrauchen keinen Bedarf. Sie schließen einander aus, und nach einem dieser Signale folgen keine weiteren Rückrufe für das Abonnement. Die Rückrufe für ein Abonnement sind durch eine happens-before-Beziehung geordnet, müssen aber nicht im selben Thread laufen. Lass keine Ausnahmen aus diesen Methoden entweichen: Der Vertrag garantiert weder eine Wiederherstellung noch eine gesonderte Meldung per onError.
cancel() betrifft nur das jeweilige Abonnement. Die Auslieferung wird nach Möglichkeit gestoppt, aber nicht zwingend sofort: Bereits unterwegs befindliche Signale können noch eintreffen. Ein Abbruch ist kein regulärer Abschluss; warte danach weder auf onComplete() noch auf onError(Throwable). Das Beispiel implementiert einen Subscriber und überlässt die Verwaltung des Abonnements und die Auslieferung dem SubmissionPublisher aus der Bibliothek.
Beispiele
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);
}
}
}Ergebnis
COMPLETE onSubscribe onNext 10 onNext 20 onComplete INVALID onSubscribe onError IllegalArgumentException CANCEL onSubscribe onNext 10 cancel
In `COMPLETE` fordert der Subscriber ein Element an, nach `10` ein weiteres, und erhält nach `20` den Rückruf `onComplete`. In `INVALID` löst `request(0)` ohne veröffentlichte Elemente `onError` aus. In `CANCEL` beendet der Subscriber das Abonnement nach dem einzigen veröffentlichten Element. Das Programm wartet auf das erwartete Ereignis statt auf eine feste Pause: `close()` wartet nicht auf den Abschluss aller Subscriber-Rückrufe, und der Abbruchfall wartet nicht auf ein terminales Signal.
Zugehörige Lektionen
- Java · Lektion 44 · Fortgeschritten · Version: 2