Base de conocimientosCentro de exámenes
ESEspañol
Elegir idioma13

CKTIS / Java

Contratos de Java Flow: suscripción, demanda y finalización

Aprende a establecer una suscripción Flow en Java SE 21, recibir elementos con demanda acotada y distinguir la finalización normal, el error y la cancelación.

Versión: Java SE 21

Sintaxis

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

En Java SE 21, los tipos Flow pertenecen a java.util.concurrent. Flow.Publisher<T>.subscribe acepta un Flow.Subscriber<? super T>, es decir, un suscriptor que puede procesar T o un supertipo. Si el registro tiene éxito, el publicador entrega una nueva suscripción a onSubscribe(Flow.Subscription) antes de cualquier otra llamada al suscriptor para esa suscripción. Pasar null a subscribe lanza NullPointerException. Un registro duplicado mientras el suscriptor ya está inscrito o un registro rechazado por las reglas del publicador se comunica mediante onError con IllegalStateException.

El suscriptor guarda la referencia en onSubscribe y llama a request(long n) sobre ella. Un n positivo se suma a la demanda pendiente, no la sustituye. Cada onNext(T item) entrega un elemento y consume una unidad de demanda acotada. Llamar a request(1) tras procesar un elemento permite recibirlos de uno en uno. La demanda limita la entrega, no la capacidad del búfer del publicador. Long.MAX_VALUE puede interpretarse como demanda prácticamente ilimitada. En una suscripción activa, n <= 0 provoca una señal onError con IllegalArgumentException, no una excepción lanzada de forma síncrona por request.

onComplete() indica la finalización normal; onError(Throwable) indica un error irrecuperable. No consumen demanda de elementos. Son mutuamente excluyentes y, después de cualquiera de ellas, no hay más llamadas al suscriptor para esa suscripción. Las llamadas de una misma suscripción se ordenan según la relación happens-before, pero no tienen por qué ejecutarse en el mismo hilo. No dejes que se propaguen excepciones desde estas llamadas: el contrato no garantiza la recuperación ni una notificación separada mediante onError.

cancel() afecta solo a esa suscripción. La entrega se detiene en la medida de lo posible, pero no necesariamente de inmediato: aún pueden llegar señales que ya estuvieran en curso. Cancelar no equivale a finalizar normalmente; después no esperes onComplete() ni onError(Throwable). El ejemplo implementa un suscriptor y deja la gestión de la suscripción y la entrega al SubmissionPublisher de la biblioteca.

Ejemplos

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

Resultado

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

En `COMPLETE`, el suscriptor solicita un elemento, pide otro después de `10` y recibe `onComplete` después de `20`. En `INVALID`, `request(0)` provoca `onError` sin que se publique ningún elemento. En `CANCEL`, el suscriptor cancela tras el único elemento publicado. El programa espera el evento previsto en lugar de hacer una pausa fija: `close()` no espera a que terminen todas las llamadas a los suscriptores y el caso de cancelación no espera ninguna señal terminal.

Lecciones relacionadas

  • Java · Lección 44 · Avanzado · Versión: 2

Fuentes