CKTIS / Java
Contratos de Java Flow: subscrição, procura e conclusão
Aprende a estabelecer uma subscrição Flow em Java SE 21, a receber elementos com procura limitada e a distinguir a conclusão normal, o erro e o cancelamento.
Versão: Java SE 21
Sintaxe
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();Em Java SE 21, os tipos Flow pertencem ao pacote java.util.concurrent. Flow.Publisher<T>.subscribe aceita um Flow.Subscriber<? super T>, ou seja, um subscritor capaz de tratar T ou um supertipo. Se o registo for bem-sucedido, o publicador entrega uma nova subscrição a onSubscribe(Flow.Subscription) antes de qualquer outra chamada para essa subscrição. Passar null a subscribe lança NullPointerException. Um registo duplicado quando o subscritor já está inscrito, ou um registo rejeitado pelas regras do publicador, é comunicado através de onError com IllegalStateException.
O subscritor guarda a referência em onSubscribe e usa-a para chamar request(long n). Um n positivo soma-se à procura pendente, em vez de a substituir. Cada onNext(T item) entrega um elemento e consome uma unidade de procura limitada. Chamar request(1) depois de processar um elemento permite recebê-los um de cada vez. A procura limita a entrega, não a capacidade do buffer do publicador. Long.MAX_VALUE pode ser tratado como procura praticamente ilimitada. Numa subscrição ativa, n <= 0 origina um sinal onError com IllegalArgumentException, e não uma exceção lançada de forma síncrona por request.
onComplete() indica a conclusão normal; onError(Throwable) indica uma falha irrecuperável. Estes sinais não consomem procura de elementos. São mutuamente exclusivos e, depois de um deles, não há mais chamadas para essa subscrição. As chamadas ao subscritor para uma dada subscrição obedecem à relação happens-before, mas não têm de decorrer na mesma thread. Não deixes escapar exceções destes métodos: o contrato não garante a recuperação nem uma notificação separada através de onError.
cancel() afeta apenas a subscrição em causa. A entrega é interrompida na medida do possível, mas não necessariamente de imediato: podem ainda chegar sinais que já estavam em trânsito. Cancelar não é o mesmo que concluir normalmente; depois do cancelamento, não esperes por onComplete() nem por onError(Throwable). O exemplo implementa um subscritor e delega a gestão da subscrição e a entrega no SubmissionPublisher da biblioteca.
Exemplos
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
Em `COMPLETE`, o subscritor pede um elemento, pede mais um depois de `10` e recebe `onComplete` depois de `20`. Em `INVALID`, `request(0)` origina `onError` sem que se publique qualquer elemento. Em `CANCEL`, o subscritor cancela após o único elemento publicado. O programa espera pelo evento previsto em vez de fazer uma pausa fixa: `close()` não espera pela conclusão de todas as chamadas aos subscritores e o caso de cancelamento não espera por um sinal terminal.
Lições relacionadas
- Java · Lição 44 · Avançado · Versão: 2