Package io.axoniq.framework.springcloud.query

Class SseQueryResponseSink

java.lang.Object
io.axoniq.framework.springcloud.query.SseQueryResponseSink
All Implemented Interfaces:
QueryResponseSink
public class SseQueryResponseSink extends Object implements QueryResponseSink
Writes a query's responses to the member that asked, as events of a Server-Sent Events stream.

Each response is written as one event, whose data the container writes with the same message converters that write the body of any other response. Nothing is serialized here.

A write that fails is raised rather than swallowed: it means the member that asked is no longer reading, and the caller releases the query's response stream on the strength of it.

Since:
5.4.0
Author:
Allard Buijze

  • Constructor Summary

    Constructors
    Constructor
    Description
    SseQueryResponseSink(org.springframework.web.servlet.mvc.method.annotation.SseEmitter emitter)
    Constructs an SseQueryResponseSink writing to the given emitter.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    complete()
    Ends the response stream, reporting that the query was answered in full.
    void
    error(QueryDispatchFailure error)
    Ends the response stream, reporting that the query failed.
    void
    keepAlive()
    Writes a comment, which carries nothing but keeps an otherwise idle stream from being closed.
    void
    leaving(String requestIdentifier)
    Ends the response stream, reporting that this member stops answering the subscription query because it is leaving the cluster.
    void
    onUnavailable(Runnable listener)
    Registers a listener to run once this sink can no longer be written to, for a reason other than the query having been answered — the member that asked stopped reading, or waited longer than it was given.
    void
    response(QueryDispatchResponse response)
    Writes one response to the query being answered.
    void
    subscriptionComplete(String requestIdentifier)
    Reports that the subscription query being answered is over: there will never be another update to it.
    void
    update(QueryDispatchResponse update)
    Writes one update to the subscription query being answered.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • SseQueryResponseSink

      public SseQueryResponseSink(org.springframework.web.servlet.mvc.method.annotation.SseEmitter emitter)
      Constructs an SseQueryResponseSink writing to the given emitter.
      Parameters:
      emitter - the emitter carrying the response stream to the member that asked

  • Method Details

    • onUnavailable

      public void onUnavailable(Runnable listener)
      Description copied from interface: QueryResponseSink
      Registers a listener to run once this sink can no longer be written to, for a reason other than the query having been answered — the member that asked stopped reading, or waited longer than it was given.

      Only the sink knows how its transport reports that, which is why the listener is registered here rather than discovered by whatever writes to it. Answering a query that nothing is reading is wasted work, and the handler's response stream would otherwise be held until it happens to produce a response that fails to write — which a handler that has gone quiet never does.

      Specified by:
      onUnavailable in interface QueryResponseSink
      Parameters:
      listener - runs when this sink can no longer be written to

    • response

      public void response(QueryDispatchResponse response)
      Description copied from interface: QueryResponseSink
      Writes one response to the query being answered.
      Specified by:
      response in interface QueryResponseSink
      Parameters:
      response - the response to write

    • update

      public void update(QueryDispatchResponse update)
      Description copied from interface: QueryResponseSink
      Writes one update to the subscription query being answered.

      Distinct from QueryResponseSink.response(QueryDispatchResponse) because the subscriber acts on the two differently: a response belongs to the initial result, an update is a change after it.

      Specified by:
      update in interface QueryResponseSink
      Parameters:
      update - the update to write

    • subscriptionComplete

      public void subscriptionComplete(String requestIdentifier)
      Description copied from interface: QueryResponseSink
      Reports that the subscription query being answered is over: there will never be another update to it.

      Distinct from QueryResponseSink.leaving(String), which says only that this member stops answering, and from the stream merely ending, which fails the subscription. This says the subscription itself has run its course, and the subscriber stops waiting on every other member too.

      Specified by:
      subscriptionComplete in interface QueryResponseSink
      Parameters:
      requestIdentifier - the identifier of the subscription query that is over

    • leaving

      public void leaving(String requestIdentifier)
      Description copied from interface: QueryResponseSink
      Ends the response stream, reporting that this member stops answering the subscription query because it is leaving the cluster.

      Distinct from QueryResponseSink.subscriptionComplete(String), which ends the subscription for every member, and from QueryResponseSink.error(QueryDispatchFailure), which fails it. This ends only this member's part: it has stopped emitting updates, so the subscriber carries on with the members that remain. Also distinct from the stream merely ending, which the subscriber cannot tell apart from a lost connection and so treats as a failure.

      Specified by:
      leaving in interface QueryResponseSink
      Parameters:
      requestIdentifier - the identifier of the subscription query this member stops answering

    • error

      public void error(QueryDispatchFailure error)
      Description copied from interface: QueryResponseSink
      Ends the response stream, reporting that the query failed.
      Specified by:
      error in interface QueryResponseSink
      Parameters:
      error - the failure that ended the response stream

    • complete

      public void complete()
      Description copied from interface: QueryResponseSink
      Ends the response stream, reporting that the query was answered in full.
      Specified by:
      complete in interface QueryResponseSink

    • keepAlive

      public void keepAlive()
      Writes a comment, which carries nothing but keeps an otherwise idle stream from being closed.

      A subscription query may go a long time without producing an update, and an idle connection is what a load balancer, proxy or NAT table reclaims. A comment is the Server-Sent Events way of saying nothing: a reader following the specification discards it, and this member learns the subscriber is gone when the write fails.

      Throws:
      ResponseStreamClosedException - when the member that asked has stopped reading