reactor.core.observability

Interface SignalListener<T>

All Known Implementing Classes:

DefaultSignalListener

public interface SignalListener<T>

A listener which combines various handlers to be triggered per the corresponding Flux or Mono signals. This is similar to the "side effect" operators in Flux and Mono, but in a single listener class. SignalListener are created by a SignalListenerFactory, which is tied to a particular Publisher. Each time a new Subscriber subscribes to that Publisher, the factory creates an associated SignalListener.

Both publisher-to-subscriber events and subscription events are handled. Methods are closer to the side-effect doOnXxx operators than to Subscriber and Subscription methods, in order to avoid misconstruing this for an actual Reactive Streams implementation. The actual downstream Subscriber and upstream Subscription are intentionally not exposed to avoid any influence on the observed sequence.

Author:

Simon Baslé

Method Summary

Modifier and Type	Method and Description
default Context	addToContext(Context originalContext) In some cases, the tap operation should alter the Context exposed by the operator in order to store additional data.
void	doAfterComplete() Handle graceful onComplete sequence termination, after onComplete has been propagated downstream.
void	doAfterError(Throwable error) Handle onError sequence termination after onError has been propagated downstream.
void	doFinally(SignalType terminationType) Handle terminal signals after the signals have been propagated, as the final step.
void	doFirst() Handle the very beginning of the Subscriber-Publisher interaction.
void	doOnCancel() Handle the downstream cancelling its currently observed Subscription.
void	doOnComplete() Handle graceful onComplete sequence termination.
void	doOnError(Throwable error) Handle onError sequence termination.
void	doOnFusion(int negotiatedFusion) Handle the negotiation of fusion between two Fuseable operators.
void	doOnMalformedOnComplete() Handle malformed Subscriber.onComplete(), which means the sequence has already terminated via Subscriber.onComplete() or Subscriber.onError(Throwable).
void	doOnMalformedOnError(Throwable error) Handle malformed Subscriber.onError(Throwable), which means the sequence has already terminated via Subscriber.onComplete() or Subscriber.onError(Throwable).
void	doOnMalformedOnNext(T value) Handle malformed Subscriber.onNext(Object), which are onNext happening after the sequence has already terminated via Subscriber.onComplete() or Subscriber.onError(Throwable).
void	doOnNext(T value) Handle a new value emission from the source.
void	doOnRequest(long requested) Handle a new request made by the downstream, exposing the demand.
void	doOnSubscription() Handle the fact that the upstream Publisher acknowledged Subscription.
void	handleListenerError(Throwable listenerError) A special handler for exceptions thrown from all the other handlers.

Method Detail

doFirst

void doFirst()
      throws Throwable

Handle the very beginning of the Subscriber-Publisher interaction. This handler is invoked right before subscribing to the parent Publisher, as a downstream Subscriber has called Publisher.subscribe(Subscriber).

Once the Publisher has acknowledged with a Subscription, the doOnSubscription() handler will be invoked before that Subscription is passed down.

Throws:

Throwable

See Also:

doOnSubscription()

doFinally

void doFinally(SignalType terminationType)
        throws Throwable

Handle terminal signals after the signals have been propagated, as the final step. Only SignalType.ON_COMPLETE, SignalType.ON_ERROR or SignalType.CANCEL can be passed. This handler is invoked AFTER the terminal signal has been propagated, and if relevant AFTER the doAfterComplete() or doAfterError(Throwable) events. If any doOnXxx handler throws, this handler is NOT invoked (see handleListenerError(Throwable) instead).

Throws:

Throwable

See Also:

handleListenerError(Throwable)

doOnSubscription

void doOnSubscription()
               throws Throwable

Handle the fact that the upstream Publisher acknowledged Subscription. The Subscription is intentionally not exposed in order to avoid manipulation by the observer.

While doFirst() is invoked right as the downstream Subscriber is registered, this method is invoked as the upstream answers back with a Subscription (and before that same Subscription is passed downstream).

Throws:

Throwable

See Also:

doFirst()

doOnFusion

void doOnFusion(int negotiatedFusion)
         throws Throwable

Handle the negotiation of fusion between two Fuseable operators. As the downstream operator requests fusion, the upstream answers back with the compatible level of fusion it can handle. This negotiatedFusion code is passed to this handler right before it is propagated downstream.

Parameters:

negotiatedFusion - the final fusion mode negotiated by the upstream operator in response to a fusion request from downstream

