io.smallrye.reactive.messaging.MutinyEmitter Maven / Gradle / Ivy
package io.smallrye.reactive.messaging;
import org.eclipse.microprofile.reactive.messaging.Channel;
import org.eclipse.microprofile.reactive.messaging.Message;
import org.eclipse.microprofile.reactive.messaging.OnOverflow;
import io.smallrye.common.annotation.CheckReturnValue;
import io.smallrye.mutiny.Uni;
import io.smallrye.mutiny.subscription.Cancellable;
/**
* Interface used to feed a channel from an imperative piece of code.
*
* Instances are injected using:
*
*
* @Inject
* @Channel("my-channel")
* MutinyEmitter<String> emitter;
*
*
* You can use an injected emitter to send either payloads or
* {@link org.eclipse.microprofile.reactive.messaging.Message Messages}.
*
* The name of the channel (given in the {@link Channel Channel annotation})
* indicates which channel is fed. It must match the name used in a method using
* {@link org.eclipse.microprofile.reactive.messaging.Incoming @Incoming} or an
* outgoing channel configured in the application configuration.
*
* The {@link OnOverflow OnOverflow annotation} can be used to configure what to do if
* messages are sent using the `MutinyEmitter` when a downstream subscriber hasn't requested
* more messages.
*
* @param type of payload
*/
public interface MutinyEmitter extends EmitterType {
/**
* Sends a payload to the channel.
*
* A {@link Message} object will be created to hold the payload and the returned {@code Uni}
* can be subscribed to for triggering the send.
* When subscribed, a {@code null} item will be passed to the {@code Uni} when the
* {@code Message} is acknowledged. If the {@code Message} is never acknowledged, then the {@code Uni} will
* never be completed.
*
* The {@code Message} will not be sent to the channel until the {@code Uni} has been subscribed to:
*
*
* emitter.send("a").subscribe().with(x -> {
* });
*
*
* @param payload the thing to send, must not be {@code null}
* @return the {@code Uni}, that requires subscription to send the {@link Message}.
* @throws IllegalStateException if the channel has been cancelled or terminated or if an overflow strategy of
* {@link OnOverflow.Strategy#THROW_EXCEPTION THROW_EXCEPTION} or {@link OnOverflow.Strategy#BUFFER BUFFER} is
* configured and the emitter overflows.
*/
@CheckReturnValue
Uni send(T payload);
/**
* Sends a payload to the channel.
*
* A {@link Message} object will be created to hold the payload.
*
* Execution will block waiting for the resulting {@code Message} to be acknowledged before returning.
*
* @param payload the thing to send, must not be {@code null}
* @throws IllegalStateException if the channel has been cancelled or terminated or if an overflow strategy of
* {@link OnOverflow.Strategy#THROW_EXCEPTION THROW_EXCEPTION} or {@link OnOverflow.Strategy#BUFFER BUFFER} is
* configured and the emitter overflows.
*/
void sendAndAwait(T payload);
/**
* Sends a payload to the channel without waiting for acknowledgement.
*
* A {@link Message} object will be created to hold the payload.
*
* @param payload the thing to send, must not be {@code null}
* @return the {@code Cancellable} from the subscribed {@code Uni}.
* @throws IllegalStateException if the channel has been cancelled or terminated or if an overflow strategy of
* {@link OnOverflow.Strategy#THROW_EXCEPTION THROW_EXCEPTION} or {@link OnOverflow.Strategy#BUFFER BUFFER} is
* configured and the emitter overflows.
*/
Cancellable sendAndForget(T payload);
/**
* Sends a message to the channel.
*
* @param the Message type
* @param msg the Message to send, must not be {@code null}
* @deprecated use {{@link #sendMessageAndForget(Message)}}
* @throws IllegalStateException if the channel has been cancelled or terminated or if an overflow strategy of
* {@link OnOverflow.Strategy#THROW_EXCEPTION THROW_EXCEPTION} or {@link OnOverflow.Strategy#BUFFER BUFFER} is
* configured and the emitter overflows.
*/
@Deprecated
> void send(M msg);
/**
* Sends a message to the channel.
*
* @param the Message type
* @param msg the Message to send, must not be {@code null}
* @return the {@code Uni}, that requires subscription to send the {@link Message}.
* @throws IllegalStateException if the channel has been cancelled or terminated or if an overflow strategy of
* {@link OnOverflow.Strategy#THROW_EXCEPTION THROW_EXCEPTION} or {@link OnOverflow.Strategy#BUFFER BUFFER} is
* configured and the emitter overflows.
*/
> Uni sendMessage(M msg);
/**
* Sends a message to the channel.
*
* Execution will block waiting for the resulting {@code Message} to be acknowledged before returning.
*
* @param the Message type
* @param msg the Message to send, must not be {@code null}
* @throws IllegalStateException if the channel has been cancelled or terminated or if an overflow strategy of
* {@link OnOverflow.Strategy#THROW_EXCEPTION THROW_EXCEPTION} or {@link OnOverflow.Strategy#BUFFER BUFFER} is
* configured and the emitter overflows.
*/
> void sendMessageAndAwait(M msg);
/**
* Sends a message to the channel without waiting for acknowledgement.
*
* @param the Message type
* @param msg the Message to send, must not be {@code null}
* @return the {@code Cancellable} from the subscribed {@code Uni}.
* @throws IllegalStateException if the channel has been cancelled or terminated or if an overflow strategy of
* {@link OnOverflow.Strategy#THROW_EXCEPTION THROW_EXCEPTION} or {@link OnOverflow.Strategy#BUFFER BUFFER} is
* configured and the emitter overflows.
*/
> Cancellable sendMessageAndForget(M msg);
/**
* Sends the completion event to the channel indicating that no other events will be sent afterward.
*/
void complete();
/**
* Sends a failure event to the channel. No more events will be sent afterward.
*
* @param e the exception, must not be {@code null}
*/
void error(Exception e);
/**
* @return {@code true} if the emitter has been terminated or the subscription cancelled.
*/
boolean isCancelled();
/**
* @return {@code true} if one or more subscribers request messages from the corresponding channel where the emitter
* connects to,
* return {@code false} otherwise.
*/
boolean hasRequests();
}