Throws:

Throwable

doOnRequest

void doOnRequest(long requested)
          throws Throwable

Handle a new request made by the downstream, exposing the demand.

This is invoked before the request is propagated upstream.

Parameters:

requested - the downstream demand

Throws:

Throwable

doOnCancel

void doOnCancel()
         throws Throwable

Handle the downstream cancelling its currently observed Subscription.

This handler is invoked before propagating the cancellation upstream, while doFinally(SignalType) is invoked right after the cancellation has been propagated upstream.

Throws:

Throwable

See Also:

doFinally(SignalType)

doOnNext

void doOnNext(T value)
       throws Throwable

Handle a new value emission from the source.

This handler is invoked before propagating the value downstream.

Parameters:

value - the emitted value

Throws:

Throwable

doOnComplete

void doOnComplete()
           throws Throwable

Handle graceful onComplete sequence termination.

This handler is invoked before propagating the completion downstream, while both doAfterComplete() and doFinally(SignalType) are invoked after.

Throws:

Throwable

See Also:

doAfterComplete(), doFinally(SignalType)

doOnError

void doOnError(Throwable error)
        throws Throwable

Handle onError sequence termination.

This handler is invoked before propagating the error downstream, while both doAfterError(Throwable) and doFinally(SignalType) are invoked after.

Parameters:

error - the exception that terminated the sequence

Throws:

Throwable

See Also:

doAfterError(Throwable), doFinally(SignalType)

doAfterComplete

void doAfterComplete()
              throws Throwable

Handle graceful onComplete sequence termination, after onComplete has been propagated downstream.

This handler is invoked after propagating the completion downstream, similar to doFinally(SignalType) and unlike doOnComplete().

Throws:

Throwable

doAfterError

void doAfterError(Throwable error)
           throws Throwable

Handle onError sequence termination after onError has been propagated downstream.

This handler is invoked after propagating the error downstream, similar to doFinally(SignalType) and unlike doOnError(Throwable).

Parameters:

error - the exception that terminated the sequence

Throws:

Throwable

doOnMalformedOnNext

void doOnMalformedOnNext(T value)
                  throws Throwable

Handle malformed Subscriber.onNext(Object), which are onNext happening after the sequence has already terminated via Subscriber.onComplete() or Subscriber.onError(Throwable). Note that after this handler is invoked, the value is automatically dropped.

If this handler fails with an exception, that exception is dropped before the value is also dropped.

Parameters:

value - the value for which an emission was attempted (which will be automatically dropped afterwards)

Throws:

Throwable

doOnMalformedOnError

void doOnMalformedOnError(Throwable error)
                   throws Throwable

Handle malformed Subscriber.onError(Throwable), which means the sequence has already terminated via Subscriber.onComplete() or Subscriber.onError(Throwable). Note that after this handler is invoked, the exception is automatically dropped.

If this handler fails with an exception, that exception is dropped before the original onError exception is also dropped.

Parameters:

error - the extraneous exception (which will be automatically dropped afterwards)

Throws:

Throwable

doOnMalformedOnComplete

void doOnMalformedOnComplete()
                      throws Throwable

Handle malformed Subscriber.onComplete(), which means the sequence has already terminated via Subscriber.onComplete() or Subscriber.onError(Throwable).

If this handler fails with an exception, that exception is dropped.

Throws:

Throwable

handleListenerError

void handleListenerError(Throwable listenerError)

A special handler for exceptions thrown from all the other handlers. This method MUST return normally, i.e. it MUST NOT throw. When a SignalListener handler fails, callers are expected to first invoke this method then to propagate the listenerError downstream if that is possible, terminating the original sequence with the listenerError.

Typically, this special handler is intended for a last chance at processing the error despite the fact that doFinally(SignalType) is not triggered on handler errors. For example, recording the error in a metrics backend or cleaning up state that would otherwise be cleaned up by doFinally(SignalType).

Parameters:

listenerError - the exception thrown from a SignalListener handler method

addToContext

default Context addToContext(Context originalContext)

In some cases, the tap operation should alter the Context exposed by the operator in order to store additional data. This method is invoked when the tap subscriber is created, which is between the invocation of doFirst() and the invocation of doOnSubscription(). Generally, only addition of new keys should be performed on the downstream original Context. Extra care should be exercised if any pre-existing key is to be removed or replaced.

Parameters:

originalContext - the original downstream operator's Context

Returns:

the Context to use and expose upstream